API do TributoX

Integre análises fiscais ao seu software. Você envia a demanda ou a operação e recebe um resultado estruturado, com a análise, a base legal citada e um nível de confiança, pronto para o seu sistema mostrar ao usuário.

A API é uma capacidade contratada. Não há cadastro aberto, chave emitida pelo próprio desenvolvedor, créditos gratuitos nem ambiente público: o acesso começa numa demonstração, passa por proposta e contrato e termina numa credencial exclusiva entregue pelo time. Esta página e a especificação OpenAPI pública (sem chave) são a referência do contrato.

Comece por aqui

1. 01ContrateAgende a demonstração. Depois da proposta e do contrato, o time habilita o seu parceiro.
2. 02Receba a credencialChave exclusiva, com escopos, empresas autorizadas e limites definidos no contrato.
3. 03Chame a APIHTTP com JSON, a chave no backend. Comece pelo /auditar (síncrono) ou pelo /sugerir (assíncrono).
4. 04Leia campo a campoCada decisão vem determinada, inconclusiva ou em revisão necessária, com fundamento e o que falta.

Antes de começar

Processo de contratação

Do primeiro contato ao primeiro consumo, em oito passos. Cada um é conduzido pelo time; nenhum depende de cadastro no site.

1. 01Agende a demonstraçãoPelo mesmo agendamento do site, em /signup. Você mostra o sistema e o caso de uso; o time mostra a análise fiscal funcionando.
2. 02Qualificação comercialO time entende o volume esperado, as empresas atendidas, os escopos necessários e os requisitos de segurança e de dados.
3. 03PropostaProposta com escopos, limites por minuto, cota mensal e vigência. O preço é por volume e contrato, nunca por tabela aberta.
4. 04ContratoAssinatura do contrato, com as condições de tratamento de dados (LGPD) combinadas com o parceiro.
5. 05Habilitação do parceiroO time cadastra o parceiro, as empresas autorizadas e ativa o contrato. Sem essa ativação, nenhuma chave de parceiro funciona.
6. 06Escopos e limites configuradosO time configura o teto de escopos do parceiro, o limite por minuto, a cota mensal e a validade das chaves.
7. 07Credencial exclusiva entregue com segurançaA chave é emitida pelo time, exclusiva do seu sistema, e entregue por canal seguro. Ela aparece uma única vez; guarde no cofre de segredos do seu backend.
8. 08Seu sistema consome a APIA integração roda em produção com a credencial contratada. Revogação, suspensão e rotação passam pelo time, a qualquer momento.

A chave contratada acessa a API real, sem ambiente separado. Durante a integração, use dados fictícios: nada de CNPJ, nota fiscal ou documento real de cliente até a operação começar. A chave nunca deve ir para o navegador nem para o repositório.

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.

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": { "regime": "simples", "uf": "SP" }
  }'

# 202 Accepted
# { "job_id": "3f2b9c1e-7a4d-4e8b-9c2a-1d5e6f7a8b9c", "status": "pendente" }

Exige chave de parceiro contratado, habilitado pelo time. Cada rota pede um escopo; a chave só funciona dentro do teto de escopos do contrato.

HTTP/1.1 403 Forbidden

{ "detail": "A chave nao tem o escopo exigido por esta rota.", "erro": "escopo_insuficiente" }

Exige chave de parceiro contratado. Software houses e ERPs atendem várias empresas com a mesma credencial: o header diz em nome de quem a chamada é feita, e o contrato diz quais empresas o parceiro pode atender.

curl https://api.tributox.studiolabsai.com/api/fiscal/v1/auditar \
  -H "Authorization: Bearer $TRIBUTOX_API_KEY" \
  -H "X-TributoX-CNPJ: 12345678000199" \
  -H "Idempotency-Key: pedido-erp-000123" \
  -H "Content-Type: application/json" \
  -d '{ "entrada": "Venda de produção própria, NCM 84713012, de SP para BA em 2026-03-10, origem 0, para contribuinte do ICMS, emitente no Simples Nacional." }'

# Repetir a mesma chamada devolve a resposta guardada, com o header Idempotent-Replayed: true.

Idempotência (Idempotency-Key)

Repita uma chamada sem duplicar o job nem o consumo, por exemplo depois de um timeout de rede. Vale para as chaves de parceiro contratado; nas rotas POST de sugerir, auditar e lotes.

