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 de30 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) é umafraçã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 (preço, cotação, duration; cronograma opcional).

              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"
      }
    ]
  }'

POST/v1/redemption

Simulação de resgate antecipado: lote histórico (price XOR rate) + venda hipotética (rate). Retorna precificação bruta da venda e netReturns (IOF, IR regressivo, custódia B3) como aplicação das regras fiscais — não é aconselhamento.

              curl -X POST https://api.tesouroemfoco.com/v1/redemption \
  -H 'Content-Type: application/json' \
  -d '{
    "bondType": "prefixado",
    "maturityDate": "2029-01-01",
    "lot": { "tradeDate": "2024-06-03", "price": "700.00" },
    "sell": { "tradeDate": "2026-03-10", "rate": "0.13" }
  }'

POST/v1/redemption/bulk

Até 10 cenários de resgate por chamada. Mesmo formato per-item de simulate/bulk ({ input, ok, result | error }).

              curl -X POST https://api.tesouroemfoco.com/v1/redemption/bulk \
  -H 'Content-Type: application/json' \
  -d '{
    "items": [
      {
        "bondType": "prefixado",
        "maturityDate": "2029-01-01",
        "lot": { "tradeDate": "2024-06-03", "price": "700.00" },
        "sell": { "tradeDate": "2026-03-10", "rate": "0.13" }
      }
    ]
  }'

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 | maturityDate | conversionYear) + referenceDate. Retorna taxa e preço unitário (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 de um título em uma janela de datas. aggregate: "stats" devolve min/max/média e, para taxas, percentis p25/p50/p75 (nearest-rank), last e lastPercentile. Pontos crus aceitam step, limit (1–200), offset e order: "desc" — a resposta traz meta.page com o total.

              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/price-history/ranking

Comparação entre títulos do catálogo: para cada papel, onde a taxa mais recente fica na própria história (lastPercentile e percentis nearest-rank por janela). Descrição estatística — não é ranking de atratividade nem recomendação. Só as seis famílias do catálogo (sem selic/igpm). Parâmetros opcionais: windows, side, productId, to.

              curl -X POST https://api.tesouroemfoco.com/v1/price-history/ranking \
  -H 'Content-Type: application/json' \
  -d '{
    "windows": ["1y"],
    "side": "investorBuy"
  }'

POST/v1/live-quotes/lookup

Cotações vivas (compra/venda atuais) do site do Tesouro Direto — dataset diferente do histórico STN, atualizadas a cada hora na janela BRT de pregão (dias úteis). Até 50 tuplas por chamada. Para Renda+/Educa+, passe conversionYear (ano do rótulo) OU maturityYear (vencimento), nunca ambos. Pode retornar 503 se o feed estiver indisponível.

              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

GET/v1/openapi.json

Spec OpenAPI 3.1 gerada a partir dos schemas Zod dos endpoints.

              curl https://api.tesouroemfoco.com/v1/openapi.json

OpenAPI

Spec hospedado em/v1/openapi.json.

Erros

Todo erro vem como{ error: { code, message, issues? } }. Ocode é 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 (qualquer família/ano)
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

Respostas são técnicas e informativas — simulações ou leituras de dados públicos. Não substituem canais oficiais do Tesouro nem constituem recomendação de investimento ou consultoria profissional.