Processamento assíncrono

A autorização de um documento fiscal depende de sistemas externos — SEFAZ, Ambiente Nacional, prefeitura ou provedor municipal. O resultado definitivo raramente está disponível no mesmo instante em que sua aplicação envia a solicitação.

Por isso a emissão devolve 202 com um job_id, e o resultado é acompanhado depois.

O que sua aplicação deve fazer

1. enviar a emissão;
2. salvar o job_id (e a sua referencia_externa);
3. aguardar o webhook ou consultar o status;
4. só considerar a operação concluída ao atingir um estado final.

Consultando

GET /v1/nfe/consultar/{job_id}
GET /v1/nfce/consultar/{job_id}
GET /v1/nfse/consultar/{job_id}

Para muitos jobs de uma vez, existe consulta em lote — até 200 ids por chamada, resolvida em poucas queries, independente de N:

POST /v1/jobs/consultar-lote

{ "job_ids": ["6f8dc295-...", "8881bac5-..."] }

Evite polling agressivo

Consultar em laço não acelera o autorizador

Um GET a cada segundo não faz a SEFAZ responder mais rápido: só gasta a sua cota e a sua banda.

Recomendação:

• webhook como mecanismo principal;
• polling como recuperação, com intervalo crescente (por exemplo 5s, 15s, 30s, 60s);
• consulta em lote quando precisar reconciliar muitos jobs.

Estado final

Ver Status das emissões para saber quais estados encerram o ciclo e quais ainda pedem espera.