Pré-requisitos antes de começar
Antes do primeiro passo técnico, três frentes precisam estar prontas.
Conta VTEX com perfil Enterprise ou compatível
A integração com Tax Service externo é suportada em planos Enterprise da VTEX. Confirmar com gerente de conta VTEX qual é o perfil contratado e quais funcionalidades estão habilitadas.
Contrato Mastery ativo
Cadastro Mastery completo, credenciais de API (chave, secret, ambiente sandbox e produção), URL do Tax Service Mastery e suporte técnico Mastery alocado para a integração.
Catálogo com dados fiscais
NCM atualizado contra TIPI vigente (gov.br/receitafederal), CFOP por tipo de operação, CST por SKU, regime fiscal definido. Sem catálogo limpo, o motor recebe dado inconsistente e gera cálculo divergente.
Etapa 1: kick-off técnico
A primeira reunião alinha escopo e responsabilidades.
Participantes recomendados
CTO ou líder técnico do cliente, time de desenvolvimento, fiscal interno, gerente de e-commerce, time Mastery (CSM, suporte técnico, engenheiro), eventualmente parceiro VTEX implementador.
Pauta padrão
Mapeamento de catálogo (volume de SKUs, NCMs dominantes, verticais), regras fiscais aplicáveis (UFs atendidas, ICMS-ST aplicável, DIFAL, IPI), política comercial B2B (tabelas, regimes, prazos), fluxos atuais de pedido e aprovação, cronograma e marcos.
Saída esperada
Documento de escopo, cronograma, lista de stakeholders, definição de ambiente sandbox e produção, checklist de pré-requisitos.
Etapa 2: configuração do Tax Service no admin VTEX
A VTEX expõe a configuração no admin para cadastrar Tax Service externo.
Onde configurar
No admin VTEX, em Settings ou no módulo de Fiscal Configuration (a navegação pode variar conforme versão). A documentação oficial VTEX detalha o caminho atual.
Campos a preencher
URL do endpoint Mastery (sandbox primeiro, produção depois), credenciais de autenticação (chave e secret recebidos da Mastery), timeout recomendado, configuração de fallback em caso de indisponibilidade.
Validação inicial
O admin permite teste de conectividade. Fazer uma chamada de teste, conferir que o motor Mastery responde, validar resposta minimamente. Esse é o aceite técnico do canal.
Boas práticas
Iniciar em sandbox, não em produção. Manter ambiente de homologação espelhado. Documentar credenciais em gerenciador seguro.
Etapa 3: revisão de catálogo no VTEX
O motor consome dados fiscais do catálogo VTEX. Catálogo limpo é pré-requisito.
NCM por SKU
Cada SKU precisa ter NCM correto preenchido na ficha do produto. Conferir contra TIPI vigente. NCM divergente é a fonte mais comum de erro fiscal em e-commerce B2B brasileiro.
CFOP base por operação
CFOP padrão de venda, devolução, demonstração, remessa configurados conforme política. O motor aplica conforme contexto da operação.
CST por SKU
Código de Situação Tributária por SKU, considerando regime tributário do vendedor e tratamento do produto. Em SKUs com tratamento diferenciado (cesta básica, redução de base), CST específico.
Marca de operação especial
SKUs com ICMS-ST, redução de base, isenção, suspensão precisam de marcação. O motor consome essas marcações.
Volume e priorização
Em catálogos grandes (10 mil SKUs ou mais), priorizar revisão por volume de vendas. Top 20% dos SKUs costuma responder por 80% do faturamento; começar por eles.
Etapa 4: configuração da política comercial
Política comercial alimenta o motor com contexto.
Tabelas de preço
Tabelas configuradas no admin VTEX (preço por regime, por canal, por UF, por contrato). O motor aplica a tabela aplicável conforme perfil do comprador.
Fluxos de aprovação
Definir critérios de aprovação automática (faixa de score, limite, prazo) e quando o pedido vai para fila manual (exceções, contestações, contas estratégicas).
Integração com crédito
A Análise de Crédito B2B com base em score de CNPJ de bureau de crédito entra no fluxo de aprovação. Configurar parâmetros de política.
Regras de exceção
Compradores estratégicos, contratos especiais, condições negociadas. Documentar e codificar no motor.
Etapa 5: ambiente sandbox e testes
Antes do go live, validar cenários.
Cenários mínimos
Pedido simples PJ revenda mesma UF. Pedido PJ revenda interestadual com ICMS-ST. Pedido PJ uso próprio interestadual com DIFAL. Pedido com IPI por sub-NCM específico. Pedido PJ Simples Nacional. Pedido com benefício estadual aplicável.
Validação fiscal interna
O fiscal interno do cliente confere cálculo, alíquotas, bases, destaques, CFOP, CST. Compara com regras vigentes e com expectativa.
Validação de NF
Em alguns casos, validação contra emissão real de NF-e em ambiente de homologação. A nota precisa sair correta na primeira tentativa.
Validação de performance
Latência da chamada Tax Service. Comportamento sob carga (volume simulado). Resposta em caso de timeout. Plano de fallback.
Documentação de cenários aceitos
Cada cenário validado fica documentado com payload, resposta e validação. Esse documento serve como base de auditoria contínua.
Etapa 6: go live e migração para produção
Migrar com cuidado.
Estratégia de go live
Janela de baixo tráfego, monitoramento ativo, equipe de plantão. Cliente pode optar por go live por loja, por UF ou por canal, conforme apetite de risco.
Atualizar configuração para ambiente produção
Trocar URL do Tax Service para endpoint de produção. Trocar credenciais. Confirmar conectividade.
Monitorar nas primeiras horas
Alertas configurados, dashboard de cálculos, comparação contra expectativa. Em caso de anomalia, plano de rollback testado.
Comunicação interna
Time comercial, fiscal e atendimento avisados sobre o go live. Procedimento de escalonamento em caso de incidente.
Etapa 7: operação contínua
Pós go live, manter ciclo de melhoria.
Monitoramento de cálculos
Logs por pedido, dashboards de performance, alertas em divergência. O time Mastery acompanha junto com o time do cliente.
Atualização de regras
Conforme regulamentação publicada (mudanças em convênios, alíquotas, NCMs), o motor recebe atualização. O cliente não precisa fazer deploy.
Revisão de catálogo
NCM, CFOP e CST devem ser revistos periodicamente. SKUs novos passam por validação fiscal antes de subir.
Evolução do escopo
Conforme novos canais, verticais ou geografias, ajustar configuração. A integração suporta evolução incremental.
Setup típico em casos com catálogo organizado
Em operações com dados organizados, setup completo (kick-off ao go live) pode ser concluído em poucas semanas. Esse foi o padrão observado em parte dos casos Mastery, incluindo Banana Brasil.
Em operações com catálogo grande e desorganizado, o investimento prévio em limpeza de dados pode adicionar semanas ao cronograma. A leitura de catálogo (NCM, CFOP, CST por SKU) é o trabalho que mais consome tempo na fase preparatória.
Perguntas frequentes
Quanto tempo demora a integração VTEX + Mastery?
Em operações com catálogo organizado (NCM atualizado, CFOP definido, CST por SKU), o setup completo pode ser concluído em poucas semanas. Em catálogos grandes e desorganizados, o investimento prévio em limpeza adiciona tempo.
Preciso de plano Enterprise VTEX para usar Mastery?
A integração com Tax Service externo é suportada em planos Enterprise e compatíveis da VTEX. Confirmar com gerente de conta VTEX qual é o perfil contratado e quais funcionalidades estão habilitadas.
Como funciona a autenticação entre VTEX e Mastery?
Mastery emite credenciais de API (chave e secret) cadastradas no admin VTEX no momento de configurar o Tax Service. As chamadas usam HTTPS com autenticação no cabeçalho. Sandbox e produção têm credenciais separadas.
O motor Mastery suporta benefícios fiscais estaduais?
Sim. Benefícios estaduais (incentivos, regimes especiais, programas setoriais) podem ser configurados no motor, com aplicação automática quando o perfil do comprador e o produto se enquadram. A configuração é feita junto com o time Mastery no setup.
O que acontece se o motor Mastery estiver indisponível?
A configuração inclui plano de fallback. Possíveis estratégias: cálculo simplificado de contingência, retentativa automática, fila de pedidos com aprovação manual no fallback. A política é definida no kick-off técnico conforme apetite de risco do cliente.
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 kick-off técnico VTEX + Mastery
Leituras relacionadas: - VTEX cálculo de imposto: como o motor Mastery integra com a plataforma - Como integrar cálculo fiscal Mastery via API REST - Setup em 10 dias úteis: timeline real de implementação Mastery - Tecnologia Mastery