Consultar NF-e
Lista as notas, consulta uma, atualiza o status na FocusNFe e informa a situação do certificado digital.
Como a emissão é assíncrona, você acompanha a nota por estas rotas. Em uso normal, o webhook da FocusNFe atualiza o status sozinho; check-status serve para forçar a consulta quando o webhook atrasou.
Listar notas
/api/v1/admin/nfeAdminLista as notas
Parâmetros de consulta
pageintegerpadrão: 1Página.
per_pageintegerpadrão: 20Itens por página, de 1 a 100; fora disso vale 20.
statusstringprocessandoautorizadoerrodenegadocanceladoFiltra por status.
vendor_iduuidFiltra por seller.
order_iduuidFiltra por pedido.
searchstringBusca em pedido, referência, número e chave.
date_fromstringCriada a partir de
YYYY-MM-DD.date_tostringCriada até
YYYY-MM-DD.Exemplo de requisição
Resposta
200Notas
Campos da resposta
recordsarrayNotas. A lista não traz
items.totalintegerTotal que casa com o filtro.
pageintegerPágina.
per_pageintegerTamanho da página.
total_pagesintegerTotal de páginas.
iduuidId interno da nota.
order_iduuidPedido.
vendor_iduuidSeller da nota; ausente na nota do marketplace.
refstringReferência única enviada à FocusNFe.
statusstringprocessandoautorizadoerrodenegadocanceladoprocessando, autorizado, erro, denegado ou cancelado.chave_nfestringChave de acesso de 44 dígitos. Só após autorizar.
numerostringNúmero da nota na série.
seriestringSérie.
xml_urlstringCaminho do XML na FocusNFe. Só após autorizar.
danfe_urlstringCaminho do DANFE. Só após autorizar.
error_msgstringCódigos de rejeição da SEFAZ concatenados. Só em
erro.error_messagestringMotivo legível da rejeição. Só em
erro.cancel_reasonstringJustificativa do cancelamento.
canceled_atstringQuando foi cancelada (RFC 3339).
issued_atstringQuando foi autorizada (RFC 3339).
created_atstringCriação.
updated_atstringÚltima atualização (webhook ou consulta).
Erros
| Status | Quando | Corpo de exemplo |
|---|---|---|
| 401 | Sem token ou token inválido. | {"error":"missing authorization header"} |
| 403 | O usuário não tem manage_nfe nem manage_settings. | {"error":"insufficient privileges","privilege_required_any":["manage_nfe","manage_settings"]} |
| 403 | O módulo focusnfe está desligado na loja. | {"error":"module_disabled","module":"focusnfe"} |
Consultar uma nota
/api/v1/admin/nfe/{id}AdminConsulta uma nota
Parâmetros de caminho
iduuidobrigatórioId interno da nota (não a chave de acesso).
Exemplo de requisição
Resposta
200Nota com itens
Campos da resposta
iduuidId interno da nota.
order_iduuidPedido.
vendor_iduuidSeller da nota; ausente na nota do marketplace.
refstringReferência única enviada à FocusNFe.
statusstringprocessandoautorizadoerrodenegadocanceladoprocessando, autorizado, erro, denegado ou cancelado.chave_nfestringChave de acesso de 44 dígitos. Só após autorizar.
numerostringNúmero da nota na série.
seriestringSérie.
xml_urlstringCaminho do XML na FocusNFe. Só após autorizar.
danfe_urlstringCaminho do DANFE. Só após autorizar.
error_msgstringCódigos de rejeição da SEFAZ concatenados. Só em
erro.error_messagestringMotivo legível da rejeição. Só em
erro.cancel_reasonstringJustificativa do cancelamento.
canceled_atstringQuando foi cancelada (RFC 3339).
issued_atstringQuando foi autorizada (RFC 3339).
created_atstringCriação.
updated_atstringÚltima atualização (webhook ou consulta).
itemsarrayItens com a tabela de impostos (
ncm_code, cfop_code, quantity, unit_value, total_value, icms_*, ipi_*, pis_*, cofins_*). Valores em centavos, alíquotas em pontos-base. Só no detalhe (GET por id).Erros
| Status | Quando | Corpo de exemplo |
|---|---|---|
| 401 | Sem token ou token inválido. | {"error":"missing authorization header"} |
| 403 | O usuário não tem manage_nfe nem manage_settings. | {"error":"insufficient privileges","privilege_required_any":["manage_nfe","manage_settings"]} |
| 403 | O módulo focusnfe está desligado na loja. | {"error":"module_disabled","module":"focusnfe"} |
| 404 | Nota inexistente. | {"error":"NF-e not found"} |
Atualizar o status
Pergunta o estado atual à FocusNFe, atualiza o registro e o devolve.
/api/v1/admin/nfe/{id}/check-statusAdminConsulta o status na FocusNFe
Parâmetros de caminho
iduuidobrigatórioId interno da nota.
Exemplo de requisição
Resposta
200Nota atualizada
Campos da resposta
iduuidId interno da nota.
order_iduuidPedido.
vendor_iduuidSeller da nota; ausente na nota do marketplace.
refstringReferência única enviada à FocusNFe.
statusstringprocessandoautorizadoerrodenegadocanceladoprocessando, autorizado, erro, denegado ou cancelado.chave_nfestringChave de acesso de 44 dígitos. Só após autorizar.
numerostringNúmero da nota na série.
seriestringSérie.
xml_urlstringCaminho do XML na FocusNFe. Só após autorizar.
danfe_urlstringCaminho do DANFE. Só após autorizar.
error_msgstringCódigos de rejeição da SEFAZ concatenados. Só em
erro.error_messagestringMotivo legível da rejeição. Só em
erro.cancel_reasonstringJustificativa do cancelamento.
canceled_atstringQuando foi cancelada (RFC 3339).
issued_atstringQuando foi autorizada (RFC 3339).
created_atstringCriação.
updated_atstringÚltima atualização (webhook ou consulta).
itemsarrayItens com a tabela de impostos (
ncm_code, cfop_code, quantity, unit_value, total_value, icms_*, ipi_*, pis_*, cofins_*). Valores em centavos, alíquotas em pontos-base. Só no detalhe (GET por id).Erros
| Status | Quando | Corpo de exemplo |
|---|---|---|
| 401 | Sem token ou token inválido. | {"error":"missing authorization header"} |
| 403 | O usuário não tem manage_nfe nem manage_settings. | {"error":"insufficient privileges","privilege_required_any":["manage_nfe","manage_settings"]} |
| 403 | O módulo focusnfe está desligado na loja. | {"error":"module_disabled","module":"focusnfe"} |
| 404 | Nota inexistente. | {"error":"NF-e not found"} |
| 500 | Falha ao consultar o provedor. | {"error":"failed to check NF-e status","detail":"..."} |
Ver o certificado digital
Informa se o certificado A1 foi enviado à FocusNFe. Nunca devolve erro: falta de configuração ou indisponibilidade viram um valor em status.
/api/v1/admin/nfe/certificate-statusAdminSituação do certificado digital
Exemplo de requisição
Resposta
200Certificado enviado
Campos da resposta
statusstringnot_configurednot_sentsentunknownnot_configured (sem token ou CNPJ), not_sent (empresa sem certificado), sent ou unknown (provedor inacessível).valid_untilstringValidade do certificado, só com
sent.Erros
| Status | Quando | Corpo de exemplo |
|---|---|---|
| 401 | Sem token ou token inválido. | {"error":"missing authorization header"} |
| 403 | O usuário não tem manage_nfe nem manage_settings. | {"error":"insufficient privileges","privilege_required_any":["manage_nfe","manage_settings"]} |
| 403 | O módulo focusnfe está desligado na loja. | {"error":"module_disabled","module":"focusnfe"} |