API & MCP.

Três funções do Tomé funcionam por integração: o Valide seu XML (pré-envio de informe ao Fundos.net) e o Export por administradora (o consolidado dos fundos — FIDC, FII e FIF — em planilha, direto pro seu cruzamento), com a chave de API tome_…; e a Planilha viva (DY real 12m, P/VP e PL de um FII direto no seu Google Sheets ou Excel, seção 6), com uma chave própria tomeplan_…. No seu pipeline interno, num script agendado ou direto de um agente de IA via MCP. Mesmo motor das interfaces, mesmos dados, mesmas regras.

Multipart, com o XML do informe no campo arquivo. O nome do arquivo é ignorado de propósito (não o usamos pra nada). Teto: 5 MB.

curl -X POST https://www.agentetome.com/api/v1/validar-xml \
  -H "Authorization: Bearer tome_SUA_CHAVE" \
  -F "arquivo=@informe_mensal.xml"

Resposta — o laudo em 4 níveis (mesmo da interface):

{
  "ok": true,                       // false = problema hard-estrutural (HTTP 422)
  "leiaute": "6.6",                 // versão do leiaute detectada no documento
  "provavel_recusa": [ ... ],       // 🔴 o que tende a travar o envio no protocolo
  "schema_fnet":     { ... },       // 🟠 estrutura vs leiaute (esquema derivado)
  "vale_conferir":   [ ... ],       // 🟡 contas internas que não fecham
  "informacao":      [ ... ],       // 🔵 fatos que valem registro (ex.: PL negativo)
  "composicao":      { ... },       // classes de cota: soma vs PL declarado
  "contadores": { "qt_bloqueante": 0, "qt_conferir": 0, "qt_ok": 5, ... }
}

Pra agentes de IA (Claude, e qualquer cliente MCP por HTTP): o Tomé expõe um servidor MCP com a tool validar_informe_xml. Endpoint único, JSON-RPC 2.0:

POST https://www.agentetome.com/api/mcp
Authorization: Bearer tome_SUA_CHAVE
Content-Type: application/json

Métodos: initialize, tools/list e tools/call. A tool recebe o XML em base64:

{
  "jsonrpc": "2.0", "id": 1, "method": "tools/call",
  "params": {
    "name": "validar_informe_xml",
    "arguments": { "xml_base64": "<conteúdo do XML em base64>" }
  }
}

A resposta vem em result.content[0].text com o MESMO laudo JSON da API (e isError: true quando o problema é hard-estrutural). Exemplo de configuração num cliente MCP genérico por HTTP:

{
  "mcpServers": {
    "tome-valide-xml": {
      "url": "https://www.agentetome.com/api/mcp",
      "headers": { "Authorization": "Bearer tome_SUA_CHAVE" }
    }
  }
}

O mesmo pacote da página /exportar, sem humano clicando em download: o consolidado dos fundos de uma administradora (1 linha por fundo×competência, chave de junção CNPJ de 14 dígitos como texto + competência YYYY-MM), satélites de classes e aging (FIDC) e a visão de qualidade operacional. Dado 100% público (CVM/FNET), schema versionado (v1: coluna não some nem renomeia; adição só no fim), célula vazia = não declarado.

curl -L -o export-ot.zip \
  -H "Authorization: Bearer tome_SUA_CHAVE" \
  "https://www.agentetome.com/api/v1/export/admin?admin=oliveira%20trust&formato=csv&corte=competencia&competencia=2026-06"

Resposta — o arquivo binário (Content-Disposition: attachment). O header X-Tome-Export-Cache: hit|miss conta se veio do cache do dia (repetir o mesmo pedido no mesmo dia não custa nada). O contrato do pacote — grafias que casaram, janela de dados, notas de método, contagem de linhas por arquivo — vai no manifest.json (dentro do ZIP) e também em endpoint próprio, útil pra checar antes de baixar (ou quando consome XLSX):

curl -H "Authorization: Bearer tome_SUA_CHAVE" \
  "https://www.agentetome.com/api/v1/export/admin/manifest?admin=oliveira%20trust&corte=recente"

No mesmo servidor MCP da seção 3 (mesmo endpoint, mesma chave). A tool recebe admin / corte / competencia / formato e devolve um link de download temporário (validade 1h) — nunca o binário dentro do JSON:

{
  "jsonrpc": "2.0", "id": 2, "method": "tools/call",
  "params": {
    "name": "exportar_admin",
    "arguments": { "admin": "oliveira trust", "corte": "recente", "formato": "csv" }
  }
}

Resposta (em result.content[0].text):

