VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Guia rápido/Pedidos

Fatura e NF-e

Gera a fatura do pedido em JSON, HTML ou PDF, envia por e-mail, exporta várias de uma vez e consulta a NF-e emitida.

Há dois documentos diferentes que as pessoas chamam de "nota":

  • Fatura (invoice): um resumo do pedido para o cliente ou para conferência (itens, valores, endereços, pagamento). A plataforma gera na hora, a partir do pedido. Não tem valor fiscal.
  • NF-e: a nota fiscal eletrônica, emitida junto à Sefaz por um emissor fiscal (módulo de nota fiscal da loja ou o ERP do seller). Esta API só consulta a NF-e já emitida.

Esta página cobre a fatura (cinco formas de obtê-la) e a consulta da NF-e.

GET/api/v1/admin/orders/{id}/invoiceAdmin

Dados da fatura (JSON ou HTML)

Devolve a fatura do pedido em JSON (padrão) ou em HTML, usando o modelo de fatura que o lojista salvou em Documentos. Para HTML envie ?format=html ou o cabeçalho Accept: text/html. Exige view_orders ou manage_orders.

Path parameters

iduuidobrigatório
Id do pedido.

Query parameters

formatstringpadrão: json
jsonhtml
html devolve o HTML do modelo de fatura da loja (Content-Type: text/html).
langstring
(HTML) Idioma do modelo, por exemplo pt-BR ou en.
template_iduuid
(HTML) Usa um modelo específico, que precisa ser do tipo fatura. Omitido, usa o modelo padrão da loja.
GET/api/v1/admin/orders/{id}/invoice.pdfAdmin

Invoice as PDF

Gera o PDF da fatura (application/pdf, Content-Disposition: attachment; filename="fatura-<número>.pdf"). Exige view_orders ou manage_orders.

Path parameters

iduuidobrigatório
Id do pedido.
POST/api/v1/admin/orders/{id}/invoice/sendAdmin

E-mail the invoice PDF

Gera o PDF da fatura e o envia em anexo para o e-mail informado (o texto vem do modelo de e-mail export_order, editável em Admin, E-mails). Cada envio, com sucesso ou falha, fica no log de atividades. Exige manage_orders.

Path parameters

iduuidobrigatório
Id do pedido.

Corpo da requisição

emailstringobrigatório
Destinatário. Precisa ser um endereço válido (Nome <a@b.com> também é aceito; o envio usa só o endereço).
POST/api/v1/admin/orders/bulk-invoice.pdfAdmin

Um PDF com as notas fiscais de vários pedidos

Gera um único PDF com uma página por pedido, para impressão em lote. Máximo de 100 pedidos. Pedidos que não existem são omitidos; se nenhum for encontrado, responde 404. Exige manage_orders. O nome do arquivo é faturas-<N>-pedidos.pdf. Para os dados em JSON, em vez do PDF, use a ação export_invoices de Ações em lote.

Corpo da requisição

order_idsarrayobrigatório
Ids (UUID) dos pedidos. De 1 a 100.
GET/api/v1/admin/orders/{orderId}/nfeAdmin

NF-e emitida para um pedido

Devolve o registro da NF-e mais recente do pedido, com a chave de acesso, o número, os links do XML e do DANFE e os itens com a tributação. Responde 404 enquanto nenhuma NF-e foi emitida para o pedido. Exige view_orders ou manage_orders.

Path parameters

orderIduuidobrigatório
Id do pedido.

Exemplo de requisição

bash
# Fatura em JSON
curl "$BASE_URL/api/v1/admin/orders/$ORDER_ID/invoice" -H "Authorization: Bearer $TOKEN"

# Fatura em PDF
curl -o fatura.pdf "$BASE_URL/api/v1/admin/orders/$ORDER_ID/invoice.pdf" \
  -H "Authorization: Bearer $TOKEN"

# Enviar por e-mail
curl -X POST "$BASE_URL/api/v1/admin/orders/$ORDER_ID/invoice/send" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"email":"maria.souza@example.com"}'

