VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Fiscal (NF-e e NFC-e)

Fila de emissão

Lista a fila de notas fiscais e reenvia itens que falharam, individualmente, com correção ou em lote.

Cada pedido que precisa de nota vira um item da fila. Aqui você acompanha o andamento, vê o motivo de cada falha e manda reemitir depois de corrigir o problema. Todas as rotas exigem o módulo focusnfe e o privilégio manage_nfe ou manage_settings.

Um pedido tem no máximo um item aberto (pending, processing ou submitted) por seller: tentar enfileirar de novo enquanto há um aberto não duplica nada. Quando o pedido é cancelado antes da autorização, o item aberto vira cancelled.

Listar a fila

Devolve os itens, os de NFC-e (65) primeiro e, dentro de cada modelo, os mais novos primeiro.

GET/api/v1/admin/fiscal/queueAdmin

Lista a fila de emissão fiscal

Parâmetros de consulta

statusstring
pendingprocessingsubmittedauthorizedfailedabandonedcancelled
Filtra pelo estado do item.
document_modelstring
5565
Filtra pelo modelo: 55 NF-e, 65 NFC-e.
pageintegerpadrão: 1
Página, a partir de 1.
per_pageintegerpadrão: 50
Itens por página, de 1 a 200. Fora disso volta para 50.

Exemplo de requisição

Resposta

200Fila devolvida

Campos da resposta

itemsarray
Itens da página. Pode vir como null quando vazio.
totalinteger
Total de itens que casam com os filtros.
pageinteger
Página devolvida.
per_pageinteger
Tamanho de página aplicado.
iduuid
Id do item da fila.
order_iduuid
Pedido a faturar.
vendor_iduuid
Seller do pedido (nota por seller). Ausente quando não se aplica.
establishment_iduuid
Estabelecimento emissor. Ausente quando o emissor ainda será resolvido.
document_modelstring
5565
Modelo do documento.
statusstring
pendingprocessingsubmittedauthorizedfailedabandonedcancelled
Estado do item.
trigger_sourcestring
automanualagent
Quem enfileirou: o gatilho automático, uma pessoa ou o assistente fiscal.
actor_iduuid
Usuário que acionou, quando foi manual. Ausente nos demais.
attemptsinteger
Tentativas de comunicação já feitas.
next_retry_atstring
Quando a próxima tentativa automática acontece, RFC 3339. Ausente fora de pending com espera.
last_errorstring
Último erro, em português, como veio do provedor ou da SEFAZ. Ausente quando não há.
nfe_record_iduuid
Registro da nota quando já foi emitida. Ausente antes disso.
created_atstring
Criação, RFC 3339.
updated_atstring
Última alteração, RFC 3339.

Erros

StatusQuandoCorpo
401Sem token{"error":"missing authorization header"}
403Sem privilégio{"error":"insufficient privileges","privilege_required_any":["manage_nfe","manage_settings"]}
403Módulo desligado{"error":"module_disabled","module":"focusnfe"}
500Falha de consulta{"error":"failed to list queue","detail":"..."}

Filtros com valor desconhecido não dão erro: a lista volta vazia.

Reenviar um item

Coloca de volta na fila (pending, para tentar já) um item failed ou abandoned, limpa o último erro e marca a origem como manual. Não altera nenhum dado do pedido ou do produto: se a causa era um NCM errado, corrija o produto antes.

POST/api/v1/admin/fiscal/queue/{id}/retryAdmin

Reenvia um item que falhou

Parâmetros de caminho

iduuidobrigatório
Id do item da fila.

Exemplo de requisição

Resposta

200Item reenfileirado

O status devolvido é o novo estado do item (pending), não o resultado da emissão. A nota é emitida em segundo plano: consulte a fila de novo depois de alguns segundos.

Erros

StatusQuandoCorpo
422Item que não está failed ou abandoned, ou que não existe{"error":"cannot retry item","detail":"fiscal: queue item not retryable"}

Reenviar corrigindo emissor ou modelo

Faz o mesmo que o reenvio simples, mas antes troca o estabelecimento emissor e/ou o modelo do documento. É o caminho para rejeições causadas por CNPJ, série, UF ou inscrição estadual do emissor errado, ou por usar NF-e onde cabia NFC-e (e o contrário). As tentativas voltam a zero, porque é uma emissão nova.

POST/api/v1/admin/fiscal/queue/{id}/reemitAdmin

Reenvia um item trocando emissor ou modelo

Parâmetros de caminho

iduuidobrigatório
Id do item da fila.

Corpo da requisição (opcional)

establishment_iduuid
Novo estabelecimento emissor. Vazio mantém o atual.
document_modelstring
5565
Novo modelo. Vazio mantém o atual.

Exemplo de requisição

Resposta

200Item reenfileirado

Erros

StatusQuandoCorpo
422Item que não está failed ou abandoned, ou inexistente{"error":"cannot reemit item","detail":"fiscal: queue item not retryable"}
422document_model diferente de 55 e 65{"error":"cannot reemit item","detail":"fiscal: modelo de documento inválido"}
422establishment_id que não é UUID{"error":"cannot reemit item","detail":"..."}

