Sincronismo de Classificações Tributárias e Alíquotas (CBS/IBS) com o TaxEngine¶

O que é isso?¶

Com a Reforma Tributária, todo item de venda/compra precisa ser enquadrado em uma Classificação Tributária (um código) que define, entre outras coisas:

Qual é o CST (Código de Situação Tributária) do IBS/CBS;
Quais são as alíquotas de CBS, IBS Estadual e IBS Municipal aplicáveis;
Se existem percentuais de redução ou diferimento dessas alíquotas;
Se aquela classificação gera base de cálculo para o IBS/CBS ou não.

Essas informações são publicadas e mantidas pelo TaxEngine (motor de cálculo tributário fornecido pela Promob), que funciona como uma "fonte da verdade" externa. O FoccoERP precisa manter uma cópia local e atualizada dessas classificações para poder calcular os impostos localmente, sem depender de uma chamada externa a cada cálculo (o que seria lento e arriscado em termos de disponibilidade).

Para isso, criamos uma rotina automática de sincronismo, que busca periodicamente essas informações no TaxEngine e as replica na base de dados do FoccoERP.

Como funciona o fluxo, passo a passo¶

1. Disparo automático (diário)¶

Existe uma tarefa agendada (SincronizaClassificacaoTributariaTask) que roda uma vez por dia, de forma automática, sem necessidade de intervenção manual. Essa tarefa é responsável por iniciar todo o processo de sincronismo.

2. Autenticação no TaxEngine¶

Antes de buscar qualquer dado, o sistema se autentica na API do TaxEngine (usando credenciais técnicas específicas dessa integração), obtendo um token de acesso temporário. Esse token é reaproveitado em cache enquanto for válido, evitando autenticações desnecessárias a cada execução.

3. Consulta das classificações tributárias¶

Com o token em mãos, o sistema consulta o endpoint do TaxEngine responsável por listar todas as classificações tributárias vigentes (tax-classifications). A resposta vem em formato JSON e contém, para cada classificação:

Código e descrição da classificação tributária;
CST e sua descrição;
Data de início e data de fim de vigência daquela alíquota;
Alíquotas de CBS, IBS Estadual e IBS Municipal;
Percentuais de redução e diferimento de cada tributo;
Indicador se aquela classificação gera base de cálculo do IBS/CBS.

4. Persistência dos dados no FoccoERP¶

Cada classificação retornada é gravada (ou atualizada) na tabela TCLASSIFICACOES_IBS_CBS, que é a mesma tabela já usada pelo cadastro manual de Classificações Tributárias existente no sistema. Ou seja, não criamos uma tabela nova e paralela — reaproveitamos a estrutura já existente, apenas incluindo os novos campos de alíquotas necessários para a Reforma Tributária.

O processamento de cada classificação segue esta lógica:

O sistema verifica se já existe um registro daquele mesmo código de classificação tributária cuja vigência (data início/fim) tenha sobreposição com o período informado pelo TaxEngine.
Se existir um registro compatível, ele é atualizado — as alíquotas, datas de vigência e demais campos são sobrescritos com os valores mais recentes vindos do TaxEngine.
Se não existir, um novo registro é criado.

Essa regra existe para garantir que nunca fiquem dois registros ativos e vigentes ao mesmo tempo para o mesmo código de classificação, o que poderia gerar ambiguidade na hora de calcular os impostos (o sistema não saberia qual alíquota usar).

Todo o processamento de uma sincronização acontece dentro de uma única transação: se algum item falhar ao ser salvo, nada é gravado, evitando que a base fique com dados parciais ou inconsistentes.

5. Tratamento de inconsistências vindas da API¶

Foi identificado que o TaxEngine pode, eventualmente, retornar duas entradas para o mesmo código de classificação, com vigências diferentes e ambas "em aberto" (sem data de fim definida). Para evitar erros durante a persistência nesses casos, o sistema aplica uma regra de negócio: quando isso acontece, prevalece sempre a vigência mais recente (a de data de início mais nova), entendendo que ela substitui/encerra a vigência anterior. As demais entradas duplicadas daquele código são descartadas naquela execução.

6. Proteção contra dados maiores que o esperado¶

Alguns campos de texto retornados pela API (como a descrição da classificação tributária e a mensagem de log de integração) possuem um tamanho máximo suportado pelas colunas do banco de dados. Caso o TaxEngine retorne um texto maior que o suportado, o sistema automaticamente corta o excesso, mantendo apenas os primeiros caracteres permitidos, evitando erro de gravação.

7. Registro de histórico (log de integração)¶

Ao final de cada execução — seja ela bem-sucedida ou não — o sistema grava um registro de histórico informando:

O endpoint que foi chamado;
A data/hora da execução;
Se a execução teve sucesso ou erro;
Uma mensagem descritiva do resultado (incluindo detalhes do erro, se houver).

Esse histórico é o ponto de partida para qualquer investigação/suporte, permitindo verificar rapidamente se o sincronismo do dia ocorreu com sucesso e, em caso de falha, qual foi o motivo.

Como essas informações são usadas no cálculo dos impostos¶

Depois que as classificações tributárias e alíquotas estão persistidas na base do FoccoERP, elas são utilizadas pela rotina de cálculo de custos/impostos (o "motor de cálculo" interno do FoccoERP) sempre que um item precisa ter seus tributos de CBS/IBS calculados.

O cálculo sempre considera a data do processo (a data de referência da operação sendo calculada) contra as datas de vigência de cada classificação tributária, garantindo que:

Operações atuais usem as alíquotas vigentes na data de hoje;
Reprocessamentos de datas passadas (histórico) usem corretamente as alíquotas que estavam vigentes naquela época, mesmo que já tenham sido substituídas por vigências mais novas.

Resumindo o fluxo em uma frase¶

Uma vez por dia, o FoccoERP se conecta ao TaxEngine, busca a lista atualizada de classificações tributárias e alíquotas de CBS/IBS, atualiza (ou cria) esses registros na base local — sempre garantindo um único registro vigente por código — e registra um histórico de tudo o que aconteceu, para que o cálculo de impostos do dia a dia use sempre a informação mais correta e atualizada, sem depender de uma consulta externa em tempo real.

Perguntas frequentes¶

O que acontece se o TaxEngine estiver fora do ar no dia da sincronização? A execução falha, o erro é registrado no histórico de integração, e a base de dados local permanece com as últimas alíquotas sincronizadas com sucesso (nada é perdido ou zerado). No dia seguinte, uma nova tentativa de sincronização é realizada automaticamente.

Se uma alíquota mudar no meio do mês, o sistema já calcula corretamente a partir da mudança? Sim. Cada alíquota tem uma data de início e fim de vigência. O motor de cálculo sempre escolhe a alíquota vigente para a data da operação sendo calculada, então uma alteração de vigência é respeitada automaticamente, tanto para operações novas quanto para reprocessamentos de datas anteriores.

É possível cadastrar/alterar uma classificação tributária manualmente, sem depender do sincronismo? Sim, a tela de cadastro manual já existente continua funcionando normalmente, pois utiliza a mesma tabela. O sincronismo apenas mantém os dados atualizados automaticamente, sem impedir ajustes manuais quando necessário.