Baixar XMLs por período

O download de XMLs em lote é assíncrono: você solicita, recebe um protocolo, consulta esse protocolo até o arquivo ficar pronto e então baixa o ZIP por um link temporário. O arquivo também é enviado por e-mail.

Esse desenho existe porque montar o ZIP de um período grande leva minutos — uma requisição síncrona ficaria pendurada até estourar timeout.

Fluxo

Solicitar

curl -X POST $BASE/xml/solicitacao \
  -H "Authorization: Token $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "tipo": "NFe",
    "data-inicial": "2026-04-01",
    "data-final": "2026-04-30",
    "email": "[email protected]"
  }'

Resposta:

{
  "status": "001",
  "descricao": "Solicitação de XML registrada com sucesso.",
  "data": { "protocolo": "665547" }
}

Consultar o protocolo

Use intervalo mínimo de 2 segundos entre consultas.

curl $BASE/xml/solicitacao/665547 -H "Authorization: Token $TOKEN"

Enquanto processa:

{
  "status": "002",
  "descricao": "A solicitação de XML está sendo processada.",
  "data": { "protocolo": "665547", "situacao": "processando",
            "data-solicitacao": "2026-08-06T11:35:46" }
}

Baixar quando ficar pronto

{
  "status": "005",
  "descricao": "Arquivo de XML disponível para download.",
  "data": {
    "protocolo": "665547",
    "situacao": "disponivel",
    "url-download": "https://mysetemp.s3-sa-east-1.amazonaws.com/xml/...zip?...",
    "descricao": "Arquivo de XMLs das notas solicitados do período 01/04/2026 a 30/04/2026.",
    "expira-em": "2026-08-13",
    "data-processamento": "2026-08-06T11:36:03"
  }
}

Baixe direto da url-download — ela não exige o header de autenticação.

Campos da solicitação

Campo	Obrigatório	Descrição
`tipo`	Sim	`"NFe"` ou `"NFCe"`
`data-inicial`	Sim	`AAAA-MM-DD`. Não pode ser futura
`data-final`	Sim	`AAAA-MM-DD`. Não pode ser anterior à inicial
`email`	Não	Destino do aviso. Omitido, usa o e-mail cadastrado da empresa

Situações possíveis

`status`	`situacao`	Significado
`001`	—	Solicitação registrada. Guarde o `protocolo`
`050`	—	Já existia uma solicitação igual em andamento. O `protocolo` devolvido é o dela — não é erro
`002`	`processando`	Ainda na fila ou gerando. Consulte de novo
`005`	`disponivel`	Pronto. Use `url-download`
`006`	`sem-notas`	Terminou e não havia nota no período. Estado final — reconsultar não muda
`007`	`falha`	A geração falhou. Estado final — faça uma nova solicitação
`500`	—	Protocolo não existe (ou não pertence à sua empresa)

Detalhes que evitam dor de cabeça

O link expira em 7 dias. O campo expira-em traz a data. Depois disso a URL passa a responder erro — baixe e guarde o arquivo.

A URL só aceita GET. Uma requisição HEAD para “testar se o link está vivo” devolve 403: a assinatura do link é calculada sobre o método HTTP. Para verificar disponibilidade, use GET com Range: bytes=0-0.

Solicitação repetida devolve o mesmo protocolo. Se você repetir a mesma solicitação (mesmo tipo, mesmo período, mesmo e-mail) dentro de 10 minutos, a API devolve o protocolo da solicitação anterior com status 050, em vez de gerar outro arquivo.

O e-mail é obrigatório na prática. O arquivo é entregue por e-mail além do link. Se você omitir email e a sua empresa não tiver e-mail cadastrado válido, a solicitação é recusada na hora com mensagem explicando — melhor do que aceitar e nunca entregar.

Erros comuns

Mensagem (`data.erro`)	Causa
`Campo xml@tipo inválido. Valores aceitos: "NFe" ou "NFCe".`	Tipo diferente desses dois (NFSe não é suportada neste endpoint)
`Campo xml@data-inicial inválido. Use o formato AAAA-MM-DD.`	Formato fora do padrão
`O período solicitado excede o limite de 92 dias.`	Divida em solicitações menores
`Você já possui 3 solicitações de XML em processamento.`	Aguarde alguma concluir
`Informe o campo email: o e-mail cadastrado da empresa está ausente ou inválido.`	Envie `email` no payload