Ir para o conteúdo

Endpoints api consulta lote

2) Endpoints

Cada grande grupo (nomenclaturas vigentes ou alternativas) possui três endpoints de comportamento similar. O diagrama de sequência a seguir ilustra uma utilização:

Fluxo Geral

Descrições detalhadas dos seus comportamentos estão disponíveis a seguir:

2.1) Nomenclatura Vigente (NCM)

2.1.1) Verificar atualização de capítulos

GET - /api/ext/importacao/ncm-capitulos/hashes

Esse endereço retorna a data atual, o hash correspondente ao arquivo de tratamentos tributários de cada capítulo de NCM na data atual e o seu status.

Exemplo de retorno:

{
  "data":"2026-03-19",
  "hashes":[
    {
      "capitulo":"01",
      "hash":"5AA188220B970F0855B655D61FEAE1F8D896AE476F77E894C1D4F90CB340CEB3",
      "status":"CONCLUIDO"
    },
    {
      "capitulo":"02",
      "hash":"AB2F591F83C4AC6540AC8FF7A29C3C1F15BE45DF1B7D2A38C3AB3279B21CD3A5",
      "status":"CONCLUIDO"
    }
  ]
}

2.1.2) Obter hash de um capítulo

GET - /api/ext/importacao/ncm-capitulos/{capitulo}/hash

Esse endereço retorna o nome e o hash correspondente ao arquivo de tratamentos tributários de um capítulo e data fornecidos pelo usuário. Caso esse arquivo ainda não tenha sido gerado, o sistema informará que ele está sendo construído e a chamada deve ser refeita dentro de alguns instantes para obter o hash.

Exemplo de chamada:

api/ext/importacao/ncm-capitulos/02/hash?data=2026-03-19

Exemplo de retorno:

{
  "data":"2026-03-19",
  "capitulo":"02",
  "nomeArquivo":"V_02_20260319.json",
  "hash":"AB2F591F83C4AC6540AC8FF7A29C3C1F15BE45DF1B7D2A38C3AB3279B21CD3A5"
}

2.1.3) Realizar download de um capítulo

GET - /api/ext/importacao/ncm-capitulos/{capitulo}/tratamentos-tributarios

Esse endereço retorna o arquivo correspondente ao capítulo, data e hash fornecidos pelo usuário.

Exemplo de chamada:

api/ext/importacao/ncm-capitulos/02/tratamentos-tributarios?data=2026-03-19&hash=AB2F591F83C4AC6540AC8FF7A29C3C1F15BE45DF1B7D2A38C3AB3279B21CD3A5

2.2) Nomenclaturas Alternativas

2.2.1) Verificar atualização de nomenclaturas alternativas

GET - /api/ext/importacao/fundamentos-legais/{codigoFundamentoLegal}/nomenclaturas-alternativas/hashes

Esse endereço retorna a data atual, o hash correspondente ao arquivo de tratamentos tributários de cada fundamento legal de nomenclatura alternativa na data atual e o seu status.

Exemplo de retorno:

{
  "data":"2026-03-20",
  "hashes":[
    {
      "fundamentoLegal":"0009",
      "hash":"8D8D71DB89553814C74A267BEECFADB8111A84F5DE44138ED2DF491470829224",
      "status":"CONCLUIDO"
    },
    {
      "fundamentoLegal":"0010",
      "hash":"0F4B7E2C92784D73BB8CC95B24C320582B94AD2542A3FA0E2A721758305D7B42",
      "status":"CONCLUIDO"
    }
  ]
}

GET - /api/ext/importacao/fundamentos-legais/{codigoFundamentoLegal}/nomenclaturas-alternativas/hash

Esse endereço retorna o nome e o hash correspondente ao arquivo de tratamentos tributários de nomenclatura alternativa de um fundamento legal e data fornecidos pelo usuário. Caso esse arquivo ainda não tenha sido gerado, o sistema informará que ele está sendo construído e a chamada deve ser refeita dentro de alguns instantes para obter o hash.

Exemplo de chamada:

api/ext/importacao/fundamentos-legais/25/nomenclaturas-alternativas/hash?data=2026-03-19

Exemplo de retorno:

{
  "data":"2026-03-19",
  "fundamentoLegal":"25",
  "nomeArquivo":"A_0025_20260319.json",
  "hash":"F12F42DE49C075523E1091A2739FD31355088328577600885D0699B00D60229D"
}

2.2.3) Realizar download de um capítulo

GET - /api/ext/importacao/fundamentos-legais/{codigoFundamentoLegal}/nomenclaturas-alternativas/tratamentos-tributarios

