Como integrar a emissão de NF-e por API ao seu sistema

Se o seu sistema precisa emitir notas fiscais, existem dois caminhos: falar direto com os webservices da SEFAZ ou usar uma API de emissão. Este guia explica a diferença e o que observar na integração.

O caminho direto: falar com a SEFAZ

Integrar direto com a SEFAZ significa implementar o layout do XML, a assinatura digital, a comunicação SOAP com os webservices de cada estado, o tratamento das respostas e das rejeições, o armazenamento dos arquivos e as rotinas de contingência. Cada estado tem particularidades, e os layouts mudam por notas técnicas. É um trabalho que precisa ser mantido continuamente, mesmo quando o seu produto não é fiscal.

O caminho por API de emissão

Com uma API de emissão, o seu sistema envia os dados da operação em um formato simples e recebe o resultado. Quem mantém a integração com a SEFAZ é o serviço. No dfehub, a chamada é um POST em /v1/nfe, com os dados em JSON, TXT ou XML.

Pontos importantes da integração

Alguns cuidados valem para qualquer integração de emissão:

• Autenticação: a requisição leva uma API key no cabeçalho. Guarde a chave no servidor, nunca no navegador ou no aplicativo do cliente.
• Idempotência: envie uma chave de idempotência, como o número do pedido. Se a requisição for repetida por timeout ou falha de rede, a nota não é emitida duas vezes.
• Webhooks: cadastre uma URL e os eventos desejados, como nfe.autorizado e nfe.rejeitado, e receba o resultado no seu sistema em vez de ficar consultando. O segredo gerado no cadastro permite validar que a chamada veio do dfehub.
• Tratamento de erro: trate rejeições como parte do fluxo normal. Mostre ao usuário o motivo e permita corrigir e reenviar.
• Ambientes: use homologação durante o desenvolvimento e só depois mude para produção.

O que fica fora do seu servidor

Com uma API de emissão, o certificado digital não precisa estar no seu servidor. No dfehub, o certificado A1 é enviado uma vez pelo painel e fica cifrado em cofre. Isso reduz a superfície de risco, já que o certificado é a assinatura da empresa.

Um roteiro de integração

Um caminho prático para começar:

• Crie a conta e envie o certificado A1 pelo painel.
• Gere uma API key e faça uma emissão de teste em homologação.
• Mapeie os dados do seu sistema (cliente, itens, impostos) para o payload da API.
• Configure o webhook para receber o resultado.
• Teste os casos de erro: dados inválidos, rejeição, reenvio com a mesma chave de idempotência.
• Valide a configuração fiscal com o contador e só então passe para produção.

Documentação

A documentação da API do dfehub está em hub.dfehub.com.br/docs.

Perguntas frequentes