GuiasBaixar XML e PDF

Baixar XML e PDF

Toda nota autorizada tem um XML assinado, que é o documento fiscal, e um PDF para enviar ao cliente. Este guia mostra como baixar os dois, nota a nota ou em lote para o fechamento do mês.

O que é cada arquivo

  • XML
    Conteúdo
    A NFS-e no leiaute nacional, com a assinatura digital.
    Para que serve
    É o documento com valor fiscal. Guarde pelo prazo legal e envie à contabilidade.
  • PDF
    Conteúdo
    A representação visual da nota, com os mesmos dados do XML.
    Para que serve
    É o que o tomador do serviço costuma pedir. Pode ser anexado a e-mails e cobranças.

Os arquivos só existem depois da autorização. Uma nota em processando ou rejeitada responde 409 nos dois endpoints.

Baixar os arquivos de uma nota

Os dois endpoints devolvem o arquivo direto no corpo da resposta e usam a mesma chave de API das outras chamadas.

Requisição
# XML assinadocurl https://api.emissordenota.com/v1/nfse/nfse_3Jt9wPz7Qa/xml \  -H "Authorization: Bearer $EDN_KEY" \  -o nfse-000000127.xml# PDF da notacurl https://api.emissordenota.com/v1/nfse/nfse_3Jt9wPz7Qa/pdf \  -H "Authorization: Bearer $EDN_KEY" \  -o nfse-000000127.pdf
  • Content-Type
    XML
    application/xml
    PDF
    application/pdf
  • Content-Disposition
    XML
    attachment; filename="nfse-000000127.xml"
    PDF
    attachment; filename="nfse-000000127.pdf"

Não repasse xml_url e pdf_url ao seu cliente

Esses campos do objeto NFS-e apontam para os mesmos endpoints e exigem a chave de API. Baixe o arquivo no seu servidor e entregue pelo seu sistema.

Baixar assim que a nota for autorizada

Não consulte a nota em laço esperando a autorização. Assine o evento nfse.autorizada e baixe os arquivos quando ele chegar.

Node.js
// Confira a assinatura antes de usar o corpo. Veja o guia de Webhooks.app.post("/webhooks/emissor", async (req, res) => {  const { evento, dados } = req.body;  if (evento === "nfse.autorizada") {    const resposta = await fetch(dados.xml_url, {      headers: { Authorization: `Bearer ${process.env.EDN_KEY}` }    });    await salvarArquivo(`nfse-${dados.numero}.xml`, await resposta.text());  }  res.sendStatus(200);});

Baixar em lote

Para o fechamento do mês, liste as notas autorizadas da competência e baixe o XML de cada uma. A lista é paginada: repita a chamada com o cursor recebido em proximo_cursor até ele vir nulo.

Listando as notas de outubro
curl -G https://api.emissordenota.com/v1/nfse \  -H "Authorization: Bearer $EDN_KEY" \  -d empresa_id=emp_8Kq2mXv41c \  -d status=autorizada \  -d competencia=2026-10 \  -d limite=50

Cuide do limite de requisições

Um lote grande passa fácil de 120 requisições por minuto. Baixe em sequência, com poucas chamadas em paralelo, e espere o tempo de Retry-After quando receber 429.

Erros comuns

StatusCódigoO que significa

  • 404nfse_nao_encontrada
    O id não existe ou a nota é de outro ambiente.
  • 409nfse_nao_autorizada
    A nota ainda está em processando ou foi rejeitada. Não há arquivo para baixar.