NCM API

Classifica um produto pelo nome comercial. Retorna NCM sugerido, validação contra a tabela oficial, CEST associado e flag de ST.

Request body

Exemplos

curl -X POST https://api.seu-dominio.com.br/ncm/buscar \
  -H "X-API-Key: ncm_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "produto": "coca cola lata 350ml" }'

const res = await fetch('https://api.seu-dominio.com.br/ncm/buscar', {
  method: 'POST',
  headers: {
    'X-API-Key': 'ncm_live_xxxxxxxx',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ produto: 'coca cola lata 350ml' }),
});
const data = await res.json();
console.log(data);

import requests

r = requests.post(
    'https://api.seu-dominio.com.br/ncm/buscar',
    headers={'X-API-Key': 'ncm_live_xxxxxxxx'},
    json={'produto': 'coca cola lata 350ml'},
)
print(r.json())

uses IdHTTP, IdSSLOpenSSL, System.JSON, System.Classes;

procedure TForm1.BuscarNCM(const ANome: string);
var
  HTTP: TIdHTTP;
  SSL:  TIdSSLIOHandlerSocketOpenSSL;
  Body: TStringStream;
  Resp: string;
  JSON: TJSONObject;
begin
  HTTP := TIdHTTP.Create(nil);
  SSL  := TIdSSLIOHandlerSocketOpenSSL.Create(nil);
  try
    SSL.SSLOptions.Method := sslvTLSv1_2;
    HTTP.IOHandler := SSL;
    HTTP.Request.ContentType := 'application/json';
    HTTP.Request.CustomHeaders.Values['X-API-Key'] := 'ncm_live_xxxxxxxx';

    Body := TStringStream.Create('{"produto":"' + ANome + '"}', TEncoding.UTF8);
    try
      Resp := HTTP.Post('https://api.seu-dominio.com.br/ncm/buscar', Body);
    finally
      Body.Free;
    end;

    JSON := TJSONObject.ParseJSONValue(Resp) as TJSONObject;
    try
      edtNCM.Text   := JSON.GetValue<string>('ncm');
      edtCEST.Text  := JSON.GetValue<string>('cest');
      chkST.Checked := JSON.GetValue<Boolean>('tem_st');
    finally
      JSON.Free;
    end;
  finally
    HTTP.Free;
    SSL.Free;
  end;
end;

Resposta (200 OK)

{
  "produto": "coca cola lata 350ml",
  "ncm": "22021000",
  "descricao_ncm": "Águas gaseificadas adicionadas de açúcar",
  "ncm_validado": true,
  "ncm_vigente": true,
  "cest": "0300700",
  "descricao_cest": "Refrigerantes e bebidas não alcoólicas",
  "segmento": "Bebidas",
  "tem_st": true,
  "confianca": "alta",
  "justificativa": "Refrigerante classificado como bebida não alcoólica",
  "fonte": "gemini"
}

Campos da resposta

Processa até 500 produtos em uma única requisição. Recomendado para cargas iniciais de catálogo. Internamente o sistema agrupa em lotes para o Gemini.

Request body

{
  "produtos": [
    "coca cola lata 350ml",
    "arroz tio joão 5kg",
    "detergente ypê 500ml"
  ]
}

cURL

curl -X POST https://api.seu-dominio.com.br/ncm/batch \
  -H "X-API-Key: ncm_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "produtos": ["coca cola lata 350ml", "arroz tio joão 5kg"] }'

Resposta (200 OK)

{
  "resultado": [
    {
      "produto": "coca cola lata 350ml",
      "ncm": "22021000",
      "descricao_ncm": "Águas gaseificadas adicionadas de açúcar",
      "cest": "0300700",
      "tem_st": true,
      "ncm_validado": true,
      "ncm_vigente": true,
      "confianca": "alta",
      "fonte": "gemini"
    },
    {
      "produto": "arroz tio joão 5kg",
      "ncm": "10063021",
      "descricao_ncm": "Arroz semibranqueado ou branqueado",
      "cest": null,
      "tem_st": false,
      "ncm_validado": true,
      "ncm_vigente": true,
      "confianca": "alta",
      "fonte": "gemini"
    }
  ],
  "stats": {
    "qtd_total": 2,
    "qtd_cobravel": 2,
    "qtd_cache_hit": 0,
    "qtd_gemini": 2,
    "qtd_descartado": 0,
    "qtd_invalido": 0
  }
}