# PDF único com várias faturas
curl -X POST "$BASE_URL/api/v1/admin/orders/bulk-invoice.pdf" -o faturas.pdf \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"order_ids":["0932405c-a8c1-49b3-a7db-61aab4c4d666","2b4bd680-b717-4295-a2be-8b5c6771a4d0"]}'

# NF-e do pedido
curl "$BASE_URL/api/v1/admin/orders/$ORDER_ID/nfe" -H "Authorization: Bearer $TOKEN"

Resposta

200Fatura em JSON
json
{
  "order": {
    "id": "fdbcc184-7cdc-4cf9-aaf7-5a1f7b6370e2",
    "order_number": "PEDIDO-20261011-0003",
    "status": "pending",
    "created_at": "2026-10-11T20:18:47.027421Z",
    "currency": "BRL"
  },
  "customer": {
    "name": "Maria Souza",
    "email": "maria.souza@example.com",
    "cpf": "12345678909",
    "phone": "11999990000",
    "person_type": "F"
  },
  "vendor": {
    "company_name": "Loja Seller Teste",
    "cnpj": "",
    "email": "contato@lojaseller.example.com",
    "phone": "+5511999998888",
    "address": "Rua dos Testes, 100",
    "city": "Volta Redonda",
    "state": "RJ"
  },
  "items": [
    {
      "product_name": "Notebook Slim Rosa",
      "product_sku": "SD-002373",
      "options": {},
      "quantity": 1,
      "unit_price": 11500,
      "discount": 0,
      "tax": 0,
      "total": 11500
    }
  ],
  "addresses": {
    "billing": {
      "name": "Maria Souza",
      "address_line1": "Avenida Paulista, 1000",
      "district": "Bela Vista",
      "city": "São Paulo",
      "state": "SP",
      "postal_code": "01310-100",
      "country": "BR",
      "phone": "11999990000",
      "cpf": "12345678909"
    },
    "shipping": {
      "name": "Maria Souza",
      "address_line1": "Avenida Paulista, 1000",
      "district": "Bela Vista",
      "city": "São Paulo",
      "state": "SP",
      "postal_code": "01310-100",
      "country": "BR"
    }
  },
  "payment": { "method": "pagamento-na-entrega", "status": "pending" },
  "tax": { "total_tax": 0 },
  "totals": { "subtotal": 11500, "shipping_total": 1000, "tax_total": 0, "discount_total": 0, "total": 12500 },
  "generated_at": "2026-10-11T20:30:45.642626Z"
}
200Fatura enviada por e-mail
json
{
  "sent": true,
  "to": "maria.souza@example.com",
  "recipients": ["maria.souza@example.com"],
  "order_id": "fdbcc184-7cdc-4cf9-aaf7-5a1f7b6370e2",
  "order_number": "PEDIDO-20261011-0003",
  "filename": "fatura-PEDIDO-20261011-0003.pdf"
}
200NF-e do pedido
json
{
  "id": "5b0b8a52-3e0c-4d61-8c34-7a9d1f0e2c18",
  "order_id": "fdbcc184-7cdc-4cf9-aaf7-5a1f7b6370e2",
  "ref": "VENDDOR_5b0b8a52",
  "status": "autorizado",
  "chave_nfe": "35261011222333000181550010000001231000001234",
  "numero": "123",
  "serie": "1",
  "xml_url": "https://emissor.example.com/nfe/35261011222333000181550010000001231000001234.xml",
  "danfe_url": "https://emissor.example.com/danfe/35261011222333000181550010000001231000001234.pdf",
  "issued_at": "2026-10-11T21:05:00Z",
  "created_at": "2026-10-11T21:04:30Z",
  "updated_at": "2026-10-11T21:05:00Z",
  "items": [
    {
      "id": "0c3a6f6e-1f0b-4c4a-8f6a-0f9f6f2d7a11",
      "description": "Notebook Slim Rosa",
      "ncm_code": "84713012",
      "cfop_code": "5102",
      "quantity": 1,
      "unit_value": 11500,
      "total_value": 11500,
      "icms_base": 11500,
      "icms_rate": 1800,
      "icms_value": 2070,
      "icms_cst": "00"
    }
  ]
}

