APIs principales
NCM
2 endpoints
/api/ncm/getConsultar NCM
Devuelve un elemento de la nomenclatura NCM oficial por código, con la cadena de descripciones desde el capítulo hasta el propio código, la alícuota tomada de la tabla de IPI y los CEST en los que aparece el código. El código puede enviarse con o sin punto, como código completo de 8 dígitos o como capítulo (2 dígitos), partida (4 dígitos) y niveles intermedios (5 a 7 dígitos). Esta ruta es gratuita.
Headers obligatorios
| Header | Tipo | Descripción |
|---|---|---|
| token | string | Token de la empresa emisora |
| sign | string | Firma MD5 |
| timestamp | string | Unix timestamp en segundos |
Body
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| ncm | string | Sí | 2, 4, 5, 6, 7 u 8 dígitos, por ejemplo "8517.13.00" o "85171300" |
Solo el código de 8 dígitos puede figurar en la línea de la factura (valido_para_nota igual a true); los niveles de 2 a 7 dígitos son etapas de clasificación, útiles para navegar y filtrar, pero no válidas en un documento.
La nomenclatura oficial contiene código, descripción y vigencia, nunca alícuota. El campo ipi procede de la tabla de IPI, y excecoes recoge las alícuotas de excepción del mismo código; cest procede de la lista de sustitución tributaria, y figurar en esa lista significa que la mercancía está dentro del alcance en el que la sustitución puede aplicarse, mientras que su aplicación efectiva depende del acuerdo entre los dos estados implicados.
La descricao de una hoja suele ser un fragmento como "Outras", ilegible fuera de contexto. Utilice preferentemente descricao_completa o componga el texto a partir de hierarquia.
La nomenclatura cambia de versión con cada acto oficial publicado. Se recomienda almacenarla en caché por versao y volver a sincronizar cuando ese valor cambie.
/api/ncm/listLista de NCM (paginada)
Devuelve la nomenclatura NCM oficial página por página. El resultado puede acotarse por prefijo de código, buscarse por palabra clave o limitarse a los códigos de 8 dígitos, los únicos admitidos en factura. Los filtros viajan en el cuerpo JSON; todos son opcionales y combinables, y un cuerpo vacío ({}) devuelve la nomenclatura completa (más de quince mil elementos), una página cada vez. Los elementos salen siempre en orden creciente de código. Esta ruta es gratuita.
Headers obligatorios
| Header | Tipo | Descripción |
|---|---|---|
| token | string | Token de la empresa emisora |
| sign | string | Firma MD5 |
| timestamp | string | Unix timestamp en segundos |
Body
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| page | int | No | Número de página, a partir de 1; valor predeterminado 1 |
| page_size | int | No | Elementos por página; valor predeterminado 50, máximo 200 |
| prefixo | string | No | Prefijo del código, que acota un subárbol: 2, 4, 5, 6, 7 u 8 dígitos. "8517", por ejemplo, devuelve todos los códigos de esa partida |
| termo | string | No | Palabra clave buscada en la descripción completa; mínimo 2 caracteres. La búsqueda recorre toda la cadena, de modo que si la palabra figura en el título de un nivel superior se devuelve el subárbol completo; acótelo con prefixo o somente_folhas |
| somente_folhas | string | No | Envíe "1" para devolver solo los códigos de 8 dígitos, único nivel admitido en la línea de la factura |
| incluir_extintos | string | No | Envíe "1" para incluir códigos ya derogados; de forma predeterminada solo se devuelven los vigentes |
| incluir_impostos | string | No | Envíe "0" para omitir ipi y cest y reducir la respuesta; de forma predeterminada se incluyen |
| incluir_hierarquia | string | No | Envíe "0" para omitir hierarquia y reducir la respuesta; de forma predeterminada se incluye |
Solo el código de 8 dígitos puede figurar en la línea de la factura (valido_para_nota igual a true); los niveles de 2 a 7 dígitos son etapas de clasificación, útiles para navegar y filtrar, pero no válidas en un documento.
La nomenclatura oficial contiene código, descripción y vigencia, nunca alícuota. El campo ipi procede de la tabla de IPI, y excecoes recoge las alícuotas de excepción del mismo código; cest procede de la lista de sustitución tributaria, y figurar en esa lista significa que la mercancía está dentro del alcance en el que la sustitución puede aplicarse, mientras que su aplicación efectiva depende del acuerdo entre los dos estados implicados.
La descricao de una hoja suele ser un fragmento como "Outras", ilegible fuera de contexto. Utilice preferentemente descricao_completa o componga el texto a partir de hierarquia.
La nomenclatura cambia de versión con cada acto oficial publicado. Se recomienda almacenarla en caché por versao y volver a sincronizar cuando ese valor cambie.