Como integrar um ERP à análise fiscal com API, idempotência e webhooks
Um roteiro técnico para software houses enviarem operações, consultarem resultados e receberem eventos sem duplicar trabalho.
Uma integração fiscal útil não deveria obrigar cada ERP a reproduzir toda a leitura de XML ou manter centenas de detalhes internos do motor. A API precisa receber uma operação de alto nível, devolver um contrato previsível e permitir que o sistema chamador decida o que fazer.
O fluxo recomendado
O ERP envia dados como empresa, UFs de origem e destino, NCM, CEST, CFOP, CST ou CSOSN, valor, consumidor final e data da operação. A resposta traz nível de risco, score, versão do motor, identificador de correlação e uma lista de achados estruturados.
Idempotency-Key evita análises duplicadas
Falhas de rede acontecem. Se o cliente não sabe se o servidor recebeu a requisição, ele precisa repetir. Ao enviar uma Idempotency-Key estável, a repetição pode retornar a análise original, identificada por um cabeçalho de replay. Isso protege cobrança, histórico e automações contra duplicidade.
Correlação para suporte
O X-Correlation-Id acompanha a requisição e volta na resposta. Quando ERP, API e webhook registram o mesmo identificador, o suporte consegue seguir o caminho de uma operação entre sistemas sem depender de horário aproximado ou captura de tela.
Webhooks assinados
Para tarefas assíncronas, o Certa Fiscal pode notificar eventos como analysis.completed, critical_risk.detected, import.completed e rule.updated. O corpo é assinado com HMAC-SHA256. O receptor recalcula a assinatura com o segredo e usa comparação segura antes de processar.
Retentativa e proteção
A entrega usa backoff exponencial e limita tentativas. Integrações com falhas consecutivas podem ser desativadas para evitar carga inútil. URLs privadas ou de loopback são rejeitadas, inclusive depois da resolução DNS, reduzindo risco de SSRF.
Permissões e isolamento
Chaves pertencem a um tenant, são armazenadas somente como hash e podem ter permissões, limite por minuto, expiração e revogação. Identificadores públicos usam ULID em vez de IDs sequenciais.
Uma boa integração não é apenas um endpoint que responde. É um contrato com repetição segura, rastreabilidade, isolamento e comportamento previsível diante de falhas.