O que a API faz, em uma lista
A API expõe as mesmas funções do site, com o formato que um sistema consegue consumir. Os dois endpoints principais estão documentados com exemplos de cURL e de resposta em documentação da API:
- POST /api/v1/generate: recebe o XML e devolve o PDF em base64, o tipo (NF-e ou CT-e), um resumo com a chave e o tempo de processamento.
- GET /api/v1/danfe/{chave}: consulta a NF-e pela chave de 44 dígitos e devolve PDF, XML e resumo.
- Autenticação por chave secreta no cabeçalho Authorization, gerada e revogada no painel da conta.
- Respostas sempre em JSON, sobre HTTPS.
Onde a API se encaixa
ERP que recebe XML de fornecedores e precisa mostrar o DANFE ao usuário. TMS que gera o DACTE de cada CT-e emitido. Sistema de escritório contábil que monta a pasta de documentos do cliente. Portal de compras que anexa o PDF da nota ao pedido. Em todos esses casos, a alternativa à API é manter um gerador de PDF próprio, com o leiaute do DANFE e do DACTE, e atualizá-lo sempre que o leiaute mudar.
Para o lado de negócio dessa decisão, com prós e contras de cada caminho, leia API DANFE para ERP. Se o volume é pequeno e manual, o site resolve: veja DANFE online. Para o caso específico do transporte, com DACTE gerado a partir do CT-e, veja DACTE online.
Tratamento de erros que o seu sistema deve prever
A API usa os códigos HTTP de forma previsível, e o seu sistema deve tratar cada um de um jeito diferente, em vez de repetir a chamada às cegas:
- 400: XML ausente, vazio ou grande demais. Corrija a entrada; repetir não resolve.
- 422: XML inválido ou com DOCTYPE/ENTITY. Mostre o erro ao usuário e peça outro arquivo.
- 401: chave de API ausente ou inválida. Confira o cabeçalho Authorization.
- 402: créditos insuficientes. Avise o responsável pela conta.
- 429: limite de requisições excedido. Espere e tente de novo mais tarde.
Consulta por chave: o que esperar da resposta
O endpoint de consulta segue a mesma lógica do site. Se a nota já foi processada, a resposta vem do cache. Se não, o sistema busca o documento completo no acervo e, quando não há documento completo disponível, usa a consulta pública, que divulga só o resumo da nota, sem itens. O seu sistema deve tratar esse caso: para o DANFE completo, o caminho é enviar o XML pelo endpoint de geração.
Antes de chamar a consulta, vale validar a chave no seu próprio código. O dígito verificador usa o módulo 11, e a regra está em como validar chave de acesso da NF-e. Chave inválida não deveria nem sair do seu sistema.
Segurança e boas práticas de integração
A chave de API é secreta e deve ficar no servidor. Nunca a coloque no front-end, em aplicativo móvel distribuído ou em repositório de código. Se ela vazar, revogue no painel e gere outra. Guarde o XML original no seu sistema: o PDF devolvido pela API é uma representação, e o documento fiscal válido continua sendo o XML. O uso da API exige assinatura ativa; as opções estão em planos e créditos.