Por que o motor fiscal no checkout precisa ser síncrono

Antes de discutir como fazer rápido, é útil entender por que o cálculo precisa ser síncrono no B2B.

Pré-cálculo vs tempo real

Modelo antigo: a operação faz pré-cálculo de imposto. Antes do cliente chegar no checkout, a equipe já calculou uma matriz de impostos para as principais combinações de NCM, destino e regime, e armazenou em cache. Quando o cliente chega, o sistema busca o valor pré-calculado rapidamente. Parece eficiente, mas tende a ser impreciso.

Por quê? Porque o pré-cálculo dificilmente cobre todas as combinações. O cliente compra 50 unidades de parafuso de um NCM, mas é MEI (regime especial). A tabela pré-calculada pode não ter a entrada exata para “esse NCM + MEI + UF de destino”. O sistema usa aproximação. Resultado: o imposto pode ficar diferente do correto, dependendo do caso.

Modelo síncrono: o motor calcula em tempo real quando o cliente adiciona o item, considerando:

Resultado: cálculo mais aderente ao caso concreto. Trade-off: precisa ser rápido. O resultado pode variar por UF, regime, NCM, operação e perfil do comprador, então o motor precisa lidar com essa combinação.

O custo da imprecisão fiscal

Imprecisão fiscal tende a custar conversão de duas formas:

  1. O cliente vê um valor no checkout e depois recebe nota fiscal com valor diferente, abrindo chamado de suporte e podendo cancelar.
  2. O cliente passa a desconfiar do preço apresentado, especialmente em operações de ticket alto.

A magnitude desse impacto varia por operação. Não há benchmark único publicado, mas operações que medem essa métrica costumam tratá-la como prioritária.

Anatomia de um cálculo fiscal síncrono

Cálculo rápido não é mágica. É engenharia.

Pipeline: cadastro > NCM > regras > resultado

Quando o cliente clica em “Calcular” no checkout, o sistema executa um pipeline. Os tempos abaixo são alvos típicos de arquitetura, não garantias. Latências reais variam com volume, infraestrutura, complexidade do cenário e qualidade do cadastro.

Passo 1: Validar cadastro. CNPJ, inscrição estadual e regime do cliente já foram validados em onboarding. O checkout faz lookup em índice (CNPJ confirmado, regime conhecido). Elegibilidade da operação é também pré-validada.

Passo 2: Resolver NCM. Sistema busca o NCM associado ao produto em índice. Validações de formato (8 dígitos, NCM existente) são feitas em memória, sem chamada HTTP.

Passo 3: Resolver CFOP. CFOP é função de origem, destino e regime. O sistema usa tabela compilada de regras.

Passo 4: Resolver CST. Depende do regime do cliente e do tipo de operação. Tabela compilada.

Passo 5: Calcular alíquotas. ICMS origem e destino, ICMS-ST quando aplicável, DIFAL quando aplicável, IPI quando aplicável, benefícios estaduais. Onde possível, executa em paralelo.

Passo 6: Compilar resultado. Retorna JSON com breakdown por tipo de imposto.

O objetivo de design é manter o cálculo praticamente instantâneo, executado de forma síncrona. O comportamento observado em produção depende de cada cenário.

Onde está o tempo gasto

Quando o cálculo fiscal de uma operação demora muito mais do que isso, costuma haver causas recorrentes:

Causa comum 1: chamadas HTTP síncronas a serviços externos a cada cálculo. Cada lookup remoto adiciona latência de rede. A mitigação é cache local sincronizado periodicamente.

Causa comum 2: banco relacional remoto para lookups simples. Latência de rede mais tempo de query, multiplicadas por várias consultas. A mitigação é índice em memória.

Causa comum 3: regras fiscais codificadas como lógica imperativa extensa. Centenas de “if” tornam o caminho de execução longo. A mitigação é compilar regras em estrutura otimizada (máquina de estados, engine de regras).

Causa comum 4: recalcular todos os itens do carrinho a cada mudança. A mitigação é cache por item e recálculo incremental.

A stack do Syntax (motor da Mastery)

Syntax é o motor fiscal cloud da Mastery (não confundir com Systax, empresa diferente, adquirida pela Vertex Inc.). A seguir, a arquitetura geral.

Tecnologias usadas

Camada de entrada: API REST que recebe payload mínimo com item e cliente. O carrinho completo permanece no frontend.

Backend: linguagem de alto desempenho, sem ORM pesado, acesso direto a índices.

Cache em memória: Redis ou estrutura equivalente, armazenando tabelas de ICMS, MVA, benefícios e histórico de validações de cliente com TTL definido.

Sincronização de cache: job diário que puxa dados atualizados e recompila índices, com switchover sem downtime.

Base de dados: PostgreSQL ou similar para dados persistentes, com materialized views atualizadas periodicamente.

API: REST simples, payload comprimido.

Benchmark de performance

A Mastery monitora P50, P95 e P99 internamente, em ambiente de produção. Valores específicos podem ser compartilhados sob acordo, durante apresentação técnica.

Sobre comparação com outros motores: tax engines tradicionais foram desenhados, em geral, para processamento batch ou para serem chamados de dentro do ERP, com perfis de latência diferentes do checkout síncrono de e-commerce. Comparações numéricas com fornecedores específicos não são publicadas neste material, porque os números variam por configuração, região e cenário, e não há fonte pública verificável que cubra todos os casos.

