Integração fiscal via API REST: documentação técnica para devs

Arquitetura básica da integração

A integração segue padrão REST com autenticação por chave.

Princípios

API REST sobre HTTPS, JSON como formato de payload, autenticação via cabeçalho com chave e secret, ambiente sandbox separado do ambiente de produção, versionamento de endpoint.

Endpoints principais

Endpoint de cálculo fiscal (POST), endpoint de validação cadastral (POST), endpoint de aprovação de pedido (POST), endpoint de consulta histórica (GET com filtros), endpoint de webhooks (eventos relevantes).

Latência alvo

O endpoint de cálculo responde em tempo real. Arquitetura usa cache para regras parametrizadas e processamento paralelo por item.

Segurança

TLS 1.2 ou superior, autenticação via chave e secret separados por ambiente, política de rotação de credenciais configurável, logs por chamada.

Endpoint de cálculo fiscal

O endpoint central da integração.

Método e URL

POST. URL base conforme ambiente (sandbox ou produção). Path versionado.

Payload de entrada

Itens do carrinho (SKU, NCM, quantidade, preço unitário, descrição). Comprador (CNPJ, perfil declarado). Endereço (UF origem, UF destino, CEP). Modalidade da operação (revenda, uso próprio, indústria). Contexto adicional (canal, contrato, política de desconto aplicável).

Resposta

Por item: alíquota efetiva por tributo (ICMS, ICMS-ST quando aplicável, IPI, DIFAL quando aplicável, e a partir da transição IBS, CBS, IS), base de cálculo, destaque, CFOP, CST, observação fiscal. Por pedido: total com impostos, memória completa, marcação para emissão de NF, identificador único para rastreamento.

Códigos de retorno

200 quando sucesso. 400 quando payload inválido (com mensagem específica). 401 quando autenticação falha. 422 quando dado inconsistente. 500 quando erro interno (com identificador para suporte). 503 quando indisponibilidade momentânea.

Endpoint de validação cadastral

A camada de Aprova CNPJ.

Método e URL

POST. Path versionado.

Payload de entrada

CNPJ, UF de operação, contexto (cadastro novo, reavaliação, evento crítico).

Resposta

Razão social, situação cadastral (ativo, suspenso, inapto, baixado, nulo), CNAE principal e secundário, regime tributário (Simples, Lucro Presumido, Lucro Real, MEI), IE válida por UF aplicável (via SINTEGRA e portal Sefaz), classificação interna (revenda, uso próprio, indústria, consumidor final empresa), recomendação (aprovado, fila, recusado conforme política).

Cuidados

Conformidade com LGPD em algumas operações (especialmente quando dados de sócios são consultados). Política de retenção configurável.

Endpoint de aprovação de pedido

Combinação de fiscal e crédito.

Método e URL

POST. Path versionado.

Payload de entrada

Identificador do cálculo prévio, dados de pagamento (cartão, boleto, prazo), sinal de crédito fornecido pelo próprio cliente quando aplicável.

Resposta

Recomendação (aprovado, fila para revisão manual, recusado), justificativa codificada, prazo aplicável quando boleto.

Política aplicada

Configurada em setup do cliente. Faixa de score, limite por faixa, prazo por faixa, exceção por canal, contrato especial.

Webhooks e eventos

Sincronização assíncrona.

Eventos disponíveis

Cálculo concluído, validação cadastral concluída, aprovação realizada, exceção em fluxo (timeout, indisponibilidade fonte), atualização de regra (mudança parametrizada que afeta cálculo).

Configuração

URL do cliente cadastrada para receber eventos. Autenticação por chave compartilhada. Política de retentativa configurável.

Boas práticas

Endpoint idempotente no lado do cliente, processamento assíncrono em filas, log de eventos recebidos para auditoria.

Os endpoints da integração em resumo

Cenários comuns de integração

Padrões em produção.

Cenário 1: cálculo no carrinho

A cada mudança no carrinho (adicionar item, mudar quantidade, atualizar endereço), chamada ao endpoint de cálculo. Resposta atualiza o preço final. Latência baixa é crítica para experiência.

Cenário 2: validação no cadastro

