Critério 1: latência alvo
Latência é o primeiro filtro técnico.
O que medir
Tempo entre envio do payload e recebimento da resposta no endpoint. Medir em p50, p95, p99, não só média. P99 elevado destrói experiência no checkout.
Faixa aceitável para checkout B2B
A faixa aceitável depende do tempo total que o checkout tolera. Em operações B2B brasileiras maduras, latência da chamada Tax Service tipicamente fica em tempo real. O motor Mastery opera nessa faixa, com arquitetura em Google Cloud.
Cuidados na medição
Medir em condição realista (rede, payload representativo, volume de itens). Latência baixa em sandbox vazio não vale para produção sob carga.
Critério 2: cobertura de regra brasileira
Regra B2B brasileira é multi camada.
Regras essenciais
ICMS por par origem-destino, ICMS-ST por Convênio 142 de 2018 (confaz.fazenda.gov.br) e regulamento estadual, DIFAL por LC 190 de 2022 (planalto.gov.br/ccivil_03/leis/lcp/lcp190.htm) e EC 87 de 2015, IPI por TIPI vigente (gov.br/receitafederal), PIS e COFINS conforme regime, ISS quando aplicável.
Regras emergentes (Reforma)
IBS, CBS, IS conforme LC 214 de 2025 (planalto.gov.br/ccivil_03/leis/lcp/lcp214.htm). Coexistência ICMS+IBS, PIS/Cofins+CBS durante a transição 2027 a 2033. Split Payment conforme regulamentação.
Casos avançados
Benefícios fiscais estaduais (ES, MG, BA, PE, RS e outras), regimes especiais, MVA dinâmica por UF e produto, tratamento por CNAE secundário, habilitação setorial (ANVISA, IBAMA).
Como testar cobertura
Levar 20 a 30 cenários representativos do seu catálogo e operação. Testar em sandbox. Conferir resultado contra expectativa do fiscal interno.
Critério 3: payload e contrato da API
API bem desenhada economiza esforço de integração.
Estrutura do payload
Envio mínimo: itens (SKU, NCM, quantidade, preço unitário), comprador (CNPJ, perfil), endereço (UF origem, UF destino), modalidade (revenda, uso próprio). Mais campos quando relevantes (regime do comprador, CNAE, contexto da operação).
Estrutura da resposta
Por item: alíquota efetiva por tributo, base de cálculo, destaque, CFOP, CST, observação fiscal. Por pedido: total com impostos, memória completa, marcação para NF.
Versionamento
API versionada (v1, v2). Mudanças com retrocompatibilidade quando possível. Anúncio prévio de breaking changes. Documentação por versão.
Códigos de erro
Mensagens claras. Distinguir erro do cliente (payload inválido, autenticação falhou) de erro do servidor (timeout, regra ausente). Códigos HTTP usados conforme padrão.
Critério 4: ambiente sandbox
Sandbox é onde a integração nasce.
O que esperar do sandbox
Endpoint estável, regras atualizadas (espelhando produção), credenciais separadas, sem custo de chamada, com possibilidade de gerar volume de teste sem afetar produção.
Ferramentas auxiliares
Postman collection, exemplos de payload, documentação clara, guia de início rápido. Engenheiro consegue fazer primeira chamada em minutos.
Suporte do fornecedor
Canal direto com engenheiro de suporte do fornecedor durante integração. Tempo de resposta razoável. Em casos críticos, sessão de pareamento.
Critério 5: fallback e resiliência
API fiscal indisponível não pode parar o checkout.
Estratégias de fallback
Cálculo simplificado de contingência, retentativa automática, fila de aprovação manual, cache de regra para SKUs frequentes. A política é decidida no setup, conforme apetite de risco.
SLA de disponibilidade
Verificar SLA contratual e histórico operacional. Em B2B, indisponibilidade prolongada destrói confiança do canal.
Plano de comunicação
Em incidente, comunicação clara entre fornecedor e cliente. Status page acessível, equipe de plantão, post mortem após incidente.
Plano de rollback
Em release que apresenta problema, rollback rápido para versão anterior. Critério de rollback documentado.
Critério 6: segurança
API fiscal lida com dados sensíveis (CNPJ, preços, política comercial).
Autenticação
Padrões reconhecidos (HTTPS, autenticação no cabeçalho, chave e secret, eventualmente OAuth). Credenciais separadas por ambiente.
Criptografia em trânsito
TLS 1.2 ou superior. Sem chamadas em HTTP plain.
Tratamento de dados
LGPD aplicável a CNPJ de empresas (em alguns casos). Política de retenção, logs, anonimização quando necessário.
Auditoria
Logs por chamada com identificador único, retenção mínima de tempo, possibilidade de auditoria fiscal interna.
Critério 7: documentação e DX (developer experience)
DX boa acelera integração e reduz custo.
Documentação clara
Referência da API, exemplos, casos de uso, troubleshooting comum, FAQ. Documentação atualizada conforme versões.
Guias específicos para plataforma
Guia VTEX, guia Shopify, guia Magento, guia integração com SAP, TOTVS, Oracle. O motor Mastery oferece guias específicos para os stacks mais comuns.
Comunidade ou canal de devs
Slack, fórum, GitHub, repositório de SDKs. Espaço para perguntas e troca.
Changelog visível
Histórico de mudanças, notas de release, próximas atualizações. Time técnico pode planejar.
Critério 8: preparação para Reforma Tributária
Reforma Tributária vai exigir adaptação contínua.
O que avaliar
O motor já calcula IBS, CBS, IS em sandbox? Está preparado para coexistência ICMS+IBS durante a transição? Suporta Split Payment conforme regulamentação? Tem roadmap publicado para os marcos da transição?
A Mastery e a Reforma
A Mastery está preparada para cálculo em coexistência durante a transição 2027 a 2033, com IS aplicado conforme regulamentação por NCM listado. Atualizações de regra entram no motor sem deploy do cliente.
O que isso significa para o time técnico
Menos investimento em refundação do stack interno, mais tempo para atuar onde diferencia. A camada fiscal de checkout fica como serviço sustentado.
Como conduzir uma POC (prova de conceito)
Avaliar fornecedor sem assumir custo grande.
Passo 1: definir escopo limitado
Escopo claro: 1 plataforma, 10 SKUs representativos, 3 UFs de destino, 2 regimes de comprador. Limite de cenários. Limite de tempo.
Passo 2: critérios mensuráveis
Latência alvo, cobertura mínima esperada, comportamento em fallback, qualidade da documentação. Pesos definidos antes do teste.
Passo 3: integração técnica
Engenheiro do cliente integra ao stack em sandbox. Mede latência, cobertura, payload. Anota dificuldades.
Passo 4: validação fiscal
Fiscal interno do cliente confere resultados. Compara contra expectativa. Marca divergências.
Passo 5: relatório de POC
Documento com resultados quantitativos e qualitativos, comparação contra critérios, recomendação final. Decisão informada.
Perguntas frequentes
Qual a latência aceitável de API fiscal B2B no checkout?
Em operações B2B brasileiras maduras, a latência da chamada Tax Service costuma ficar em tempo real. O motor Mastery opera nessa faixa em arquitetura cloud na Google Cloud. Avaliar p50, p95 e p99 em condição realista.
Como avaliar cobertura de regra do motor fiscal?
Levar 20 a 30 cenários representativos do catálogo e da operação (ICMS interestadual, ICMS-ST por convênio, DIFAL, IPI por sub-NCM, regime do comprador, benefício estadual). Testar em sandbox. Validar com fiscal interno.
O motor Mastery tem ambiente sandbox?
Sim. A Mastery oferece sandbox com regras atualizadas espelhando produção, credenciais separadas, documentação técnica e suporte durante a integração. Postman collection e guias específicos para VTEX, Shopify, Magento e plataformas custom.
Como funciona o fallback se o motor estiver indisponível?
A política de fallback é configurada no setup. Possibilidades: cálculo simplificado de contingência, retentativa automática, fila de pedidos para aprovação manual, cache para SKUs frequentes. A escolha depende do apetite de risco do cliente.
A API Mastery está preparada para a Reforma Tributária?
Sim. O motor calcula IBS, CBS e IS conforme regulamentação publicada (LC 214 de 2025), suporta coexistência ICMS+IBS e PIS/Cofins+CBS na transição 2027 a 2033, e está preparado para Split Payment conforme cronograma de implementação dos gateways.
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: Solicitar acesso ao sandbox Mastery
Leituras relacionadas: - Como integrar cálculo fiscal Mastery via API REST - VTEX cálculo de imposto: como o motor Mastery integra com a plataforma - Motor fiscal SAP: alternativa cloud para e-commerce B2B brasileiro - Tecnologia Mastery