Endpoints

Base https://api.tributox.studiolabsai.com. A versão fica no path (/api/fiscal/v1). A especificação OpenAPI de todos eles está em /api/fiscal/v1/openapi.json.

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.

1. 01CriarPOST /sugerir com a demanda. Retorna 202 e o job_id, com status pendente.
2. 02ProcessarO TributoX busca a norma na base, gera a sugestão e confere as citações. Status processando.
3. 03ConsultarGET /sugestao/{job_id}. Enquanto roda, devolve 202. Cada consulta conta no limite por minuto da chave.
4. 04LerQuando concluído, o GET devolve 200 com o resultado estruturado e a base legal.

curl https://api.tributox.studiolabsai.com/api/fiscal/v1/sugestao/3f2b9c1e-7a4d-4e8b-9c2a-1d5e6f7a8b9c \
  -H "Authorization: Bearer $TRIBUTOX_API_KEY"

# 202 enquanto processa · 200 quando concluído

Síncrono: você manda o texto da venda ou o XML da NF-e no campo entrada e a resposta vem na mesma chamada, em alguns segundos. Quem decide alíquota interestadual, CFOP e DIFAL é um motor de regras versionado; a IA só lê a entrada e explica o resultado.

curl https://api.tributox.studiolabsai.com/api/fiscal/v1/auditar \
  -H "X-API-Key: $TRIBUTOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entrada": "Venda de produção própria, NCM 84713012, de SP para BA em 2026-03-10, origem 0, para contribuinte do ICMS, emitente no Simples Nacional."
  }'

{
  "sucesso": true,
  "fonte": "rag",
  "status": "revisao_necessaria",
  "entrada_extraida": { "ncm": "84713012", "uf_origem": "SP", "uf_destino": "BA", "…": "…" },
  "regras_icms": {
    "versao_regras": "icms-interestadual-1.0.0",
    "aliquota_interestadual": { "status": "determinado", "valor": "7.00", "fundamentos": ["Resolução do Senado Federal nº 22/1989, …"], "motivo": "…", "faltando": [] },
    "cfop": { "status": "determinado", "valor": "6101", "fundamentos": ["…"], "motivo": "…", "faltando": [] },
    "difal": { "status": "inconclusivo", "valor": null, "fundamentos": [], "motivo": "Faltam dados para decidir o DIFAL.", "faltando": ["finalidade_aquisicao"] }
  },
  "dados_fiscais": null,
  "rag": { "sugestao": "…", "base_legal": [], "confianca": "baixa", "…": "…" },
  "insights_ia": "…"
}

Decisão com status inconclusivo ou revisao_necessaria vem sem valor, com o motivo e os campos que faltaram. Entrada vazia ou sem NCM, UF ou regime legíveis responde 422. Quando a entrada traz um CFOP, a resposta inclui também regras_icms.cfop_informado, conferido contra o calculado. O schema campo a campo está na especificação OpenAPI.

Para volume: envie até 100 operações numa chamada e acompanhe o lote. Exige chave de parceiro contratado, com os escopos fiscal:lotes (criar) e fiscal:resultados (ler). O processamento é assíncrono, item a item, com o mesmo motor do /auditar.

curl https://api.tributox.studiolabsai.com/api/fiscal/v1/lotes \
  -H "Authorization: Bearer $TRIBUTOX_API_KEY" \
  -H "X-TributoX-CNPJ: 12345678000199" \
  -H "Idempotency-Key: lote-2026-03-0001" \
  -H "Content-Type: application/json" \
  -d '{
    "itens": [
      { "referencia": "PED-1001", "entrada": "Venda de produção própria, NCM 84713012, de SP para BA em 2026-03-10, origem 0, para contribuinte do ICMS, emitente no Simples Nacional." },
      { "referencia": "PED-1002", "entrada": "Venda de mercadoria, NCM 84713012, de SP para MG em 2026-03-11, origem 0, para contribuinte do ICMS, emitente no Lucro Presumido." }
    ]
  }'

# 202 Accepted (um job_id por item, na ordem enviada)
# { "lote_id": "9d4c7e21-5b3a-4f60-8a1e-2c7d9b0e4f13", "total": 2,
#   "job_ids": [ "3f2b9c1e-7a4d-4e8b-9c2a-1d5e6f7a8b9c", "5e1d0a7b-2c3f-4d9e-8a6b-0f1e2d3c4b5a" ] }

