API de NF-e: o que costuma estar no pacote e o que está aqui
O termo API de NF-e cobre serviços muito diferentes. Alguns emitem notas, outros distribuem documentos recebidos, outros só geram PDF. Antes de integrar, vale separar as funções:
- Emissão, cancelamento e carta de correção: feitos por emissores com certificado digital. Não estão nesta API.
- Download das notas emitidas contra um CNPJ: exige o certificado da empresa. Não está nesta API.
- Geração de DANFE, DANFCE e DACTE a partir do XML: está nesta API.
- Consulta de NF-e pela chave de acesso, com PDF, XML e resumo: está nesta API.
Fluxo típico de integração
Num ERP que recebe notas de fornecedores, o fluxo costuma ser este: o XML chega por e-mail ou por outro sistema, o ERP guarda o arquivo, chama o endpoint de geração e anexa o PDF ao lançamento. O usuário vê o DANFE sem sair do ERP, e o XML original fica guardado como documento fiscal.
Num TMS, o fluxo é parecido com o CT-e: emitido o conhecimento, o sistema envia o XML e recebe o DACTE para imprimir junto com os DANFEs da carga. Para a rotina completa do transporte, veja DANFE e DACTE para transportadoras.
Quando o sistema só tem a chave da nota, o endpoint de consulta devolve o documento completo se ele estiver no acervo. Se não estiver, a consulta pública traz só o resumo, sem itens, e o sistema deve pedir o XML ao emitente para ter o DANFE completo.
Num escritório contábil, a API costuma entrar no momento em que os XML dos clientes chegam: o sistema do escritório gera o PDF de cada um e o anexa à pasta do cliente, pronto para a segunda via. A rotina do setor está em DANFE para contadores.
Cuidados técnicos na integração
Envie o XML exatamente como foi recebido, sem reformatar. XML com declaração DOCTYPE ou ENTITY é recusado por segurança, com código 422. Arquivos ausentes, vazios ou grandes demais retornam 400. Trate 401 como problema de configuração da chave, 402 como falta de créditos e 429 como sinal para esperar.
Valide a chave de acesso no seu código antes de consultar, conferindo os 44 dígitos e o dígito verificador pelo módulo 11. A regra está em chave de acesso NF-e: 44 dígitos. E guarde a chave de API apenas no servidor; ela nunca deve aparecer no navegador do usuário.
API ou uso pelo site
A API compensa quando a geração de PDF faz parte de um processo que se repete: muitas notas por dia, documentos que precisam aparecer dentro de outro sistema ou nenhuma pessoa disponível para clicar. Para uso esporádico, o site faz o mesmo trabalho sem integração: gerar DANFE pelo XML.
Para avaliar se vale a pena integrar e como apresentar isso dentro de um ERP, o artigo API DANFE para ERP traz a visão de negócio. A visão técnica, com exemplos de requisição e resposta, fica na documentação. E se a sua dúvida é sobre a diferença entre o arquivo e o PDF que a API devolve, leia diferença entre NF-e e DANFE.