No primeiro acesso PJ ou na finalização do pedido, chamada ao endpoint de validação cadastral. Resposta consolidada alimenta motor de aprovação.

Cenário 3: aprovação na finalização

Após cálculo e validação, chamada ao endpoint de aprovação combinando fiscal e crédito. Resposta libera o pedido para ERP ou encaminha para fila.

Cenário 4: atualização do pedido

Em mudança pós-aprovação (cancelamento parcial, devolução, troca), chamada com identificador original. Motor recalcula e devolve.

Cenário 5: consulta histórica

Para auditoria interna, endpoint GET com filtros (data, CNPJ, status) devolve registros relevantes.

Tratamento de erro e fallback

Operação contínua exige plano.

Erro de payload

400 com mensagem específica. Cliente corrige antes de retentar.

Autenticação inválida

401. Verificar credenciais, ambiente, política de rotação.

Dado externo indisponível

503 ou 502. Política de fallback configurada (retentativa, cache, cálculo simplificado de contingência, fila para revisão manual).

Timeout

Configurado no setup. Cliente recebe resposta padrão ou erro. Plano de comunicação no incidente.

Mudança de regra em produção

Atualização Mastery sem deploy do cliente. Cliente pode receber webhook informando atualização aplicada.

Sandbox e DX

Experiência do desenvolvedor importa.

Acesso a sandbox

Credenciais separadas, endpoint estável, regras atualizadas espelhando produção, sem custo de chamada, com possibilidade de gerar volume de teste.

Ferramentas auxiliares

Postman collection, exemplos de payload, documentação clara, guia de início rápido, guias por plataforma (VTEX, Shopify, Magento, custom).

Suporte técnico

Canal direto com engenheiro de suporte Mastery durante a integração. Em casos críticos, sessão de pareamento.

Versionamento

Endpoints versionados. Breaking change anunciada com antecedência. Compatibilidade retroativa quando possível.

Caso ilustrativo: integração em e-commerce custom

Considere e-commerce B2B customizado (não VTEX, não Shopify, não Magento) em Node.js.

Setup

Sandbox Mastery cadastrado, credenciais configuradas em variáveis de ambiente, biblioteca HTTP padrão para chamada.

Integração

No checkout, função que monta payload, dispara POST ao endpoint de cálculo, recebe resposta e atualiza o estado do carrinho. Tratamento de erro com fallback configurado.

Validação cadastral

No cadastro PJ, função que dispara POST ao endpoint de validação. Resposta atualiza perfil do comprador.

Aprovação

Na finalização, função que dispara POST ao endpoint de aprovação. Resposta decide próximo passo (envio ao ERP, fila, recusa).

Webhooks

Endpoint /webhooks/mastery configurado para receber eventos. Processamento assíncrono em fila com retentativa.

Tempo total de integração

Em operações com dev sênior e catálogo organizado, integração propriamente dita pode ser concluída em poucos dias úteis. Validação e go live somam tempo conforme cenários.

Perguntas frequentes

A API Mastery suporta versionamento?

Sim. Endpoints versionados (v1, v2). Mudanças com retrocompatibilidade quando possível. Breaking change anunciada com prazo. Documentação por versão.

Como funciona autenticação na API Mastery?

Via cabeçalho HTTP com chave e secret. Credenciais separadas por ambiente (sandbox e produção). Política de rotação configurável. HTTPS obrigatório.

Qual a latência alvo do endpoint de cálculo?

Resposta em tempo real. Arquitetura usa cache para regras parametrizadas e processamento paralelo por item.

Como tratar indisponibilidade da API Mastery?

Política de fallback configurada no setup. Estratégias: retentativa automática, cache para SKUs e CNPJs frequentes, cálculo simplificado de contingência, fila de pedidos para aprovação manual. A política depende do apetite de risco do cliente.

A documentação está pública?

A documentação técnica é disponibilizada para clientes em onboarding, com Postman collection, exemplos de payload, guias por plataforma e suporte de engenheiro. Solicitar acesso via cadastro Mastery.

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: - API fiscal B2B: o que sua plataforma deve esperar - VTEX integração fiscal: passo a passo - Setup em 10 dias úteis: timeline real - Tecnologia Mastery