Version: 1.0.0

API de Cadastro de Produtos

Introdução

API para gerenciar o cadastro de produtos e suas classificações tributárias. O objetivo principal é permitir a customização de regras tributárias (customTax) que prevalecem sobre o resultado padrão do Motor de Cálculo de Tributos na emissão de NF-e e NFC-e.

Operações disponíveis

Operação	Método e rota	Sucesso
Criar produto	POST /{tenantId}/products	201 com { "id" }
Consultar produto	GET /{tenantId}/products/{productId}	200 com o produto
Atualizar produto	PUT /{tenantId}/products/{productId}	204 sem corpo
Revalidar produto	POST /{tenantId}/products/{productId}/revalidate	200 com { "status", "errorMessage" }

Não há operação de exclusão de produto.

Convenções do contrato

• Os nomes de campo são camelCase; na entrada, a leitura não diferencia maiúsculas de minúsculas (intraState e intrastate são aceitos). As respostas usam sempre camelCase.
• Enumerações (origin, taxRegime, status etc.) trafegam pelo nome do valor (ex.: National, RealProfit). Na entrada o nome não diferencia maiúsculas de minúsculas (national também é aceito); na resposta o nome volta como está neste contrato.
• Percentuais e demais valores dos grupos de impostos são string (ex.: "18.00"); números JSON também são aceitos nesses campos e convertidos para texto.
• Campos nulos não são devolvidos nas respostas.

Processamento assíncrono

A criação e a atualização respondem assim que o cadastro é gravado. A validação tributária dos cenários de customTax acontece em segundo plano e é refletida no campo status do produto (Created → CustomTaxPending → Active, ou Error com o motivo em errorMessage). Consulte o produto, use a operação de revalidação ou assine os webhooks de produto para acompanhar.

Atenção Sujeito a alterações mediante notas técnicas e processos de homologação.

Cadastro de produto e cálculo de impostos são cobrados à parte

O Cadastro de Produto faz parte do Motor de Cálculo de Tributos, um serviço cobrado separadamente da emissão da nota fiscal. Criar ou atualizar produtos com regras tributárias registra consumo do motor, assim como emitir NF-e ou NFC-e com o grupo taxDetermination e chamar a API de Cálculo de Impostos. O valor e a forma de cobrança são definidos no seu plano comercial. Confirme com o time comercial antes de usar em produção. Veja Motor de Cálculo de Tributos e o guia funcional do Cadastro de Produtos.

Authentication

API Key: Authorization_Header

Autenticar usando o Cabeçalho HTTP Authorization com sua API Key

Security Scheme Type:	apiKey
Header parameter name:	Authorization

API Key: Authorization_QueryParam

Autenticar usando o Parametro na URL, exemplo: "/?apikey={APIKEY_TOKEN}"

Security Scheme Type:	apiKey
Query parameter name:	apikey

HTTP: Bearer Auth

Autenticar usando o cabeçalho HTTP

Security Scheme Type:	http
HTTP Authorization Scheme:	bearer
Bearer format:	Json Web Token