Pular para conteúdo

InvoiCy Tax Engine

O InvoiCy Tax Engine é um motor de processamento de regras fiscais que abstrai a complexidade da legislação brasileira. Através de uma API centralizada, sua aplicação envia dados comerciais brutos e recebe o cálculo exato de tributos, alíquotas e fundamentações legais.

O motor opera em cinco frentes:
- Enriquecimento de dados: Prepara o sistema antes da emissão, por meio da sincronização de informações fiscais e do fornecimento de metadados como CST, cClassTrib, NBS e fundamentação legal.
- Cálculo tributário: Processa e valida as regras fiscais da operação, realizando o cálculo de IBS, CBS e IS com base nos dados informados, além da apuração das bases de cálculo.
- XML: Converte o resultado do cálculo para o grupo de tributos do documento fiscal e valida o XML gerado.
- NFS-e: Consultas e validações específicas para a Nota Fiscal de Serviço Eletrônica, como indicador de operação e local de tributação.
- Observabilidade: Apoia o diagnóstico de inconsistências, isolando os itens com erro e detalhando os códigos de erro retornados.

Autenticação e Acesso

A segurança da API é baseada em JWT (JSON Web Token). Para interagir com o InvoiCy Tax Engine, é necessário realizar um processo de autenticação em duas etapas:

  1. Geração do Token de Acesso: Você deve gerar um JWT e enviá-lo ao endpoint de autenticação para obter seu accessToken e refreshToken.
  2. Autorização nas Requisições: O accessToken recebido deve ser enviado no cabeçalho Authorization: Bearer <accessToken> de todas as chamadas subsequentes.

Para instruções passo a passo sobre como estruturar o JWT, acesse nossa documentação central: Autenticação.

Enriquecimento de Dados

Estes endpoints foram projetados para permitir que seu sistema sincronize tabelas fiscais e mantenha o cadastro de produtos e serviços sempre atualizado. O objetivo é garantir que as informações enviadas no momento do cálculo (como CST e Classificação Tributária) estejam em conformidade com as regras vigentes do motor.

Alíquotas

Endpoint para consulta das alíquotas aplicáveis à localidade da operação:

  • Alíquota Município / UF / União: Retorna a alíquota de referência e a alíquota própria do município, da UF e da União para a data informada. Essencial para determinar a carga tributária com base na localidade da operação.

Situações Tributárias (CST)

Endpoints para consulta dos códigos de situação tributária vigentes:

  • CST do IBS e da CBS: Lista as situações tributárias vigentes para uma determinada data. É o ponto de partida para entender como o item será enquadrado no novo regime.
  • CST do Imposto Seletivo: Retorna a lista específica de códigos de situação tributária cadastrados exclusivamente para o IS.

Classificações Tributárias (cClassTrib)

Estes endpoints permitem mapear as combinações corretas de códigos exigidos na Reforma Tributária:

  • Classificações do IBS e da CBS: Lista as classificações tributárias do IVA Dual. É possível buscar todos os códigos disponíveis ou filtrar apenas as classificações vinculadas a um CST específico.
  • Classificações do Imposto Seletivo: Lista as classificações para operações sujeitas ao Imposto Seletivo, com consulta completa ou filtrada por CST.
  • Classificação por Tipo de DF-e: Valida se um cClassTrib pode ser utilizado em um tipo de documento fiscal e informa se exige tributação regular, se permite diferimento e se há possibilidade de crédito presumido.
  • Classificações por NBS: Retorna os cClassTrib que podem ser utilizados com o código NBS informado.

NCM e NBS

Endpoints para consulta de produtos (NCM) e serviços (NBS):

  • NCM do Imposto Seletivo: Fornece o detalhamento de como uma NCM (Nomenclatura Comum do Mercosul) é afetada pelo Imposto Seletivo (IS), permitindo identificar se o produto é tributado e qual a alíquota aplicável.
  • NBS do Imposto Seletivo: Semelhante ao NCM, porém focado em serviços (NBS), retornando a regra de incidência do Imposto Seletivo para o item consultado.
  • Lista de NBS: Retorna a lista de todas as NBS vigentes na data informada.
  • NBS por Classificação Tributária: Retorna os códigos NBS que podem ser utilizados com o cClassTrib informado na data da operação. Quando não há NBS associada e a classificação se aplica a serviços, são retornadas todas as NBS vigentes. Quando a classificação se aplica apenas a mercadorias (NCM), o retorno é uma lista vazia.

Parâmetros de Transição

Endpoints para consulta dos percentuais aplicáveis ao longo do cronograma de transição da Reforma Tributária. Cada item retorna o valor e seu período de vigência:

