API & MCP — Valide seu XML por integração

Tudo que a função Valide seu XML faz pela interface, você pode fazer por integração: no seu pipeline interno, num script de pré-envio ou direto de um agente de IA via MCP. Mesmo motor, mesmo laudo, mesma privacidade — o arquivo é analisado em memória e descartado na hora; nada é guardado, nada vai à CVM por aqui.

1 · Autenticação — sua chave de API

Crie sua conta (ou entre) no Tomé.

Na página Sua conta, seção "Chave de API", clique em gerar chave. A chave (tome_…) aparece uma única vez — guarde num cofre de segredos. Gerar outra revoga a anterior.

Envie a chave em toda requisição, no header Authorization: Bearer <chave>. A mesma chave vale pra API e pro MCP.

2 · API REST

POST /api/v1/validar-xml

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, ... }
}

HTTP	Significado
200	Laudo emitido (pode conter apontamentos 🟡/🔵)
422	Laudo emitido com problema hard-estrutural (🔴 — ex.: o arquivo é uma página HTML, não o XML)
401	Chave ausente/inválida/revogada
413	Arquivo acima de 5 MB
429	Limite de uso da chave (padrão 30/min) — honre o `Retry-After`
503	Motor indisponível — tente de novo

3 · MCP (Model Context Protocol)

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

4 · Limites honestos

Este check é preventivo, não o validador oficial. Ele cobre hoje o informe mensal de FIDC (leiaute FNET). A CVM não publica o XSD oficial do informe — a conferência de estrutura usa um esquema que derivamos do leiaute publicado. Passar aqui reduz muito o risco de recusa e de reapresentação, mas não garante o aceite do Fundos.net. O laudo aponta FATOS do documento ("as faixas somam X, o total declara Y"), nunca veredito regulatório.

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.

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.