Prévia de documentação apenas para visualização
Esta é uma prévia da documentação do Portal, gerada a partir do branch r75-parana , e o propósito desta página é simples conferências e revisão pelos departamentos responsáveis da Decex e RFB. Não é a documentação definitiva e qualquer coisa aqui pode mudar a qualquer momento. A documentação da release atual pode ser sempre acessada em https://docs.portalunico.siscomex.gov.br/ .
Documentação adicional sobre a API de consulta em lote (por Capítulo ou por Fundamento Legal)
1) Introdução
Esta API implementa um mecanismo para a obtenção de tratamentos tributários em massa, facilitando a criação de bases de dados próprias a partir das informações armazenadas e gerenciadas pelo PUCOMEX. A API permite que os usuários realizem o download de conjuntos de tratamentos tributários para um dia específico e separados em dois grandes grupos: tratamentos referentes à nomenclatura vigente (NCM), com as operações de verificar atualização, obter hash e realizar download, e às nomenclaturas alternativas, com as operações de verificar atualização, obter hash e realizar download. Enquanto os dados de NCM são identificados pelo seu capítulo, os dados referentes às nomenclaturas alternativas são identificados em função do fundamento legal associado.
A partir do arquivo referente a cada capítulo (ou fundamento legal) de uma dada data, o sistema calcula um hash que serve de identificador para o download dos dados. Modificações nos tratamentos de um determinado dia acarretarão na mudança do hash dos capítulos (ou fundamentos legais) afetados; dessa forma, comparando o hash dos arquivos locais com os fornecidos pela API, os usuários podem verificar se existe alguma atualização a ser realizada em sua base de dados local.
Os usuários contarão com três endpoints para cada grupo de tratamentos tributários com os seguintes comportamentos:
- Verificar atualização: fornece os hashes de todos os tratamentos na data atual, atualizado diariamente às 5h.
- Obter hash: fornece o hash de um capítulo (ou fundamento legal) em uma data específica.
- Realizar download: realize o download dos tratamentos referentes ao hash fornecido.
Esse documento está organizando nos seguintes tópicos:
- Endpoints: URL e descrição dos novos endpoints.
- Cenários de uso: exemplos de utilização dos novos endpoints.
- Exemplo de JSON: exemplo do JSON gerado para o capítulo 40, demonstrando sua estrutura.
- Estrutura do JSON de tratamentos tributários: descrição tabular dos campos do JSON.
- Interpretação do conteúdo do JSON: explicação dos campos do JSON em forma de exemplo.
- Observações: observações importantes.
2) Cenários de uso
2.1) Quando o usuário importador quer carregar uma base inicial
- Chama o serviço
ncm-capitulos/hashese recebe a lista de hashes por capítulo. - Chama o serviço
ncm-capitulos/{capitulo}/tratamentos-tributarioscom data, capitulo e hash para fazer o download de cada capítulo desejado. - Chama o serviço
fundamentos-legais/nomenclaturas-alternativas/hashese recebe a lista de hashes por fundamento legal. - Chama o serviço
fundamentos-legais/{codigoFundamentoLegal}/nomenclaturas-alternativas/tratamentos-tributarioscom data, fundamento legal e hash para fazer o download de cada fundamento legal desejado.
2.2) Quando usuário importador vai verificar se existe atualização de algum capítulo e, caso exista, busca o arquivo
- Chama o serviço
ncm-capitulos/hashese recebe a lista de hashes por capítulo. - Verifica que houve atualização em alguns capítulos (hash recebido != hash armazenado).
- Chama o serviço
ncm-capitulos/{capitulo}/tratamentos-tributarioscom data, capitulo e hash para fazer o download de cada capítulo desatualizado.
2.3) Quando usuário importador vai verificar se existe atualização de nomenclaturas alternativas e, caso exista, busca o arquivo
- Chama o serviço
fundamentos-legais/nomenclaturas-alternativas/hashese recebe a lista de hashes por fundamento legal. - Verifica que houve atualização em alguns fundamentos legais (hash recebido != hash armazenado).
- Chama o serviço
fundamentos-legais/{codigoFundamentoLegal}/nomenclaturas-alternativas/tratamentos-tributarioscom data, fundamento legal e hash para fazer o download de cada fundamento legal desatualizado.
2.4) Quando houve uma atualização do TTCE no meio do dia e os novos arquivos já foram gerados
- Realiza o processo de DUIMP e recebe um erro de parâmetros, que pode indicar que houve uma atualização no tratamento tributário.
- Executa os passos descritos no
Cenário 2.2. - Executa os passos descritos no
Cenário 2.3. - Corrige os dados e realiza o processo de DUIMP com as informações atualizadas.
2.5) Quando houve uma atualização do TTCE no meio do dia e os novos arquivos ainda estão sendo gerados
- Realiza o processo de DUIMP e recebe um erro de parâmetros, que pode indicar que houve uma atualização no tratamento tributário.
- Chama o serviço
ncm-capitulos/hashese recebe a lista de hashes por capítulo com status G (Gerando). - Aguarda alguns minutos para que a geração de arquivos seja finalizada e repete a chamada ao serviço ncm-capitulos/hashes.
- Verifica que houve atualização em alguns capítulos (hash recebido != hash armazenado).
- Chama o serviço
ncm-capitulos/{capitulo}/tratamentos-tributarioscom data, capitulo e hash para fazer o download de cada capítulo desatualizado. - Chama o serviço
fundamentos-legais/nomenclaturas-alternativas/hashese recebe a lista de hashes por fundamento legal. - Verifica que houve atualização em alguns fundamentos legais (hash recebido != hash armazenado).
- Chama o serviço
fundamentos-legais/{codigoFundamentoLegal}/nomenclaturas-alternativas/tratamentos-tributarioscom data, fundamento legal e hash para fazer o download de cada fundamento legal desatualizado. - Corrige os dados e realiza o processo de DUIMP com as informações atualizadas.
2.6) Quando usuário importador precisa de dados de nomenclatura vigente de uma data passada ou data futura
-
Chama o serviço
ncm-capitulos/{capitulo}/hashcom data e capítulo desejados.a. Se o arquivo já estiver disponível:
a1. Recebe o hash do arquivo solicitado.b. Se o arquivo ainda não estiver disponível:
b1. Recebe uma mensagem do sistema informando que será necessária uma nova chamada ao mesmo serviço dentro de alguns instantes para que a geração do arquivo seja concluída. b2. Chama o serviço novamente com os mesmos parâmetros para obter o hash do arquivo gerado. -
Chama o serviço
ncm-capitulos/{capitulo}/tratamentos-tributarioscom data, capitulo e hash para fazer o download do arquivo desejado.
2.7) Quando usuário importador precisa de dados de nomenclatura alternativa de uma data passada ou data futura
-
Chama o serviço
fundamentos-legais/{codigoFundamentoLegal}/nomenclaturas-alternativas/hashcom data e fundamento legal desejados. a. Se o arquivo já estiver disponível:a1. Recebe o hash do arquivo solicitado.b. Se o arquivo ainda não estiver disponível:
b1. Recebe uma mensagem do sistema informando que será necessária uma nova chamada ao mesmo serviço dentro de alguns instantes para que a geração do arquivo seja concluída. b2. Chama o serviço novamente com os mesmos parâmetros para obter o hash do arquivo gerado. -
Chama o serviço
fundamentos-legais/{codigoFundamentoLegal}/nomenclaturas-alternativas/tratamentos-tributarioscom data, fundamento legal e hash para fazer o download do arquivo desejado.
3) Exemplo de JSON
Segue abaixo um trecho do JSON obtido para as NCMs de capítulo 40 no dia 23/03/2026:
{
"dataFatoGerador": "2026-03-23",
"capitulo": "40",
"hash": "32055B40F5BC2D76FD49E3F6BDA2455E0C9FCD931240B2E25282B937BF9276CB",
"intervalosNcm": [
{
"intervaloInicialNcm": "40090000",
"intervaloFinalNcm": "40091099",
"origensDestinosTratamentos": [
{
"todosPaisesOrigem": true,
"destinosTratamentos": [
{
"destinos": [
{
"todasUfsMunicipios": false,
"ufsMunicipios": [
{
"ufDestino": "RS",
"todosMunicipios": false,
"municipioDestino": [
"4304606"
]
}
]
}
],
"tratamentosTributarios": [
{
"tributo": {
"codigo": "6",
"nome": "PIS IMPORTAÇÃO"
},
"regime": {
"codigo": "1",
"nome": "RECOLHIMENTO INTEGRAL"
},
"fundamentoLegal": {
"codigo": "1100",
"nome": "PIS-IMPORTAÇÃO e COFINS-IMPORTAÇÃO",
"tipo": "Normal"
},
"atributos": [
{
"codigo": "ATT_5552",
"descricaoCodigo": "Uso autopeças",
"formaPreenchimento": "Domínio dinâmico",
"dominios": [
{
"valor": "0001",
"descricaoValor": "Importador NÃO é pessoa jurídica fabricante de máquinas e veículos relacionados no art. 1º da Lei 10.485/2002.",
"atributos": [
{
"codigo": "ATT_5547",
"descricaoCodigo": "Anexo II da Lei 10.485/2002",
"formaPreenchimento": "Domínio dinâmico",
"dominios": [
{
"valor": "0001",
"descricaoValor": "Se enquadra na descrição do Anexo II da Lei 10.485/2002",
"atributos": []
},
{
"valor": "XXXX",
"descricaoValor": "NÃO se enquadra na descrição do Anexo II da Lei 10.485/2002",
"atributos": []
}
]
}
]
},
{
"valor": "XXXX",
"descricaoValor": "Importador É pessoa jurídica fabricante de máquinas e veículos relacionados no art. 1º da Lei 10.485/2002.",
"atributos": []
}
]
}
]
}
]
}
]
}
]
}
]
}
4) Interpretação do conteúdo do JSON
Consideremos o caso a seguir: um importador deseja consultar os atributos necessários para preencher uma DUIMP de NCM 4009.11.00, referente a uma importação vinda da Argentina para a cidade de Canoas, no RS. Para preencher os dados referentes ao tributo PIS, por exemplo, o caminho para identificar os dados seria o seguinte:
- Intervalo de NCM correspondente, dentro do arquivo referente ao capítulo 40:
{
"intervaloInicialNcm":"40090000",
"intervaloFinalNcm":"40091099"
}
- Origem correspondente, dentro do intervalo citado acima:
{
"origensDestinosTratamentos":[
{
"todosPaisesOrigem":true
}
]
}
- Destino correspondente, dentro da origem citada acima:
{
"todasUfsMunicipios":false,
"ufsMunicipios":[
{
"ufDestino":"RS",
"todosMunicipios":false,
"municipioDestino":[
"4304606"
]
}
]
}
- Tratamento tributário referente ao PIS, dentro do destino citado acima:
{
"tratamentosTributarios":[
{
"tributo":{
"codigo":"6",
"nome":"PIS IMPORTAÇÃO"
},
"regime":{
"codigo":"1",
"nome":"RECOLHIMENTO INTEGRAL"
},
"fundamentoLegal":{
"codigo":"1100",
"nome":"PIS-IMPORTAÇÃO e COFINS-IMPORTAÇÃO",
"tipo":"Normal"
},
"atributos":[
{
"codigo":"ATT_5552",
"descricaoCodigo":"Uso autopeças",
"formaPreenchimento":"Domínio dinâmico",
"dominios":[
{
"valor":"0001",
"descricaoValor":"Importador NÃO é pessoa jurídica fabricante de máquinas ...",
"atributos":[
{
"codigo":"ATT_5547",
"descricaoCodigo":"Anexo II da Lei 10.485/2002",
"formaPreenchimento":"Domínio dinâmico",
"dominios":[
{
"valor":"0001",
"descricaoValor":"Se enquadra na descrição do Anexo II da Lei 10.485/2002",
"atributos":[ ]
},
{
"valor":"XXXX",
"descricaoValor":"NÃO se enquadra na descrição do Anexo II da Lei ...",
"atributos":[ ]
}
]
}
]
},
{
"valor":"XXXX",
"descricaoValor":"Importador É pessoa jurídica fabricante de máquinas ...",
"atributos":[ ]
}
]
}
]
}
]
}
- Possível seleção de atributos para o imposto PIS, nosso exemplo, a ser passada para a DUIMP:
{
"tributos":[
{
"tributo":{
"codigo":"PIS IMPORTAÇÃO"
},
"regime":{
"codigo":1
},
"fundamento":{
"codigo":1100
},
"atributos":[
{
"codigo":"ATT_5552",
"valor":"0001"
},
{
"codigo":"ATT_5547",
"valor":"XXXX"
}
]
}
]
}
5) Observações
Importante: Ao submeter os dados para DUIMP
- Fundamentos legais normais devem ser informados sempre que necessitarem de atributos dinâmicos, independentemente de estarem sendo informados outros fundamentos opcionais. Fundamentos legais normais sem atributos dinâmicos são encontrados e calculados automaticamente pelo sistema, não devem ser informados.
- Fundamentos legais opcionais não são obrigatórios. Caso o importador deseje, precisa informar este tipo de fundamento legal (independente se o fundamento legal em questão possui ou não atributos dinâmicos).
- É obrigatório manter a ordem da lista de
atributos, conforme retornado pelo TTCE.
- O sistema TTCE fornece um Simulador de Cálculo público, tanto no ambiente de Validação, Produção e Homologação.
- Os atributos dinâmicos cadastrados no sistema Cadastro de Atributos (CADA) recebem códigos diferentes em cada ambiente. O código usado no ambiente de treinamento não é o mesmo que o usado em produção ou homologação.