curl https://api.tributox.studiolabsai.com/api/fiscal/v1/lotes/9d4c7e21-5b3a-4f60-8a1e-2c7d9b0e4f13 \
  -H "Authorization: Bearer $TRIBUTOX_API_KEY"

# 202 enquanto houver item pendente ou processando; 200 quando todos terminarem
# { "lote_id": "…", "status": "processando", "total": 2, "criado_em": "2026-11-03T12:00:00",
#   "contagem": { "pendente": 0, "processando": 1, "concluido": 1, "erro": 0 },
#   "itens": [ { "job_id": "…", "referencia": "PED-1001", "status": "concluido", "resultado": { … }, "erro": null },
#              { "job_id": "…", "referencia": "PED-1002", "status": "processando", "resultado": null, "erro": null } ] }

Guia de integração com ERP

Como um ERP ou software fiscal envia uma operação e recebe de volta uma análise estruturada. O mesmo padrão vale para sistemas contábeis e plataformas financeiras.

import os, time, httpx

API = "https://api.tributox.studiolabsai.com/api/fiscal/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['TRIBUTOX_API_KEY']}"}

def auditar(entrada: str):
    for tentativa in range(3):
        r = httpx.post(f"{API}/auditar", json={"entrada": entrada}, headers=HEADERS, timeout=60)
        if r.status_code in (429, 503):
            time.sleep(int(r.headers.get("Retry-After", "5")))
            continue
        r.raise_for_status()  # 401, 413, 422: corrigir o pedido
        return r.json()
    raise RuntimeError("API indisponível depois de 3 tentativas")

res = auditar("Venda de produção própria, NCM 84713012, de SP para BA em 2026-03-10, "
              "origem 0, para contribuinte do ICMS, emitente no Simples Nacional.")
for campo in ("aliquota_interestadual", "cfop", "difal"):
    d = res["regras_icms"][campo]
    print(campo, d["status"], d["valor"], d["faltando"])

const API = "https://api.tributox.studiolabsai.com/api/fiscal/v1";
const headers = { Authorization: `Bearer ${process.env.TRIBUTOX_API_KEY}`, "Content-Type": "application/json" };

export async function sugerir(demanda: string, contexto?: Record<string, string>) {
  const criar = await fetch(`${API}/sugerir`, { method: "POST", headers, body: JSON.stringify({ demanda, contexto }) });
  if (criar.status !== 202) throw new Error(`criar: ${criar.status}`);
  const { job_id } = (await criar.json()) as { job_id: string };

  for (let i = 0; i < 30; i++) {
    await new Promise((r) => setTimeout(r, 2000)); // cada consulta conta no limite por minuto
    const r = await fetch(`${API}/sugestao/${job_id}`, { headers });
    if (r.status === 202) continue;
    if (r.status === 429) { await new Promise((ok) => setTimeout(ok, Number(r.headers.get("Retry-After") ?? 5) * 1000)); continue; }
    const job = await r.json();
    if (job.status === "erro") throw new Error("job com erro: crie outro");
    return job.resultado; // sugestao, regras, excecoes, base_legal, confianca, aviso
  }
  throw new Error("tempo esgotado");
}

Limites e consumo

O consumo é medido por chave, para atribuição por consumidor. O volume contratado, o limite por minuto e, para parceiros, a cota mensal são combinados no contrato. Não há plano gratuito nem cota automática para quem não tem contrato.

HTTP/1.1 429 Too Many Requests
Retry-After: 23
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 23

{ "detail": "Limite de 60 requisicoes por minuto atingido para esta chave." }

Erros

O 202 não é erro: é a resposta de criação e a de consulta enquanto o job ainda processa. Todo erro vem como JSON com o campo detail; os erros de contrato trazem também o campo erro, com um código estável para tratar no seu sistema. Linhas marcadas como contrato valem para chaves de parceiro contratado.

Versionamento e OpenAPI

curl https://api.tributox.studiolabsai.com/api/fiscal/v1/openapi.json

Segurança e LGPD

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. Idempotência e lotes já estão disponíveis para parceiros contratados.

• 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.

Portal de autoatendimento para desenvolvedores não faz parte do roadmap: a API é um modelo contratado, com credencial exclusiva entregue pelo time depois do contrato.

Cobertura