Classificação fiscal via API
Envie descrições de produtos e receba sugestões de NCM, benefícios da Reforma Tributária e possíveis enquadramentos de cClassTrib (IBS/CBS) em formato estruturado para integração.
Base URL
https://api.taxradar.app/api/v1
Autenticação
X-API-Key: sk_live_xxx
Disponibilidade
Planos Business e Enterprise
Caso de uso: enriquecer itens de NFC-e em lote
O caso mais comum é enriquecer um catálogo ou um lote de itens de NFC-e que precisam de uma sugestão
de NCM e de enquadramento tributário. Envie até 100 itens com external_id por chamada com tipo_dfe: "nfce" no contexto. A resposta traz sugestões
de NCM, a hierarquia, as situações de cClassTrib compatíveis com o contexto informado e a faixa de
confiança de cada sugestão. Erros de validação ficam isolados no item e não consomem cota.
curl --fail-with-body -X POST "https://api.taxradar.app/api/v1/ingest/classify/batch" \
-H "X-API-Key: $TAXRADAR_API_KEY" \
-H "Idempotency-Key: 6f9bd488-3edf-4ad7-aa73-054d76d74f7d" \
-H "Content-Type: application/json" \
-d '{
"itens": [
{
"external_id": "SKU-001",
"descricao": "ARROZ TIPO 1 5KG",
"ean": "7891234567895",
"ncm_atual": "10063021"
},
{
"external_id": "SKU-002",
"descricao": "x"
}
],
"top_k": 3,
"contexto_cclasstrib": {"tipo_dfe": "nfce"},
"incluir_nesh": false
}'
A resposta traz hierarquia e classificacao_tributaria por sugestão, além de um bloco usage no nível raiz com o consumo do plano após a chamada.
Reutilize a mesma Idempotency-Key e o mesmo body após
timeout: o replay não consome nova cota nem duplica o histórico. Chave com payload diferente ou tentativa
ainda ativa retornam 409. O formato legado descricoes continua compatível, sem data de remoção.
Confiança baixa encerra normalmente, sem pergunta ou interação adicional.
Como começar
Crie sua conta
O cadastro é gratuito e leva um minuto. O acesso à API está disponível nos planos Business e Enterprise.
Gere sua API Key
Em Configurações, crie uma chave com as permissões que a sua integração precisa: classificação, consultas, histórico e uso.
Integre
Envie as descrições dos produtos e receba sugestões de NCM, benefícios fiscais e situações de cClassTrib em formato estruturado.
Cada API Key tem permissões independentes e um limite de requisições por minuto configurável. A referência completa de endpoints, permissões e códigos de erro está na documentação.
Cota do plano
O plano Business inclui 500.000 classificações por ciclo de cobrança. Ao atingir o limite, novas
chamadas retornam 429 até o próximo ciclo. Não há
cobrança automática de excedente. O plano Enterprise não possui limite mensal definido. A resolução
de cClassTrib unitária consome 1 crédito a cada 5 consultas do ciclo.
Limite por minuto
Cada chave tem um limite de requisições por minuto, com 60 por padrão e configuração de 1 a 1.000.
Ao atingir esse limite, a resposta é 429 com o header Retry-After.
Pronto para integrar?
Crie sua conta, gere uma API Key em Configurações e comece a classificar produtos automaticamente.