Integração Delphi com API fiscal: um roteiro para sistemas legados
Como conectar aplicações Delphi e Lazarus a uma API fiscal moderna sem reescrever o ERP inteiro.
Muitos ERPs regionais foram construídos em Delphi e continuam sustentando operações críticas. Modernizar a camada fiscal não exige abandonar essa base. Uma integração HTTP bem definida permite preservar o sistema existente e consumir análise, histórico e alertas como serviços.
Começa pelo contrato
Antes de criar componentes visuais, define autenticação, timeout, serialização JSON, códigos HTTP, idempotência e política de retry. O cliente precisa devolver erros legíveis ao sistema e registrar o identificador de correlação para suporte.
Componente compartilhado
Uma unit comum pode encapsular URL base, chave Bearer, criação de requisições, leitura de respostas e exceções. Delphi moderno pode usar THTTPClient; Lazarus pode usar fphttpclient. A interface pública deve esconder essas diferenças do restante do ERP.
Fluxo de pré-análise
O sistema monta a operação com identificador da empresa, UFs, NCM, CEST, CFOP, CST ou CSOSN, valor e indicadores necessários. Envia um POST com Idempotency-Key e X-Correlation-Id. A resposta retorna score, risco, versão e achados.
Trata cada código HTTP
401 indica chave ausente ou inválida; 403 aponta falta de permissão; 422 contém problemas de validação; 429 pede espera por rate limit; 5xx exige retentativa controlada. Repetir cegamente qualquer erro cria duplicidade e sobrecarga.
Não grava segredo em tela
A chave deve ficar em configuração protegida, com acesso restrito e possibilidade de rotação. Logs nunca devem imprimir o token completo. No servidor, somente o hash da chave é armazenado.
Webhooks para eventos assíncronos
Quando a importação ou análise termina depois, um serviço receptor pode validar a assinatura HMAC e colocar o evento em uma fila local. O processamento não deve acontecer dentro da resposta HTTP do webhook.
Implantação em etapas
Começa com consulta manual e ambiente de teste. Depois adiciona pré-análise em um fluxo controlado, monitora latência e falsos positivos e só então decide se algum código pode bloquear emissão.
O melhor projeto de integração é o que acrescenta capacidade sem tornar o ERP dependente de detalhes internos do serviço.