Comportamento de erro por item

Se um produto individual falhar (Gemini não retornou NCM, cota se esgotou no meio do lote, etc.), o item do array vem com chave erro em vez dos campos normais. Os demais continuam normalmente:

{
  "produto": "produto qualquer",
  "erro": "cota_insuficiente"
}

Detalhes de um NCM específico a partir da tabela oficial local (sem chamar Gemini). Útil para validar um NCM já cadastrado no ERP.

cURL

curl https://api.seu-dominio.com.br/ncm/22021000 \
  -H "X-API-Key: ncm_live_xxxxxxxx"

Resposta (200 OK)

{
  "codncm": "22021000",
  "descricao": "Águas gaseificadas adicionadas de açúcar ou aromatizadas",
  "validade_ini": "2022-04-01",
  "validade_fim": null,
  "vigente": true,
  "tipoato": "Resolução",
  "numeroato": "125",
  "anoato": 2022,
  "cests": [
    { "codcest": "0300700", "descricao": "Refrigerantes...", "segmento": "Bebidas" }
  ],
  "tem_st": true
}

Tributação completa: ICMS/PIS/COFINS/IPI do regime atual, carga IBPT (Lei 12.741/2012) e alíquotas IBS/CBS/IS da Reforma Tributária (LC 214/2025).

Query parameters

cURL — sem CFOP (sugestão automática)

curl "https://api.seu-dominio.com.br/ncm/22021000/tributacao?uf=PE®ime=simples" \
  -H "X-API-Key: ncm_live_xxxxxxxx"

cURL — com CFOPs do ERP

curl "https://api.seu-dominio.com.br/ncm/22021000/tributacao?uf=PE®ime=simples&cfop_interno=5405&cfop_externo=6404" \
  -H "X-API-Key: ncm_live_xxxxxxxx"

Os 4 campos retornados em cada bloco de tributo

Tabela de comportamento por CST/CSOSN

Mesma lógica aplica para PIS/COFINS no Simples Nacional (recolhidos via DAS, nunca destacam). O bloco IPI tem apenas destacar_na_nfe (sem alíquota separada — usa a alíquota TIPI direto).

Resposta (200 OK) — resumo