Um corpo vazio ou ausente é válido e se comporta como o reenvio simples. O corpo com JSON inválido é ignorado em silêncio, com o mesmo efeito.

Reenviar vários itens

Reenfileira de uma vez os itens failed e abandoned escolhidos. Itens em outro estado são pulados sem erro; a resposta diz quantos foram de fato reenfileirados.

POST/api/v1/admin/fiscal/queue/bulk-retryAdmin

Reenvia vários itens da fila

Corpo da requisição

idsarrayobrigatório
Ids (UUID) dos itens a reenviar. Obrigatório, a não ser que você use filter.
filterobject

Alternativa a ids: reenvia por critério, sempre sobre itens failed ou abandoned. Exige simulação e confirmação (veja abaixo). Chaves aceitas, todas opcionais: status, vendor_id, document_model, trigger_source, attempts_min (inteiro), error_contains (trecho do último erro), created_after e created_before (AAAA-MM-DD).

simulateboolean
true: só calcula o recorte e devolve total, sample e um confirm_token, sem reenviar nada.
confirm_tokenstring
Token da simulação, obrigatório para executar um recorte por filter.

Exemplo de requisição

Resposta

200Itens reenfileirados

Campos da resposta

retriedinteger
Quantos itens saíram de failed ou abandoned para pending.

Com filter, a resposta segue o protocolo de lote por critério da plataforma. A simulação devolve total (quantos itens o recorte alcança), sample (até 10 exemplos), confirm_token e expires_at. A execução, com o mesmo corpo mais o confirm_token, devolve action, total_requested, status, affected e failed (200), ou 202 com async: true e o andamento do trabalho quando o recorte é grande. Sem simulação prévia a execução é recusada.

Erros

StatusQuandoCorpo
400JSON inválido{"error":"invalid body","detail":"..."}
400ids vazio e sem filter{"error":"nenhum item selecionado"}
422Falha ao reenfileirar{"error":"cannot retry items","detail":"..."}
Corrija a causa em lote antes de reenviar em lote

Use error_contains para achar todos os itens com o mesmo erro (por exemplo NCM), corrija os produtos com Validação prévia e só então reenvie o grupo. Reenviar sem corrigir apenas gasta tentativas e polui a fila.

Veja também

  • Configuração de emissão
  • Validação prévia
  • Estabelecimentos
Anterior
Fiscal: notas fiscais eletrônicas
Próxima
Configuração de emissão
Nesta página
  • Listar a fila
  • Exemplo de requisição
  • Resposta
  • Erros
  • Reenviar um item
  • Exemplo de requisição
  • Resposta
  • Erros
  • Reenviar corrigindo emissor ou modelo
  • Exemplo de requisição
  • Resposta
  • Erros
  • Reenviar vários itens
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também
bash
curl "$BASE_URL/api/v1/admin/fiscal/queue?status=failed&per_page=50" \
  -H "Authorization: Bearer $TOKEN"
bash
curl -X POST "$BASE_URL/api/v1/admin/fiscal/queue/0d6b7a54-3c1e-4f0a-9b8d-6e2f1a4c7b90/retry" \
  -H "Authorization: Bearer $TOKEN"
bash
curl -X POST "$BASE_URL/api/v1/admin/fiscal/queue/0d6b7a54-3c1e-4f0a-9b8d-6e2f1a4c7b90/reemit" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "establishment_id": "c04d4d27-b16d-4dcb-836a-7c9eb0a40c3b", "document_model": "55" }'
bash
curl -X POST "$BASE_URL/api/v1/admin/fiscal/queue/bulk-retry" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "ids": ["0d6b7a54-3c1e-4f0a-9b8d-6e2f1a4c7b90", "7a1c9e22-5d3b-4c68-8f10-2b9d4e6a3c11"] }'
json
{
  "items": [
    {
      "id": "0d6b7a54-3c1e-4f0a-9b8d-6e2f1a4c7b90",
      "order_id": "615b4147-6cb2-4057-9e25-ee82281b9d68",
      "vendor_id": "ec5e10b3-8cb1-43e9-9aa8-964b64eda8de",
      "establishment_id": "c04d4d27-b16d-4dcb-836a-7c9eb0a40c3b",
      "document_model": "55",
      "status": "failed",
      "trigger_source": "auto",
      "attempts": 1,
      "last_error": "Rejeição 778: NCM inválido",
      "created_at": "2026-10-10T14:02:11Z",
      "updated_at": "2026-10-10T14:02:19Z"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 50
}
json
{ "id": "0d6b7a54-3c1e-4f0a-9b8d-6e2f1a4c7b90", "status": "pending" }
json
{ "id": "0d6b7a54-3c1e-4f0a-9b8d-6e2f1a4c7b90", "status": "pending" }
json
{ "retried": 2 }