{
  "arquivo": "tome-export-oliveira-trust-foto-atual-2026-07-22.zip",
  "formato": "zip_de_csvs",
  "tamanho_bytes": 118742,
  "link_download": "https://www.agentetome.com/api/export/download?t=eyJ…",
  "expira_em": "2026-07-22T18:40:00.000Z",
  "como_baixar": "GET simples no link (sem header de auth — a assinatura no token é a credencial; validade 1h).",
  "manifest": { "schema_versao": 1, "filtro": { … }, "arquivos": { … }, "notas_metodo": { … } }
}

O link é assinado (HMAC) e expira em 1 hora; qualquer um com o link baixa o arquivo dentro da validade — trate-o como o próprio arquivo. A geração conta no limite de 10/hora da chave; o download pelo link, não.

Privacidade por construção: o XML entra, é analisado em memória e descartado — não guardamos o arquivo, o CNPJ nem os valores. O que fica registrado (pra operação do serviço) são só contadores e códigos de regra, sem conteúdo. Nada é enviado à CVM por aqui.

No export: a base cobre o que a CVM/FNET publica e o Tomé já ingeriu — fundo ausente aparece como ausência, e ausência também é informação. No corte recente os meses variam por fundo por design (a coluna competencia acompanha toda linha); dias_atraso usa régua aproximada declarada no manifest. Todo número carrega o informe_id de origem — nada é estimado, nada é preenchido.

Na planilha viva: os limites da chave tomeplan_… estão na tabela da seção 6 — cada teto explicado com o porquê, e as mensagens de erro exatamente como aparecem na célula da sua planilha.

O dado do Tomé DENTRO da sua planilha, atualizando sozinho: DY real 12 meses (soma dos rendimentos por cota em 12 meses fechados ÷ preço B3 — não o DY declarado), P/VP, PL e as flags de honestidade, tudo com fonte por linha. Zero raspagem de site: é a mesma base pública (CVM/FNET + B3 COTAHIST) do chat, servida em CSV por um SELECT.

=IMPORTDATA("https://www.agentetome.com/api/v1/ticker/XPML11.csv?chave=tomeplan_SUA_CHAVE&locale=br")

=IMPORTDATA("https://www.agentetome.com/api/v1/watchlist.csv?chave=tomeplan_SUA_CHAVE&locale=br")

locale=br: com ele o CSV sai com ; de separador e vírgula decimal — o formato que um Sheets/Excel em português entende como NÚMERO. Sem o parâmetro, o CSV é o padrão RFC (, + ponto decimal) — num Sheets pt-BR os números virariam texto (pegadinha clássica do IMPORTDATA). Excel: mesma URL em Dados → Da Web (ou =WEBSERVICE+Power Query) — funciona igual.

Quer ver funcionando antes de criar conta? Este endpoint é aberto e devolve 1 fundo fixo (XPML11), com dado real:

=IMPORTDATA("https://www.agentetome.com/api/v1/ticker/demo.csv?locale=br")

A chave vai na URL (?chave=tomeplan_…) — o IMPORTDATA não envia headers — ou, pra scripts, no header Authorization: Bearer tomeplan_…. A variante .json devolve os mesmos campos com status HTTP real (integração séria usa ela). Cache de 15 minutos do nosso lado (o dado muda 1×/dia); o Google ainda aplica um cache próprio de até ~1h no IMPORTDATA — a planilha pode levar até uma hora pra refletir o dado novo, por conta dele.

Colunas (contrato v1 — coluna não some nem renomeia; adição só no fim):

Célula vazia = valor não declarado — nunca inventamos 0. Nenhuma coluna de recomendação, nota ou score: a pré-análise é sua. Cobertura v1: FII (551 fundos com DY real na base) — FIDC/FIF/CRI-CRA na planilha viva ficam pra uma v2 com colunas próprias por classe.

Limites (e o porquê de cada um):

Varredura automatizada da base (muitos fundos em sequência alfabética) suspende a chave na hora — você reativa sozinho na sua conta na primeira vez. O seu uso do dia (requisições e fundos distintos) fica visível na conta, antes de qualquer limite bater.

Erros — legíveis na célula. As rotas .csv respondem HTTP 200 com uma única célula em português (o Sheets mostraria só "Error: resource at url…"); as rotas .json respondem o status real (401/403/404/429/503) com {codigo, mensagem}. As mensagens, exatamente como aparecem na planilha:

Uso próprio; redistribuição comercial do CSV é proibida. O dado é público e de graça no próprio site — a fonte (fonte_informe_id, competencia_informe, pregao) viaja em cada linha.

Dúvidas ou um caso de uso que a API ainda não cobre? Pergunta pro Tomé no chat — as conversas são lidas por gente.