Visão geral / API do TributoXAPI fiscal · v1

API do TributoX

Rode sugestões fiscais fundamentadas de forma programática. Você envia a demanda, o motor responde de forma assíncrona com a análise, a base legal citada e um nível de confiança.

O acesso é liberado para parceiros: uma chave de sandbox para testar, ou o acesso completo após uma demonstração, para avaliar antes de contratar. A especificação campo a campo é fechada com cada parceiro; esta página é a referência pública do contrato atual.

Pedir chave de sandbox

Antes de começar

O que você precisa

✓Uma chave de API, liberada por sandbox ou após demonstração
✓Um backend para chamar. A chave nunca deve chegar ao navegador
✓A demanda fiscal em texto e, opcional, um contexto (CNPJ, regime)

O que instalar

Nada. Não existe SDK nem CLI: é HTTP com JSON, então use o que a sua linguagem já tem.

Pacotes de terceiros com o nome tributox no npm ou PyPI não são nossos e não funcionam com esta API.

Autenticação

Máquina a máquina, por chave de API. Mande a chave no header Authorization: Bearer <chave> ou X-API-Key: <chave>. Nenhuma chamada é anônima; sem chave válida, a API responde 401.

Chave de API

Emitida para a sua conta e usada no seu backend. Validada por hash: a chave em claro nunca é comparada direto nem guardada.

Enviada em Authorization: Bearer ou X-API-Key
Revogação imediata: chave desativada para de funcionar
Consumo medido por chave, para atribuição por consumidor

cURLPOST /api/fiscal/v1/sugerir

curl https://api.tributox.studiolabsai.com/api/fiscal/v1/sugerir \
  -H "Authorization: Bearer $TRIBUTOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "demanda": "Empresa de serviços no Simples. O Fator R muda o anexo?",
    "contexto": { "cnpj": "11.222.333/0001-85", "regime": "simples" }
  }'

# 202 Accepted
# { "job_id": "8f3k…", "status": "pendente" }

Endpoints

Base https://api.tributox.studiolabsai.com. A versão fica no path (/api/fiscal/v1).

MétodoRecursoPara que serve

POST/api/fiscal/v1/sugerirCria uma sugestão fiscal fundamentada. Retorna 202 e o job_id; a geração roda em background.

GET/api/fiscal/v1/sugestao/{job_id}Busca o resultado pelo job_id. 202 enquanto processa, 200 com o resultado quando concluído.

Fluxo assíncrono

Uma sugestão leva alguns segundos, então a API é assíncrona. Você cria, recebe um job_id e consulta o resultado por polling. A notificação por webhook está no roadmap.

01CriarPOST /sugerir com a demanda. Retorna 202 e o job_id, com status pendente.

02ProcessarO agente busca a norma, gera e aplica o guard de citação. Status processando.

03ConsultarGET /sugestao/{job_id}. Enquanto roda, devolve 202. Polling: consulte de tempos em tempos.

04LerQuando concluído, o GET devolve 200 com o resultado estruturado e a base legal.

cURLGET /api/fiscal/v1/sugestao/{job_id}

curl https://api.tributox.studiolabsai.com/api/fiscal/v1/sugestao/8f3k… \
  -H "Authorization: Bearer $TRIBUTOX_API_KEY"

# 202 enquanto processa · 200 quando concluído

Resposta estruturada

Nunca um bloco de texto solto. O resultado traz sugestao, regras, campos_afetados, excecoes, base_legal e um nível de confianca.

Fail-closed: quando a base não sustenta a resposta, vem confianca: baixa, base_legal: [] e a sugestão pede verificação. Nenhuma lei é inventada.

Resultado200 OK

{
  "job_id": "8f3k…",
  "status": "concluido",
  "resultado": {
    "sugestao": "Com Fator R ≥ 28%, a atividade tributa pelo Anexo III…",
    "regras": "Fator R = folha 12m / receita 12m (LC 123/2006).",
    "campos_afetados": ["anexo", "aliquota_efetiva"],
    "excecoes": ["Fator R apurado mês a mês…"],
    "base_legal": ["LC 123/2006, art. 18, §5º-J"],
    "confianca": "alta",
    "aviso": "Confirme a folha dos últimos 12 meses."
  }
}

Limites e consumo

O consumo é medido por chave (custo por job), para atribuição e faturamento por consumidor. Hoje o limite de volume é medido, não cortado no request; o teto e o corte são definidos em contrato. Volumes de sandbox e de produção saem na conversa com o time.

Números fixos de requisições por minuto e de análises por dia não são publicados como contrato: eles são definidos por parceiro. Peça os limites do seu caso junto com a chave de sandbox.

Erros

StatusMotivoO que fazer

401chave ausente ou inválidaSem chave, ou chave inválida ou revogada. Nenhuma chamada é anônima.

422demanda obrigatóriaO corpo veio sem o campo demanda.

404job não encontradoJob inexistente ou de outro consumidor. Por isolamento, não é 403 (não vaza a existência de job alheio).

O 202 não é erro: é a resposta de criação e a de consulta enquanto o job ainda processa.

Chaves e isolamentoA chave é validada por hash (sha256); revogar é desativar a chave. Cada consumidor só enxerga os próprios jobs.

Segurança e LGPDDados no Brasil, criptografia em trânsito e em repouso. DPA disponível para parceiros.

VersionamentoContrato versionado no path (/api/fiscal/v1). Mudança incompatível só em nova versão.

Roadmap

ainda não disponível

O que está no plano da API, para você saber o que vem, sem confundir com o contrato atual:

Notificação por webhook do resultado (hoje o acompanhamento é por polling).
Mais tipos de análise (enquadramento, simulação da Reforma, oportunidades) via endpoint.
LexFeed por endpoint e por push.

Cobertura

Pedir chave de sandboxUma demonstração de 20 minutos libera o sandbox e a especificação completa para você avaliar antes de contratar.Preço por volumeA integração é comercial, por volume e contrato, definida com o time.