Campos da fatura

orderobject
Cabeçalho: id, order_number, status (código longo), created_at, currency.
customerobject
Comprador: name, email, cpf ou cnpj (só dígitos), phone, person_type (F pessoa física, J jurídica) e, para pessoa jurídica, legal_name e trade_name.
vendorobject
Seller que vende: company_name, cnpj, state_reg, email, phone, address, city, state. Ausente em pedido da própria loja.
itemsarray
Linhas: product_name, product_sku, variation_label, options, quantity, unit_price, discount, tax, total (valores em centavos).
addressesobject
billing e shipping, cada um com name, address_line1, address_line2, district, complement, city, state, postal_code, country, phone, cpf.
paymentobject
method, status, reference (identificador no gateway) e details.
taxobject
total_tax em centavos e details (detalhamento por imposto, quando existe).
totalsobject
subtotal, shipping_total, tax_total, discount_total, total, todos em centavos.
generated_atstring
Quando a fatura foi gerada. RFC 3339.

Campos da NF-e

statusstring
processandoautorizadoerrocanceladodenegadoinutilizado
Situação da nota. Só autorizado tem XML e DANFE. Em erro, error_message (motivo da Sefaz) e error_msg (códigos de rejeição) explicam o que corrigir.
chave_nfestring
Chave de acesso de 44 dígitos, atribuída pela Sefaz na autorização.
numerostring
Número da nota na série.
seriestring
Série (normalmente 1).
xml_urlstring
Endereço do XML assinado.
danfe_urlstring
Endereço do DANFE (PDF).
vendor_iduuid
Seller dono da nota, em pedido com vários sellers.
cancel_reasonstring
Justificativa, se a nota foi cancelada.
issued_atstring
Autorização pela Sefaz. RFC 3339.
canceled_atstring
Cancelamento. RFC 3339.
itemsarray
Itens da nota: description, ncm_code, cfop_code, quantity, unit_value, total_value (centavos) e a base, alíquota (icms_rate em pontos-base: 1800 = 18,00%), valor e CST do ICMS.

Erros

StatusQuandoCorpo
400email ausente ou inválido; order_ids ausente ou com mais de 100 ids{"error":"email is required"}, {"error":"invalid email address","detail":"mail: missing '@' or angle-addr"}, {"error":"order_ids is required and must not be empty"}, {"error":"maximum 100 orders per bulk invoice export"}
400template_id de um modelo que não é de fatura{"error":"template type mismatch","detail":"..."}
401Sem credenciais ou token expirado{"error":"invalid or expired token"}
403Sem permissão{"error":"insufficient privileges", ...}
404Pedido inexistente; modelo (template_id) inexistente; loja sem modelo de fatura padrão (HTML); nenhuma fatura encontrada (lote); pedido sem NF-e{"error":"order not found"}, {"error":"template not found"}, {"error":"no default invoice template configured"}, {"error":"no invoices found for the selected orders"}, {"error":"no NF-e found for this order"}
502O e-mail não pôde ser enviado{"error":"failed to send the invoice e-mail","detail":"..."}
503Serviço de e-mail não configurado na loja{"error":"email service not available"}
500Falha ao gerar a fatura ou o PDF{"error":"failed to generate invoice","detail":"..."}
Fatura não é nota fiscal

O PDF desta página é um documento de conferência. Não use como nota fiscal, nem envie ao cliente como se fosse. A nota fiscal é a NF-e (/nfe), emitida e autorizada pela Sefaz. Um pedido pode ter fatura desde o momento da criação e só ter NF-e depois de faturado.

Procure o XML e o DANFE na NF-e, não na fatura

Para anexar a nota ao e-mail do cliente, ao WMS ou ao ERP, leia xml_url e danfe_url do /nfe quando o status for autorizado. Se o seller emite a nota fora da Venddor, ela só aparece no /nfe depois de registrada no pedido.

Veja também

  • Romaneio (packing slip)
  • Nota de crédito
  • Ações em lote
Anterior
Cancelamentos pedidos pelo cliente
Próxima
Romaneio (packing slip)
Nesta página
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também