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

Emitir NF-e

Emite a nota fiscal de um pedido, a partir do próprio pedido ou com os dados informados à mão.

Há duas formas. A simplificada (/issue) só precisa do id do pedido e monta tudo a partir dele. A manual (POST /nfe) recebe todos os dados e serve quando o pedido não carrega o necessário. As duas devolvem a nota como processando.

Emitir a partir do pedido

Se o pedido já tem nota, devolve a existente (200) em vez de criar outra. Caso contrário monta a emissão com os itens, o endereço e o documento do cliente do pedido e responde 201.

POST/api/v1/admin/nfe/issueAdmin

Emite a NF-e de um pedido

Corpo da requisição

order_iduuidobrigatório
Pedido a faturar.
vendor_iduuid
Emite só a nota do sub-pedido deste seller.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/admin/nfe/issue" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": "608a3291-6064-44a2-b352-5816d0471469"
  }'

Resposta

201Nota criada
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": "processando",
  "serie": "1",
  "created_at": "2026-10-11T14:00:00Z",
  "updated_at": "2026-10-11T14:00:00Z"
}
200Nota já existente
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
400order_id ausente.{"error":"order_id is required"}
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"}
404Pedido inexistente.{"error":"order not found"}
422Pedido não faturável: faturado_leg_not_invoiceable, customer_document_missing, order_has_no_items, fractional_quantity_not_supported; ou credencial recusada.{"error":"customer_document_missing","detail":"..."}
500Falha ao emitir (a mensagem do provedor vai em detail).{"error":"failed to emit NF-e","detail":"..."}

Emitir com dados manuais

POST/api/v1/admin/nfeAdmin

Emite uma NF-e com dados manuais

Corpo da requisição

order_iduuidobrigatório
Pedido.
vendor_iduuid
Seller, para nota de sub-pedido.
customer_namestringobrigatório
Nome do destinatário (máx. 60 caracteres na SEFAZ).
customer_cpfstring
CPF (11 dígitos). Envie CPF ou CNPJ.
customer_cnpjstring
CNPJ (14 caracteres, validado).
customer_emailstring
E-mail para envio da nota.
cepstring
CEP, 8 dígitos.
streetstring
Logradouro.
numberstring
Número.
complementstring
Complemento.
neighborhoodstring
Bairro.
citystring
Município.
statestring
UF.
total_amountintegerobrigatório
Total em centavos, positivo, com frete.
freight_amountinteger
Frete em centavos.
discount_amountinteger
Desconto em centavos.
icms_destinatariointeger
129
1 contribuinte, 2 isento, 9 não contribuinte. Padrão: 9 para CPF e 1 para CNPJ.
customer_inscricao_estadualstring
Inscrição estadual, obrigatória com icms_destinatario 1.
natureza_operacaostring
Natureza da operação; padrão da loja se vazio.
itemsarrayobrigatório

Pelo menos um item.

product_iduuid
Produto do catálogo (opcional).
product_namestringobrigatório
Descrição na nota (máx. 120).
ncmstring
NCM, 8 dígitos. Padrão 84714900: confira, NCM errado causa rejeição.
cfopstring
CFOP. Padrão 5102 (dentro do estado); use 6102 entre estados.
quantityintegerobrigatório
Quantidade inteira.
unit_priceintegerobrigatório
Preço unitário em centavos.
total_priceintegerobrigatório
Total da linha em centavos.
csosnstring
CSOSN do Simples Nacional. Padrão 400.
icms_cststring
CST de ICMS no Regime Normal. Padrão 00.
icms_rateinteger
Alíquota ICMS em pontos-base.
ipi_rateinteger
Alíquota IPI em pontos-base.
pis_rateinteger
Alíquota PIS em pontos-base.
cofins_rateinteger
Alíquota COFINS em pontos-base.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/admin/nfe" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": "608a3291-6064-44a2-b352-5816d0471469",
    "customer_name": "Maria Souza",
    "customer_cpf": "123.456.789-09",
    "customer_email": "maria.souza@example.com",
    "cep": "01310100",
    "street": "Avenida Paulista",
    "number": "1000",
    "neighborhood": "Bela Vista",
    "city": "São Paulo",
    "state": "SP",
    "total_amount": 10980,
    "freight_amount": 1000,
    "items": [
      {
        "product_name": "Camiseta Básica Preta M",
        "ncm": "61091000",
        "cfop": "5102",
        "quantity": 2,
        "unit_price": 4990,
        "total_price": 9980,
        "csosn": "102"
      }
    ]
  }'

Resposta

201Nota enviada à SEFAZ
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": "processando",
  "serie": "1",
  "created_at": "2026-10-11T14:00:00Z",
  "updated_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
400Campo obrigatório ausente (order_id, customer_name, CPF ou CNPJ), documento inválido, total_amount não positivo ou lista de itens vazia.{"error":"customer_cpf or customer_cnpj is required"}
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"}
422Credencial fiscal recusada pela FocusNFe.{"error":"fiscal provider rejected the credentials","detail":"..."}
423O mês contábil do pedido está fechado.{"error":"period_closed","competence":"2026-09"}
500Falha ao emitir (a mensagem do provedor vai em detail).{"error":"failed to emit NF-e","detail":"..."}
Os campos fiscais são sua responsabilidade

Nesta rota a plataforma não calcula impostos nem confere o NCM: um NCM ou CFOP errado gera rejeição da SEFAZ ou multa. Prefira /nfe/issue sempre que o pedido tiver dados completos.

Veja também

  • NF-e
Anterior
NF-e (nota fiscal)
Próxima
Consultar NF-e
Nesta página
  • Emitir a partir do pedido
  • Exemplo de requisição
  • Resposta
  • Erros
  • Emitir com dados manuais
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também