Tesouro em Foco · v1

Os mesmos números, em JSON.

Mesma engine do simulador, exposta como endpoint público. Sem autenticação, CORS aberto, rate limit de 30 req/min por IP. Base URL: https://api.tesouroemfoco.com.

Convenção de formato

Todo campo de taxa (annualRate de entrada e rate de saída em qualquer endpoint) é uma fração decimal como string — '0.0737' significa 7,37% a.a., '0.0005' significa 0,05% a.a. Nunca é percentual cheio: '7.37' seria interpretado como 737% a.a.

POST /v1/simulate

Simula um único título.

curl -X POST https://api.tesouroemfoco.com/v1/simulate \
  -H 'Content-Type: application/json' \
  -d '{
    "bondType": "prefixado",
    "tradeDate": "2026-04-13",
    "annualRate": "0.1423",
    "maturityDate": "2027-01-01"
  }'

POST /v1/simulate/bulk

Lote de até 10 itens (5 quando algum tem includeSchedule: true). Cada linha responde como { input, ok, result | error } — erros isolados não afetam o batch.

curl -X POST https://api.tesouroemfoco.com/v1/simulate/bulk \
  -H 'Content-Type: application/json' \
  -d '{
    "items": [
      {
        "bondType": "prefixado",
        "tradeDate": "2026-04-13",
        "annualRate": "0.1423",
        "maturityDate": "2027-01-01"
      },
      {
        "bondType": "ipca-mais",
        "tradeDate": "2026-04-13",
        "annualRate": "0.0723",
        "maturityDate": "2035-05-15"
      }
    ]
  }'

GET /v1/catalog

Catálogo completo agrupado por família. Renda+/Educa+ trazem conversionDate e installments.

curl https://api.tesouroemfoco.com/v1/catalog

POST /v1/price-history/lookup

Consulta pontual em lote — até 50 tuplas de productId + maturityYear + referenceDate. Retorna taxa e PU de compra/venda publicados pelo Tesouro Transparente.

curl -X POST https://api.tesouroemfoco.com/v1/price-history/lookup \
  -H 'Content-Type: application/json' \
  -d '{
    "queries": [
      {
        "productId": "ipca-mais",
        "maturityYear": 2035,
        "referenceDate": "2024-03-15"
      }
    ]
  }'

POST /v1/price-history/series

Série temporal ou estatísticas agregadas (min/max/média) de um título em uma janela de datas. Use aggregate: "stats" para resumo compacto ou step: "monthly" para sub-amostragem.

curl -X POST https://api.tesouroemfoco.com/v1/price-history/series \
  -H 'Content-Type: application/json' \
  -d '{
    "productId": "ipca-mais",
    "maturityYear": 2035,
    "from": "2024-01-01",
    "to": "2024-12-31",
    "aggregate": "stats"
  }'

POST /v1/live-quotes/lookup

Cotações vivas (compra/venda atuais) do site do Tesouro Direto — dataset diferente do histórico STN, atualizado a cada 30 min. Até 50 tuplas por chamada. Para Renda+/Educa+, passe conversionYear (ano do rótulo) OU maturityYear (vencimento), nunca ambos. Pode retornar 503 em caso de indisponibilidade temporária do feed.

curl -X POST https://api.tesouroemfoco.com/v1/live-quotes/lookup \
  -H 'Content-Type: application/json' \
  -d '{
    "queries": [
      { "productId": "ipca-mais", "maturityYear": 2035 },
      { "productId": "educa-mais", "conversionYear": 2027 }
    ]
  }'

GET /v1/health

Liveness check. Devolve version (semver) e revision (commit hash do build).

curl https://api.tesouroemfoco.com/v1/health

Erros

Todo erro vem como { error: { code, message, issues? } }. O code é estável; o status HTTP é uma derivação dele.

Códigos de erro da API.
Code	Status	Quando
VALIDATION_ERROR	400	Body Zod inválido (issues[] no response)
INVALID_XOR_ARGS	400	conversionYear/maturityYear fornecidos juntos
INVALID_ISO_DATE	400	Data fora do formato YYYY-MM-DD
DATE_OUT_OF_RANGE	400	Data fora do calendário disponível
PRODUCT_NOT_FOUND	404	Bond não está no catálogo (Renda+/Educa+)
SETTLEMENT_AFTER_MATURITY	422	Liquidação após o vencimento
INVALID_VNA	422	VNA não disponível para a data
RATE_LIMITED	429	Excedeu 30 req/min — Retry-After: 60

OpenAPI

Spec hospedado em /v1/openapi.json.

Respostas da API são técnicas e informativas. Não substituem canais oficiais do Tesouro nem constituem recomendação de investimento ou consultoria profissional.