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

bash

curl "$BASE_URL/api/v1/admin/fiscal/queue?status=failed&per_page=50" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Fila devolvida

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
}

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

Status	Quando	Corpo
401	Sem token	`{"error":"missing authorization header"}`
403	Sem privilégio	`{"error":"insufficient privileges","privilege_required_any":["manage_nfe","manage_settings"]}`
403	Módulo desligado	`{"error":"module_disabled","module":"focusnfe"}`
500	Falha 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

bash

curl -X POST "$BASE_URL/api/v1/admin/fiscal/queue/0d6b7a54-3c1e-4f0a-9b8d-6e2f1a4c7b90/retry" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Item reenfileirado

json

{ "id": "0d6b7a54-3c1e-4f0a-9b8d-6e2f1a4c7b90", "status": "pending" }

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

Status	Quando	Corpo
422	Item 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

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" }'

Resposta

200Item reenfileirado

json

{ "id": "0d6b7a54-3c1e-4f0a-9b8d-6e2f1a4c7b90", "status": "pending" }

Erros

Status	Quando	Corpo
422	Item que não está `failed` ou `abandoned`, ou inexistente	`{"error":"cannot reemit item","detail":"fiscal: queue item not retryable"}`
422	`document_model` diferente de `55` e `65`	`{"error":"cannot reemit item","detail":"fiscal: modelo de documento inválido"}`
422	`establishment_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

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"] }'

Resposta

200Itens reenfileirados

json

{ "retried": 2 }

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

Status	Quando	Corpo
400	JSON inválido	`{"error":"invalid body","detail":"..."}`
400	`ids` vazio e sem `filter`	`{"error":"nenhum item selecionado"}`
422	Falha ao reenfileirar	`{"error":"cannot retry items","detail":"..."}`

Veja também

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.

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

bash

curl "$BASE_URL/api/v1/admin/fiscal/queue?status=failed&per_page=50" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Fila devolvida

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
}

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

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

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

Reenviar um item

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

bash

curl -X POST "$BASE_URL/api/v1/admin/fiscal/queue/0d6b7a54-3c1e-4f0a-9b8d-6e2f1a4c7b90/retry" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Item reenfileirado

json

{ "id": "0d6b7a54-3c1e-4f0a-9b8d-6e2f1a4c7b90", "status": "pending" }

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

Status	Quando	Corpo
422	Item 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

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

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" }'

Resposta

200Item reenfileirado

json

{ "id": "0d6b7a54-3c1e-4f0a-9b8d-6e2f1a4c7b90", "status": "pending" }

Erros

Status	Quando	Corpo
422	Item que não está `failed` ou `abandoned`, ou inexistente	`{"error":"cannot reemit item","detail":"fiscal: queue item not retryable"}`
422	`document_model` diferente de `55` e `65`	`{"error":"cannot reemit item","detail":"fiscal: modelo de documento inválido"}`
422	`establishment_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

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

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"] }'

Resposta

200Itens reenfileirados

json

{ "retried": 2 }

Campos da resposta

retriedinteger

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

Erros

Status	Quando	Corpo
400	JSON inválido	`{"error":"invalid body","detail":"..."}`
400	`ids` vazio e sem `filter`	`{"error":"nenhum item selecionado"}`
422	Falha ao reenfileirar	`{"error":"cannot retry items","detail":"..."}`