Tabelas oficiais
A Nomenclatura Comum do Mercosul como a Receita publica, com os seis níveis de hierarquia, busca que ignora acento e a linhagem completa de cada código.
Para que serve
Validar um NCM que veio num documento, achar o código de uma mercadoria pela descrição e entender o que um código significa. O último caso é o menos óbvio e o mais útil: 8482.10.10 tem a descrição oficial De carga radial, que sozinha não diz nada. Só o caminho até ela informa o que o código é.
8482.10.10 De carga radial ↑ 84 Reatores nucleares, caldeiras, máquinas, aparelhos… ↑ 84.82 Rolamentos de esferas, de roletes ou de agulhas ↑ 8482.10 - Rolamentos de esferas
Duas rotas
| Rota | O que faz |
|---|---|
GET /v1/tabelas/ncm | Busca e listagem paginada. Um termo só, e o servidor decide se é código ou descrição |
GET /v1/tabelas/ncm/{codigo} | Um código com a linhagem acima dele e os desdobramentos abaixo |
Respondem na hora, sem job e sem webhook. Use a mesma chave de autenticação das outras rotas.
Buscar
# por prefixo de código curl "https://comexdoc.com.br/v1/tabelas/ncm?q=8482" \ -H "Authorization: Bearer cxd_live_..." # por descrição. Acento não importa: "valvula" acha "Válvulas" curl "https://comexdoc.com.br/v1/tabelas/ncm?q=rolamento&limite=25" \ -H "Authorization: Bearer cxd_live_..." # sem termo: pagina a tabela inteira, em ordem de código curl "https://comexdoc.com.br/v1/tabelas/ncm?pagina=2" \ -H "Authorization: Bearer cxd_live_..."
É um parâmetro só. Dígitos e pontuação são lidos como prefixo de código; qualquer outra coisa, como texto da descrição. O campo interpretado_como na resposta diz como o termo foi lido.
Sem termo, a rota pagina a tabela inteira em ordem de código, que é a ordem da hierarquia. Percorrer de ponta a ponta passa por capítulo, posições e itens na sequência certa.
A hierarquia tem seis níveis, não três
O nível é a quantidade de dígitos significativos: 2 é capítulo, 4 é posição, 6 é subposição, 8 é item. A tabela da Receita também traz códigos de 5 e 7 dígitos. 0102.29.1 é um código legítimo.
9999.99.99 tem oito dígitos e nunca existiu. Valide procurando o código na tabela.Isso importa em Bill of Lading: os BLs declaram NCM quase sempre com 4 dígitos, e exigir 8 rejeitaria a forma mais comum do documento.
Toda resposta diz de quando é a tabela
{
"items": [ ... ],
"total": 15156,
"pagina": 1,
"limite": 10,
"interpretado_como": "codigo",
"tabela": {
"total": 15156,
"ato": "Resolução Gecex nº 926/2026",
"vigencia": "Vigente em 05/09/2026",
"importada_em": "2026-09-05T23:03:06.381Z"
},
"cobranca": {
"codigos_cobrados": 10,
"valor": "0.1000"
}
}A tabela é atualizada quando a Receita publica uma resolução nova. Todo retorno carrega o ato, a vigência declarada e a data da carga, para você saber contra o que está conferindo.
Código extinto continua aparecendo
Quando um código sai por resolução, ele permanece na tabela com data_fim preenchida. Assim a consulta ainda responde sobre um código que aparece num documento antigo.
data_fim em null significa vigente por prazo indeterminado, que é o caso da maioria.
Cobrança
Pela API, cada código consultado custa 0,01 crédito (R$ 0,01) no preço padrão. Na tela do portal, a consulta é grátis.
| Rota | O que conta como código |
|---|---|
GET /v1/tabelas/ncm/{codigo} | Um código por consulta, exista ele na tabela ou não. O 404 também é cobrado |
GET /v1/tabelas/ncm | Cada código devolvido na página. Uma busca sem resultado conta como um |
O campo cobranca de toda resposta diz quantos códigos foram cobrados e o valor debitado. Na busca, quem controla o custo é o limite: com o padrão de 10, uma página custa no máximo 10 códigos.
A fonte é a Receita Federal
Nós carregamos o arquivo que ela publica e servimos com hierarquia e busca. Se houver divergência entre o que devolvemos e o que a Receita publica, a Receita está certa, e vale nos avisar.