Endpoint para consulta das regras de enquadramento tributário de acordo com a Reforma Tributária (IBS e CBS):

  • Fundamentação Legal: Retorna a referência normativa (lei, decreto ou regulamento) que fundamenta a classificação e a regra tributária aplicada, permitindo rastreabilidade e validação fiscal.

Versão e Controle de Atualização

Endpoint para consulta das informações de versão da aplicação e da base de dados tributária:

  • Versão: Retorna informações de versão da aplicação e da base de dados, incluindo descrição das alterações, data da versão e ambiente, permitindo controle de atualização e consistência das regras tributárias.

Cálculo Tributário

Diferentemente das APIs de enriquecimento, voltadas ao fornecimento de dados para apoio à operação, as APIs de Cálculo executam as regras da Reforma Tributária. Elas compõem o núcleo do InvoiCy Tax Engine, sendo responsáveis pela apuração dos tributos (IBS, CBS e IS) com base nos dados informados na operação.

Base de Cálculo (BETA)

Endpoints para apuração da base de cálculo a partir dos valores que a compõem (valor do bem ou serviço, acréscimos, tributos e descontos):

  • Calcular Base do IBS e da CBS: Retorna a base de cálculo do IBS e da CBS de uma operação com mercadorias. Os campos PIS, COFINS, PIS Importação e COFINS Importação não podem ser informados a partir de 2027; os campos ICMS e ISS, a partir de 2033.
  • Calcular Base do Imposto Seletivo: Retorna a base de cálculo do Imposto Seletivo de uma operação com mercadorias. Os campos ICMS e ISS não podem ser informados a partir de 2033.
  • Calcular Base da NFS-e: Retorna a base de cálculo do IBS e da CBS de uma NFS-e no período de transição, considerando o valor do serviço, descontos, deduções e reduções. Os campos PIS e COFINS não podem ser informados a partir de 2027; o campo ISS, a partir de 2033.

Regime Geral e Pedágio

Principais endpoints para cálculo dos tributos conforme a Reforma Tributária:

  • Calcular Regime Geral: Recebe os dados da operação (como data, localização e itens) e realiza o cálculo dos tributos por item. Considera classificação e situação tributária (CST), base de cálculo e demais parâmetros informados. Retorna os valores calculados, os totais da operação e a memória de cálculo, garantindo conformidade com as regras vigentes e o cronograma de transição fiscal. Para compras governamentais, informe o grupo opcional gCompraGov com o tipo de ente (tpEnteGov: 1 - União, 2 - Estados, 3 - Distrito Federal, 4 - Municípios) e o tipo de operação (tpOperGov: 1 - Fornecimento, 2 - Recebimento do pagamento).
  • Calcular Pedágio: Calcula os tributos de operações de pedágio, distribuindo a base de cálculo entre os trechos percorridos de acordo com o município e a extensão de cada trecho. O número de cada trecho deve ser maior ou igual a 1.

XML

Endpoints para conversão e validação do resultado do cálculo no formato do documento fiscal:

  • Gerar XML: Converte o resultado do cálculo para o grupo de tributos no formato XML do documento fiscal informado em Tipo. O XML é retornado codificado em Base64.
  • Validar XML: Valida o grupo de tributos em XML (enviado em Base64) de acordo com o tipo de documento fiscal informado, retornando se o conteúdo é válido.

NFS-e

Endpoints específicos para a emissão da Nota Fiscal de Serviço Eletrônica, que auxiliam no enquadramento do serviço e na definição do local de incidência dos tributos:

  • Indicadores de Operação: Lista os indicadores de operação (cIndOp) vigentes na data informada, com o tipo de operação e o local de fornecimento. É possível filtrar por NBS.
  • Validar Indicador de Operação: Valida a combinação de cClassTrib, indicador de operação (cIndOp, 6 dígitos), NBS (9 dígitos) e data do fato gerador, com código de tributação nacional (cTribNac) opcional. Retorna se a combinação é válida para a NFS-e.
  • Situações e Classificações da NFS-e: Retorna todas as combinações de CST e cClassTrib associadas à NBS informada na data da operação.
  • Local de Operação: Consulta o local da operação da NFS-e a partir do indicador de operação e da data do fato gerador.

Observabilidade

Endpoints para diagnóstico de inconsistências no cálculo, permitindo identificar e tratar os itens com erro sem interromper toda a operação:

  • Calcular Regime Geral com Observabilidade: Recebe o mesmo payload do [Calcular Regime Geral][regime-geral], porém, em vez de rejeitar a operação inteira, isola os itens com inconsistência e indica o estado de cada um (estadoItem) e seus erros.
  • Dicionário de Erros: Retorna o título e a descrição de um código de erro de observabilidade, permitindo exibir mensagens mais claras ao usuário final.

Exemplos de requisições

Para visualizar exemplos de payloads (JSON), esquemas de resposta e realizar testes, clique aqui para acessar a documentação.