Documentação da API NCM

GET /v1/ncm/{codigo} Free+

Detalhe de um código NCM: descrição, hierarquia (capítulo/posição/subposição) e alíquotas de IPI e II.

Parâmetros (path)

• codigo — 8 dígitos, sem pontos (ex.: 01012100)

Exemplo de resposta

{
  "codigo": "01012100",
  "codigoFormatado": "0101.21.00",
  "descricao": "-- Reprodutores de raça pura",
  "capitulo": 1,
  "descricaoCapitulo": "Animais vivos.",
  "posicao": "0101",
  "descricaoPosicao": "Cavalos, asininos e muares, vivos.",
  "subposicao": "0101.21",
  "unidade": "UN",
  "ipi": 0,
  "ii": 0,
  "referenciaDados": "2026-07-10T21:57:16.860Z"
}

Retorna 400 parametro_invalido se o código não tiver exatamente 8 dígitos e 404 nao_encontrado quando o código não consta na tabela vigente.

GET /v1/capitulos Free+

Lista os capítulos vigentes da tabela NCM (numerados de 1 a 99, alguns reservados/sem uso) com a contagem de códigos de cada um.

Parâmetros

Nenhum.

Exemplo de resposta

{
  "total": 97,
  "referenciaDados": "2026-07-10T21:57:16.860Z",
  "capitulos": [
    { "numero": 1, "descricao": "Animais vivos.", "total": 82 },
    { "numero": 2, "descricao": "Carnes e miudezas, comestíveis.", "total": 82 }
  ]
}

GET /v1/capitulos/{n} Free+

Detalhe de um capítulo: descrição e todas as posições (4 dígitos) que ele contém, com a contagem de códigos de cada posição.

Parâmetros (path)

• n — número do capítulo, de 1 a 99 (ex.: 85)

Exemplo de resposta

{
  "numero": 1,
  "descricao": "Animais vivos.",
  "total": 82,
  "referenciaDados": "2026-07-10T21:57:16.860Z",
  "posicoes": [
    { "codigo": "0101", "descricao": "Cavalos, asininos e muares, vivos.", "total": 8 },
    { "codigo": "0102", "descricao": "Animais vivos da espécie bovina.", "total": 6 }
  ]
}

Retorna 400 parametro_invalido se n não estiver entre 1 e 99 e 404 nao_encontrado quando o capítulo não existe na tabela vigente.

GET /v1/ncm?busca=&pagina= Pro+

Busca textual (accent/case-insensitive) na descrição dos códigos NCM. Resposta paginada (20 por página).

Parâmetros (query)

• busca — termo de busca, mínimo 2 caracteres (ex.: parafuso)
• pagina — página do resultado, começa em 1 (opcional)

Exemplo curl

curl -H "X-API-Key: SUA_KEY" \
  "https://apincm-kb2xbt7jka-rj.a.run.app/v1/ncm?busca=parafuso&pagina=1"

Exemplo de resposta

{
  "total": 34,
  "pagina": 1,
  "totalPaginas": 2,
  "porPagina": 20,
  "referenciaDados": "2026-07-10T21:57:16.860Z",
  "resultados": [
    {
      "codigo": "73181200",
      "codigoFormatado": "7318.12.00",
      "descricao": "-- Outros parafusos para madeira",
      "capitulo": 73,
      "descricaoCapitulo": "Obras de ferro fundido, ferro ou aço.",
      "posicao": "7318",
      "descricaoPosicao": "Parafusos, pinos ou pernos, roscados, porcas...",
      "subposicao": "7318.12",
      "unidade": "UN",
      "ipi": 6.5,
      "ii": 16
    }
  ]
}

Retorna 400 parametro_invalido se busca tiver menos de 2 caracteres.

POST /v1/classificar Pro+

Classificador por descrição livre — sugere os NCMs mais prováveis para uma descrição de mercadoria, com um score de aderência de 0 a 1. Reduz erro de enquadramento fiscal.

Corpo (JSON)

• descricao — texto livre, de 3 a 500 caracteres (ex.: "parafuso de aço inox 5mm")

Exemplo curl

curl -X POST -H "X-API-Key: SUA_KEY" -H "Content-Type: application/json" \
  -d '{"descricao": "parafuso de aço inox 5mm"}' \
  "https://apincm-kb2xbt7jka-rj.a.run.app/v1/classificar"

Exemplo de resposta

{
  "descricao": "parafuso de aço inox 5mm",
  "total": 2,
  "referenciaDados": "2026-07-10T21:57:16.860Z",
  "sugestoes": [
    {
      "codigo": "73181400",
      "codigoFormatado": "7318.14.00",
      "descricao": "-- Parafusos autoperfurantes",
      "capitulo": 73,
      "descricaoCapitulo": "Obras de ferro fundido, ferro ou aço.",
      "posicao": "7318",
      "descricaoPosicao": "Parafusos, pinos ou pernos, roscados, porcas...",
      "subposicao": "7318.14",
      "unidade": "UN",
      "ipi": 6.5,
      "ii": 16,
      "score": 0.67
    }
  ]
}

Retorna 400 parametro_invalido se descricao estiver ausente ou fora da faixa de 3 a 500 caracteres. Método GET nesta rota retorna 405 metodo_nao_permitido.