Esse endereço retorna o arquivo de tratamentos tributários de nomenclatura alternativa correspondente ao fundamento legal, data e hash fornecidos pelo usuário.

Exemplo de chamada:

api/ext/importacao/fundamentos-legais/25/nomenclaturas-alternativas/tratamentos-tributarios?data=2026-03-19&hash=F12F42DE49C075523E1091A2739FD31355088328577600885D0699B00D60229D

4) Estrutura do JSON

Em linhas gerais, cada JSON é dividido entre intervalos de nomenclatura, origens, destinos e tratamentos tributários. Portanto, ao chegar no nível dos tratamentos tributários, os dados informados são referentes a nomenclaturas dentro de um mesmo intervalo, com mesma origem (ou grupo de origens) e destino (ou grupo de destinos). É importante ressaltar que os atributos de um tratamento tributário obedecem a uma ordem determinada e dada pelo JSON. Por isso, ao repassar os dados para realização de um cálculo tributário, é importante que essa ordem seja respeitada.

Segue abaixo a especificação de cada um dos campos disponíveis no JSON:

Nome Formato Descrição
dataFatoGerador String Representa a data do fato gerador no formato YYYY-MM-DD
hash String Identifica os dados do arquivo de maneira inequívoca
capitulo String de dois dígitos Representa o número do capítulo (apenas NCM)
codigoFundamentoLegal String de quatro dígitos Representa o código do fundamento legal associado (apenas nomenclaturas alternativas)
intervalosNcm Lista de intervalos de nomenclatura Delimita os intervalos dentro dos quais os tratamentos seguintes se aplicam
intervaloInicialNcm String de oito dígitos Descreve o primeiro valor de nomenclatura aplicável do intervalo descrito
intervaloFinalNcm String de oito dígitos Descreve o último valor de nomenclatura aplicável do intervalo descrito
origensDestinosTratamentos Lista de origens e destinos Delimita as origens e destinos aos quais os tratamentos seguintes se aplicam
todosPaisesOrigem Booleano Indica se a origem contempla todos os países (true) ou apenas um subconjunto (false)
paisesOrigem Lista de strings de identificadores de países Descreve os países de origem dos tratamentos seguintes quando o campo todosPaisesOrigem é falso
destinosTratamento Lista de destinos acompanhados dos tratamentos tributários aplicáveis Delimita os destinos aos quais os tratamentos seguintes se aplicam
destinos Lista de destinos acompanhados dos tratamentos tributários aplicáveis Delimita os destinos aos quais os tratamentos seguintes se aplicam
todasUfsMunicipios Booleano Indica se o destino contempla todas as UFs e municípios (true) ou apenas um subconjunto (false)
ufsMunicipios Lista de identificadores de UFs Descreve as UFs de destino quando o campo todasUfsMunicipios é falso
ufDestino String de dois caracteres Indica a sigla da UF de destino
todosMunicipios Booleano Indica se o destino contempla todos os municípios da UF (true) ou apenas um subconjunto (false)
municipioDestino Lista de strings de identificadores de municípios Descreve os municípios de destino quando o campo todosMunicipios é falso
tratamentosTributarios Lista de tratamentos tributários Lista os tratamentos aplicados aos destinos descritos no campo destinos
tributo Tupla tributo/regime/fundamento legal/atributos Descreve o tributo ao qual os tratamentos tributários desta lista de destinos se aplicam
código String Identifica o código numérico do tributo
nome String Identifica o nome do tributo
regime Tupla codigo/nome Descreve o regime ao qual os tratamentos tributários desta lista de destinos pertencem
código String Identifica o código numérico do regime
nome String Identificando o nome do regime
fundamentoLegal Tupla codigo/nome/tipo Descreve o fundamento legal envolvido nos tratamentos tributários da lista de destinos
codigo String Identifica o código numérico do fundamento legal
nome String Identifica o nome do fundamento legal
tipo String Identifica o tipo do fundamento legal (Normal, Opcional ou Teto)
atributos Lista ordenada de atributos Descreve, em ordem, os atributos necessários para a aplicação do tratamento tributário
codigo String Identifica o código do atributo
descricaoCodigo String Identifica a descrição do atributo
formaPreenchimento String Indica a forma que o atributo deve ser preenchido
dominios Lista de opções Descreve as opções que podem ser atribuídas ao atributo quando o campo formaPreenchimento é Domínio Dinâmico. Nesse caso, é possível que determinadas escolhas impliquem na seleção de novos atributos, formando uma estrutura recursiva
valor String Indica o valor da opção selecionada
descricaoValor String Indica a descrição da opção selecionada