API DANFE para ERP

Uma API DANFE recebe o XML autorizado da NF-e ou do CT-e pelo seu sistema e devolve o PDF pronto, sem upload manual. Vale integrar quando a equipe gera documentos auxiliares todo dia dentro do ERP, TMS ou portal.

Resposta direta

Uma API DANFE é um serviço que o seu sistema chama para transformar o XML de uma nota em PDF. O ERP envia o XML autorizado, a API valida o conteúdo, identifica se é NF-e ou CT-e e devolve o DANFE ou o DACTE. Ninguém precisa baixar arquivo, abrir site e fazer upload.

Se a sua equipe gera um ou outro PDF por semana, a ferramenta no navegador resolve: basta gerar DANFE pelo XML. Se gera dezenas por dia, dentro do ERP, a integração começa a valer a pena. A página API DANFE resume o que a nossa integração oferece.

Quando o ERP precisa de uma API

O sinal mais claro é o trabalho repetido. Alguém baixa o XML do sistema, abre um site, envia o arquivo, baixa o PDF e anexa de volta. Multiplicado por centenas de notas, vira horas de trabalho e muitos arquivos trocados.

Alguns cenários onde a integração costuma compensar.

• ERP que recebe XML de fornecedores e precisa mostrar o DANFE na tela de entrada.
• TMS de transportadora que precisa do DACTE e do DANFE de cada carga.
• Portal do cliente de escritório contábil, com segunda via de notas.
• Marketplace ou hub que reúne notas de vários vendedores.
• Sistema interno que envia o PDF por e-mail junto com a cobrança.

Como funciona uma chamada

O desenho é simples e segue o padrão REST. O seu sistema faz uma requisição HTTPS com o XML no corpo, autenticada por uma chave secreta. A resposta vem em JSON.

Na nossa API, a chave vai no cabeçalho Authorization, no formato Bearer. Ela é criada e revogada no painel da conta. O PDF volta codificado em base64 dentro do JSON, junto com um resumo do documento, como a chave de acesso. Todos os detalhes, com exemplos de requisição e resposta, estão na documentação da API.

• O sistema obtém o XML autorizado da NF-e ou do CT-e.
• Envia o XML para o endpoint de geração, com a chave de API no cabeçalho.
• A API valida o XML e identifica o tipo de documento.
• A resposta traz o PDF em base64 e um resumo em JSON.
• O sistema decodifica o PDF, salva ou exibe para o usuário.

Consulta por chave de acesso

Além de gerar a partir do XML, a API permite consultar uma NF-e pela chave de acesso de 44 dígitos. Para notas de todos os estados, buscamos o documento completo no nosso acervo. Quando não há documento completo disponível, a consulta pública só divulga um resumo, sem itens. Nesse caso o sistema deve tratar o retorno como parcial e, se precisar do DANFE completo, obter o XML do emitente.

Validar a chave antes de chamar evita requisições perdidas. A estrutura dos 44 dígitos, com o dígito verificador em módulo 11, está no guia da chave de acesso NF-e de 44 dígitos. Para testes manuais, a consulta NF-e pela chave de acesso mostra o mesmo fluxo no navegador.

Segurança na integração

A chave de API dá acesso à sua conta. Trate-a como uma senha.

A nossa API recusa XML com declarações DOCTYPE ou ENTITY, por segurança. Se o seu sistema gera XML com esse tipo de cabeçalho, remova-o antes de enviar. Para uma visão mais ampla de cuidados com dados fiscais em ferramentas online, veja DANFE online é seguro?.

• Guarde a chave no servidor, em variável de ambiente ou cofre de segredos.
• Nunca exponha a chave no front-end, em aplicativo ou em JavaScript do navegador.
• Use uma chave por sistema, para poder revogar sem derrubar os outros.
• Revogue imediatamente a chave que vazar.

Erros comuns na integração

A maioria dos problemas aparece nos primeiros dias e se repete entre integrações.

O primeiro é mandar o arquivo errado: XML sem protocolo, XML de NFS-e ou um PDF convertido em texto. O segundo é não tratar os códigos de erro. A API responde com códigos HTTP diferentes para XML ausente, XML inválido, chave de API inválida, falta de créditos e excesso de requisições. Cada um pede uma ação diferente no seu sistema.

• XML ausente ou grande demais: revise o que o sistema está enviando.
• XML inválido: confira se o arquivo é o autorizado e está completo.
• Chave de API inválida: confira o cabeçalho e se a chave não foi revogada.
• Créditos insuficientes: avise o administrador da conta.
• Limite de requisições: espace as chamadas e tente de novo depois.

O que avaliar antes de escolher uma API

Antes de integrar com qualquer fornecedor, vale testar com XMLs reais da sua operação. Algumas perguntas ajudam na decisão.

Se quiser comparar opções do mercado, o guia melhores geradores de DANFE online e a página API NFe ajudam a mapear o que existe.

• A API aceita NF-e, NFC-e e CT-e, ou só NF-e?
• A documentação é pública e tem exemplos de requisição e resposta?
• Os códigos de erro são claros o suficiente para o seu sistema reagir?
• O modelo de cobrança é previsível para o seu volume?
• O fornecedor explica o que guarda dos documentos enviados?

Limites do que uma API DANFE faz

Uma API DANFE não é um emissor de notas. A nossa não emite, não cancela e não autoriza NF-e ou CT-e. Ela trabalha com documentos que já existem e já foram autorizados. Para emitir, o ERP precisa de integração com a SEFAZ e de certificado digital, normalmente por um módulo emissor próprio ou de terceiros.

O PDF gerado também não substitui o XML. O documento fiscal válido continua sendo o XML autorizado, que o seu sistema deve guardar. O guia XML NF-e ou DANFE: qual guardar explica por quê.

Perguntas frequentes

Preciso de plano para usar a API? Sim. O uso pela API exige conta com plano ativo. As opções estão em planos e créditos.

A API gera DACTE? Sim. Se o XML enviado for de CT-e, a resposta traz o DACTE.

Posso testar antes de integrar? Sim. Dá para gerar PDFs no navegador, sem cadastro, com XMLs reais da sua operação e conferir o resultado antes de escrever a integração.

A API funciona com qualquer linguagem? Sim. É uma API HTTP com JSON. Qualquer linguagem que faça requisições HTTPS consegue integrar.

A API emite nota fiscal? Não. Ela só gera o documento auxiliar a partir do XML existente ou consulta uma NF-e pela chave.