Como integrar via API REST

A equipe técnica pode integrar o Syntax ao checkout VTEX, Shopify ou custom através de uma API REST.

Exemplo de request

{
  "client": {
    "cnpj": "12345678901234",
    "regime": "contribuinte",
    "state": "SP"
  },
  "items": [
    {
      "ncm": "73071900",
      "quantity": 100,
      "unit_value": 10.50,
      "origin_state": "MG"
    }
  ]
}

Exemplo de response

{
  "calculation_id": "calc_abc123",
  "timestamp": "2026-05-05T14:32:00Z",
  "items": [
    {
      "ncm": "73071900",
      "quantity": 100,
      "unit_value": 10.50,
      "subtotal": 1050.00,
      "taxes": {
        "icms": 73.50,
        "icms_st": 0,
        "difal": 12.60,
        "ipi": 0,
        "total": 86.10
      },
      "effective_rate": "8.2%"
    }
  ],
  "totals": {
    "items_subtotal": 1050.00,
    "total_taxes": 86.10,
    "final_value": 1136.10
  },
  "audit": {
    "rules_applied": ["ICMS_MG", "ICMS_ST_SP", "DIFAL_SP_REGIME_CONTRIBUINTE"],
    "data_sources": ["receita_federal", "sefaz_mg", "sefaz_sp"]
  }
}

Os valores acima são ilustrativos. O imposto efetivo pode variar por UF, regime, NCM, operação e perfil do comprador.

Tratamento de erros

Webhooks de auditoria

A operação pode registrar webhook para receber log de cada cálculo, para fins de auditoria e integração com ERP.

Erros comuns que afetam a performance

Erro 1: validação cadastral síncrona contra SEFAZ a cada carrinho. Mitigação: validar no onboarding e usar cache.

Erro 2: recalcular todos os itens do carrinho a cada mudança. Mitigação: cache por item, recálculo incremental.

Erro 3: depender exclusivamente de pré-cálculo para garantir precisão. Mitigação: cálculo síncrono com arquitetura otimizada.

Erro 4: acoplamento entre motor fiscal e processamento de NF no ERP. Mitigação: motor como serviço separado, especializado.

Erro 5: não cachear regras e tabelas. Mitigação: compilar em memória, sincronizar periodicamente.

Como medir se seu motor atual está rápido o suficiente

Use ferramentas de performance, APM e analytics:

1. Latência de cálculo (P50, P95, P99): quanto tempo entre a requisição e a resposta? Se passa de alguns segundos, vale investigar.

2. Taxa de erro: percentual de requisições com erro ou timeout. Alta taxa sinaliza arquitetura sobrecarregada.

3. Impacto no TTI da página: o cálculo bloqueia o resto da página? Idealmente, deveria rodar de forma assíncrona ou em segundo plano quando possível.

4. CPU e memória sob carga de pico: se a infra está saturada nos horários de maior tráfego, o motor não escala.

5. Taxa de divergência entre preço apresentado e preço final na NF: se clientes reclamam que o imposto da fatura é diferente do que viram no checkout, há sinal de imprecisão.

Perguntas frequentes

Como calcular ICMS, ICMS-ST, DIFAL e IPI em tempo real no checkout?

Mantendo tabelas de alíquotas e regras compiladas em memória, com cache local sincronizado periodicamente, evitando lookups remotos no caminho crítico. ICMS e ICMS-ST são calculados a partir de tabelas por UF; DIFAL é função da diferença entre alíquotas; IPI depende do NCM e do regime. Cada componente pode variar por UF, regime, NCM e operação.

Qual o tempo médio de cálculo fiscal no carrinho B2B?

Em arquiteturas modernas, o cálculo roda de forma síncrona e é praticamente instantâneo, sem fricção perceptível no checkout. O comportamento real depende da operação.

Cálculo síncrono vs pré-cálculo: qual a diferença?

Pré-cálculo armazena resultados antes do cliente chegar, ganhando velocidade mas perdendo precisão em casos não previstos. Síncrono calcula em tempo real, ganhando precisão. Arquiteturas modernas tentam combinar ambos, usando cache para acelerar o cálculo síncrono.

Como integrar motor fiscal via API REST?

POST para o endpoint com payload contendo cliente e itens. Resposta em JSON com breakdown de impostos. Documentação típica via Swagger/OpenAPI. Erros expressos por HTTP status codes.

Como medir performance do meu motor fiscal atual?

Meça latência (P50, P95, P99), taxa de erro, impacto no TTI da página, uso de CPU e memória sob pico, e taxa de divergência entre preço de checkout e preço de NF. Esses são sinais úteis para decidir se há espaço para otimização arquitetural.

Aviso importante

Este conteúdo tem caráter informativo e não substitui orientação contábil, fiscal ou jurídica especializada. Regras tributárias podem variar conforme UF, regime tributário, operação, produto, NCM, CNAE e perfil do comprador. Valide seu cenário com profissional habilitado.

Próximo passo: Ver demo do motor em ms

Leituras relacionadas: - Checkout B2B: por que a tributação é a maior fricção invisível - Por que o ERP não foi feito para a jornada tributária B2B - Integrar cálculo fiscal Mastery via API REST