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

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

GET/api/v1/admin/nfeAdmin

Lista as notas

Parâmetros de consulta

pageintegerpadrão: 1
Página.
per_pageintegerpadrão: 20
Itens por página, de 1 a 100; fora disso vale 20.
statusstring
processandoautorizadoerrodenegadocancelado
Filtra por status.
vendor_iduuid
Filtra por seller.
order_iduuid
Filtra por pedido.
searchstring
Busca em pedido, referência, número e chave.
date_fromstring
Criada a partir de YYYY-MM-DD.
date_tostring
Criada até YYYY-MM-DD.

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/admin/nfe?status=autorizado&page=1&per_page=20" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Notas
json
{
  "records": [
    {
      "id": "b7a76302-e926-4988-a015-789e8f225c60",
      "order_id": "608a3291-6064-44a2-b352-5816d0471469",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "ref": "VENDDOR_608A3291",
      "status": "autorizado",
      "serie": "1",
      "created_at": "2026-10-11T14:00:00Z",
      "updated_at": "2026-10-11T14:00:00Z",
      "chave_nfe": "35261012345678000199550010000001241234567891",
      "numero": "124",
      "xml_url": "/files/nfe/124.xml",
      "danfe_url": "/files/nfe/124.pdf",
      "issued_at": "2026-10-11T14:00:20Z",
      "items": [
        {
          "id": "1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
          "nfe_id": "b7a76302-e926-4988-a015-789e8f225c60",
          "description": "Camiseta Básica Preta M",
          "ncm_code": "61091000",
          "cfop_code": "5102",
          "quantity": 2,
          "unit_value": 4990,
          "total_value": 9980,
          "icms_base": 9980,
          "icms_rate": 1800,
          "icms_value": 1796,
          "icms_cst": "00",
          "icms_csosn": "",
          "ipi_rate": 0,
          "ipi_value": 0,
          "ipi_cst": "",
          "pis_rate": 165,
          "pis_value": 165,
          "pis_cst": "01",
          "cofins_rate": 760,
          "cofins_value": 758,
          "cofins_cst": "01",
          "created_at": "2026-10-11T14:00:00Z"
        }
      ]
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20,
  "total_pages": 1
}

Campos da resposta

recordsarray
Notas. A lista não traz items.
totalinteger
Total que casa com o filtro.
pageinteger
Página.
per_pageinteger
Tamanho da página.
total_pagesinteger
Total de páginas.
iduuid
Id interno da nota.
order_iduuid
Pedido.
vendor_iduuid
Seller da nota; ausente na nota do marketplace.
refstring
Referência única enviada à FocusNFe.
statusstring
processandoautorizadoerrodenegadocancelado
processando, autorizado, erro, denegado ou cancelado.
chave_nfestring
Chave de acesso de 44 dígitos. Só após autorizar.
numerostring
Número da nota na série.
seriestring
Série.
xml_urlstring
Caminho do XML na FocusNFe. Só após autorizar.
danfe_urlstring
Caminho do DANFE. Só após autorizar.
error_msgstring
Códigos de rejeição da SEFAZ concatenados. Só em erro.
error_messagestring
Motivo legível da rejeição. Só em erro.
cancel_reasonstring
Justificativa do cancelamento.
canceled_atstring
Quando foi cancelada (RFC 3339).
issued_atstring
Quando foi autorizada (RFC 3339).
created_atstring
Criação.
updated_atstring
Última atualização (webhook ou consulta).

Erros

StatusQuandoCorpo de exemplo
401Sem token ou token inválido.{"error":"missing authorization header"}
403O usuário não tem manage_nfe nem manage_settings.{"error":"insufficient privileges","privilege_required_any":["manage_nfe","manage_settings"]}
403O módulo focusnfe está desligado na loja.{"error":"module_disabled","module":"focusnfe"}

Consultar uma nota

GET/api/v1/admin/nfe/{id}Admin

Consulta uma nota

Parâmetros de caminho

iduuidobrigatório
Id interno da nota (não a chave de acesso).

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/admin/nfe/b7a76302-e926-4988-a015-789e8f225c60" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Nota com itens
json
{
  "id": "b7a76302-e926-4988-a015-789e8f225c60",
  "order_id": "608a3291-6064-44a2-b352-5816d0471469",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "ref": "VENDDOR_608A3291",
  "status": "autorizado",
  "serie": "1",
  "created_at": "2026-10-11T14:00:00Z",
  "updated_at": "2026-10-11T14:00:00Z",
  "chave_nfe": "35261012345678000199550010000001241234567891",
  "numero": "124",
  "xml_url": "/files/nfe/124.xml",
  "danfe_url": "/files/nfe/124.pdf",
  "issued_at": "2026-10-11T14:00:20Z",
  "items": [
    {
      "id": "1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
      "nfe_id": "b7a76302-e926-4988-a015-789e8f225c60",
      "description": "Camiseta Básica Preta M",
      "ncm_code": "61091000",
      "cfop_code": "5102",
      "quantity": 2,
      "unit_value": 4990,
      "total_value": 9980,
      "icms_base": 9980,
      "icms_rate": 1800,
      "icms_value": 1796,
      "icms_cst": "00",
      "icms_csosn": "",
      "ipi_rate": 0,
      "ipi_value": 0,
      "ipi_cst": "",
      "pis_rate": 165,
      "pis_value": 165,
      "pis_cst": "01",
      "cofins_rate": 760,
      "cofins_value": 758,
      "cofins_cst": "01",
      "created_at": "2026-10-11T14:00:00Z"
    }
  ]
}

Campos da resposta

iduuid
Id interno da nota.
order_iduuid
Pedido.
vendor_iduuid
Seller da nota; ausente na nota do marketplace.
refstring
Referência única enviada à FocusNFe.
statusstring
processandoautorizadoerrodenegadocancelado
processando, autorizado, erro, denegado ou cancelado.
chave_nfestring
Chave de acesso de 44 dígitos. Só após autorizar.
numerostring
Número da nota na série.
seriestring
Série.
xml_urlstring
Caminho do XML na FocusNFe. Só após autorizar.
danfe_urlstring
Caminho do DANFE. Só após autorizar.
error_msgstring
Códigos de rejeição da SEFAZ concatenados. Só em erro.
error_messagestring
Motivo legível da rejeição. Só em erro.
cancel_reasonstring
Justificativa do cancelamento.
canceled_atstring
Quando foi cancelada (RFC 3339).
issued_atstring
Quando foi autorizada (RFC 3339).
created_atstring
Criação.
updated_atstring
Última atualização (webhook ou consulta).
itemsarray
Itens 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

StatusQuandoCorpo de exemplo
401Sem token ou token inválido.{"error":"missing authorization header"}
403O usuário não tem manage_nfe nem manage_settings.{"error":"insufficient privileges","privilege_required_any":["manage_nfe","manage_settings"]}
403O módulo focusnfe está desligado na loja.{"error":"module_disabled","module":"focusnfe"}
404Nota inexistente.{"error":"NF-e not found"}

Atualizar o status

Pergunta o estado atual à FocusNFe, atualiza o registro e o devolve.

POST/api/v1/admin/nfe/{id}/check-statusAdmin

Consulta o status na FocusNFe

Parâmetros de caminho

iduuidobrigatório
Id interno da nota.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/admin/nfe/b7a76302-e926-4988-a015-789e8f225c60/check-status" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Nota atualizada
json
{
  "id": "b7a76302-e926-4988-a015-789e8f225c60",
  "order_id": "608a3291-6064-44a2-b352-5816d0471469",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "ref": "VENDDOR_608A3291",
  "status": "autorizado",
  "serie": "1",
  "created_at": "2026-10-11T14:00:00Z",
  "updated_at": "2026-10-11T14:00:00Z",
  "chave_nfe": "35261012345678000199550010000001241234567891",
  "numero": "124",
  "xml_url": "/files/nfe/124.xml",
  "danfe_url": "/files/nfe/124.pdf",
  "issued_at": "2026-10-11T14:00:20Z",
  "items": [
    {
      "id": "1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
      "nfe_id": "b7a76302-e926-4988-a015-789e8f225c60",
      "description": "Camiseta Básica Preta M",
      "ncm_code": "61091000",
      "cfop_code": "5102",
      "quantity": 2,
      "unit_value": 4990,
      "total_value": 9980,
      "icms_base": 9980,
      "icms_rate": 1800,
      "icms_value": 1796,
      "icms_cst": "00",
      "icms_csosn": "",
      "ipi_rate": 0,
      "ipi_value": 0,
      "ipi_cst": "",
      "pis_rate": 165,
      "pis_value": 165,
      "pis_cst": "01",
      "cofins_rate": 760,
      "cofins_value": 758,
      "cofins_cst": "01",
      "created_at": "2026-10-11T14:00:00Z"
    }
  ]
}

Campos da resposta

iduuid
Id interno da nota.
order_iduuid
Pedido.
vendor_iduuid
Seller da nota; ausente na nota do marketplace.
refstring
Referência única enviada à FocusNFe.
statusstring
processandoautorizadoerrodenegadocancelado
processando, autorizado, erro, denegado ou cancelado.
chave_nfestring
Chave de acesso de 44 dígitos. Só após autorizar.
numerostring
Número da nota na série.
seriestring
Série.
xml_urlstring
Caminho do XML na FocusNFe. Só após autorizar.
danfe_urlstring
Caminho do DANFE. Só após autorizar.
error_msgstring
Códigos de rejeição da SEFAZ concatenados. Só em erro.
error_messagestring
Motivo legível da rejeição. Só em erro.
cancel_reasonstring
Justificativa do cancelamento.
canceled_atstring
Quando foi cancelada (RFC 3339).
issued_atstring
Quando foi autorizada (RFC 3339).
created_atstring
Criação.
updated_atstring
Última atualização (webhook ou consulta).
itemsarray
Itens 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

StatusQuandoCorpo de exemplo
401Sem token ou token inválido.{"error":"missing authorization header"}
403O usuário não tem manage_nfe nem manage_settings.{"error":"insufficient privileges","privilege_required_any":["manage_nfe","manage_settings"]}
403O módulo focusnfe está desligado na loja.{"error":"module_disabled","module":"focusnfe"}
404Nota inexistente.{"error":"NF-e not found"}
500Falha 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.

GET/api/v1/admin/nfe/certificate-statusAdmin

Situação do certificado digital

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/admin/nfe/certificate-status" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Certificado enviado
json
{
  "status": "sent",
  "valid_until": "2027-03-15"
}

Campos da resposta

statusstring
not_configurednot_sentsentunknown
not_configured (sem token ou CNPJ), not_sent (empresa sem certificado), sent ou unknown (provedor inacessível).
valid_untilstring
Validade do certificado, só com sent.

Erros

StatusQuandoCorpo de exemplo
401Sem token ou token inválido.{"error":"missing authorization header"}
403O usuário não tem manage_nfe nem manage_settings.{"error":"insufficient privileges","privilege_required_any":["manage_nfe","manage_settings"]}
403O módulo focusnfe está desligado na loja.{"error":"module_disabled","module":"focusnfe"}

Veja também

  • NF-e
Anterior
Emitir NF-e
Próxima
Arquivos da NF-e (XML e DANFE)
Nesta página
  • Listar notas
  • Exemplo de requisição
  • Resposta
  • Erros
  • Consultar uma nota
  • Exemplo de requisição
  • Resposta
  • Erros
  • Atualizar o status
  • Exemplo de requisição
  • Resposta
  • Erros
  • Ver o certificado digital
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também