Revisado em .
Uma API para download de XML de NF-e precisa tratar acesso, distribuição e armazenamento. A escolha entre comunicação direta com a SEFAZ e um intermediário depende dos documentos necessários, das permissões e da capacidade de manter a integração.
SOAP da SEFAZ ou API REST intermediária?
O serviço NFeDistribuicaoDFe utiliza mensagens XML/SOAP. Uma API intermediária pode oferecer outra interface, como REST, mas mantém dependências das fontes fiscais. Converter a resposta em JSON não amplia a autorização para acessar documentos nem substitui a preservação do XML original.
- Acesso: configure o certificado digital compatível e identifique o interessado autorizado. Autenticação da conexão e assinatura de eventos são etapas distintas; siga o leiaute de cada serviço.
- Continuidade: registre o último NSU e coordene os consumidores do mesmo CNPJ. Guarde os retornos necessários para retomar consultas sem perder o controle da sequência.
- Manifestação: escolha o evento de acordo com os fatos. Não envie Confirmação da Operação apenas para liberar o download; Ciência da Emissão não equivale a confirmação.
- Persistência: preserve o XML recebido, identifique duplicidades e separe documento, evento e resumo antes de alimentar o ERP.
Como avaliar uma API fiscal
Peça documentação de autenticação, endpoints, paginação, limites, formatos, cobertura e tratamento de erros. Teste uma amostra autorizada com critérios de aceite: documentos esperados e recebidos, latência observada, retomada após falha e custo contratado. Este artigo não publica um contrato de API REST do FideFlow nem comprova disponibilidade de endpoints para todos os planos.
Conheça o Flow Fiscal
Confira os recursos e planos e valide os requisitos da sua integração antes de contratar. O acesso a NF-e, NFS-e e CT-e deve ser avaliado separadamente.
Ver recursos e planosPerguntas frequentes
Como tratar consumo indevido?
Interprete o código retornado. Ao receber 656, aguarde uma hora antes de repetir; novas tentativas antecipadas podem renovar o bloqueio. Não use esse intervalo como regra única para toda paginação. Coordene as consultas e siga a orientação vigente do Portal NF-e.
XML ou JSON: qual preservar?
Preserve o XML fiscal original e seus eventos. JSON pode facilitar o processamento, desde que o mapeamento mantenha a origem e a interpretação dos campos. A transformação não comprova validade fiscal ou completude.
A mesma integração cobre NFS-e e CT-e?
Não presuma essa cobertura. Cada modelo possui serviços, regras e permissões próprios. O NFeDistribuicaoDFe não é um endpoint único para os três documentos; confirme a cobertura oferecida pelo integrador.
Fontes e requisitos da integração
Consulte o Portal Nacional da NF-e sobre consumo indevido, a orientação da SEF/MG sobre manifestação e a documentação própria da NFS-e Nacional. Leia os esquemas e regras vigentes antes de implementar.