{
  "ncm": "22021000",
  "descricao": "Águas gaseificadas adicionadas de açúcar",
  "uf": "PE",
  "regime": "simples",
  "tem_st": true,
  "cest": "0300700",
  "regime_atual": {
    "icms":   {
      "aliquota":               18.00,
      "aliquota_destacada_nfe": 0,           // ← o que vai no  da NF-e
      "cst":                    "500",
      "tem_st":                 true,
      "destacar_na_nfe":        false,
      "obs":                    "Simples + substituído: ICMS-ST já recolhido anteriormente. NF-e NÃO destaca ICMS (vICMS=0)..."
    },
    "pis":    {
      "aliquota":               0.00,
      "aliquota_destacada_nfe": 0,
      "cst":                    "07",
      "destacar_na_nfe":        false,
      "obs":                    "Simples Nacional: PIS recolhido via DAS."
    },
    "cofins": { "aliquota": 0.00, "aliquota_destacada_nfe": 0, "cst": "07", "destacar_na_nfe": false },
    "ipi":    {
      "aliquota":        0.00,
      "cst":             "53",          // ← Simples comércio: CST 53 (saída não tributada)
      "destacar_na_nfe": false,
      "fundamento":      "Comerciante não-contribuinte do IPI (art. 24 do RIPI).",
      "obs":             "Comerciante (varejista/atacadista) não é contribuinte do IPI..."
    }
  },
  "ibpt": {
    "versao": "25.2.E",
    "fed_nacional": 3.65,
    "estadual": 18.00,
    "municipal": 0.00,
    "carga_total": 21.65
  },
  "reforma_tributaria": {
    "ano_referencia": 2026,
    "fase": "transicao",
    "cbs": { "aliquota_efetiva": 0.90, "cst": "01" },
    "ibs": { "aliquota_efetiva": 0.12, "cst": "01" },
    "is":  { "tem_is": true, "aliquota": 20.00 },
    "total_ibs_cbs": 1.02
  },
  "cst_sugerido":  { "icms": "500", "pis": "07", "cofins": "07", "ipi": "50", "ibs_cbs": "01" },
  "cfop_sugerido": { "venda_interna": "5405", "venda_interestadual": "6404", "obs": "...sujeita a ST" },
  "cfops_analisados": {
    "interno": {
      "cfop": "5405",
      "conhecido": true,
      "descricao": "Venda de mercadoria c/ ST já recolhida (substituído, interna)",
      "dentro_uf": true,
      "tipo_operacao": "venda_st_substituido",
      "tem_st": true,
      "cst_icms_sugerido": "500",
      "alerta": null
    },
    "externo": {
      "cfop": "6404",
      "conhecido": true,
      "descricao": "Venda de mercadoria c/ ST já recolhida (substituído, interestadual)",
      "dentro_uf": false,
      "tipo_operacao": "venda_st_substituido",
      "tem_st": true,
      "cst_icms_sugerido": "500",
      "alerta": null
    }
  }
}

O bloco cfops_analisados só aparece quando você passa os parâmetros. O campo alerta não-nulo indica inconsistência entre CFOP escolhido e situação tributária do NCM (ex: produto com ST mas CFOP de venda comum).

Consulta o saldo do tenant sem consumir créditos. Útil para o ERP exibir o saldo na tela, validar antes de iniciar batch, ou bloquear UI quando o saldo estiver baixo.

cURL

curl https://api.seu-dominio.com.br/quota \
  -H "X-API-Key: ncm_live_xxxxxxxx"

Resposta (200 OK)

{
  "tenant": {
    "id":         "uuid-do-tenant",
    "nome":       "Padaria do Zé",
    "atividade":  "comercio",
    "status":     "ativo"
  },
  "api_key": {
    "nome":     "Chave do ERP principal",
    "prefix":   "ncm_live_a1b2c3d4",
    "ambiente": "producao"
  },
  "assinatura": {
    "plano":            "PRO",
    "status":           "ativa",
    "vigencia_fim":     "2026-06-12",
    "dias_para_vencer": 31,
    "vencida":          false
  },
  "saldo": {
    "total":                 2500,
    "usado":                 437,
    "disponivel":            2063,
    "percentual_usado":      17.48,
    "percentual_disponivel": 82.52,
    "creditos_extras":       0
  },
  "custos": {
    "ncm_buscar_por_produto": 1,
    "ncm_batch_por_produto":  1,
    "ncm_get":                0,
    "ncm_tributacao":         0,
    "cest_get":               0,
    "quota_consulta":         0
  },
  "homologacao_gratis": false,
  "consulta_em":        "2026-05-13T22:30:00.000Z"
}

Os mesmos headers X-NCM-Quota-* que vêm em todas as outras respostas também são incluídos aqui — você pode escolher ler do JSON ou dos headers.

Casos de uso típicos

Lista todos os CESTs associados a um NCM (Convênio ICMS 142/2018).

cURL

curl https://api.seu-dominio.com.br/cest/22021000 \
  -H "X-API-Key: ncm_live_xxxxxxxx"

Resposta (200 OK)

{
  "ncm": "22021000",
  "tem_st": true,
  "cests": [
    {
      "codcest": "0300700",
      "descricao": "Refrigerantes e bebidas não alcoólicas",
      "segmento": "Bebidas"
    }
  ]
}