API atual/Referência completa/Pedidos e conta do cliente

Fatura do pedido

Fatura em JSON, HTML ou PDF e envio da fatura por e-mail.

A fatura é o comprovante do pedido gerado pela plataforma (itens, totais, endereços, pagamento, vendedor). Não é a nota fiscal eletrônica: a NF-e, emitida pelo seller junto à Receita, fica em Nota fiscal (NF-e). Esta página tem três rotas: a fatura em dados (ou HTML), a fatura em PDF e o envio da fatura por e-mail.

GET/api/v1/storefront/orders/{id}/invoiceCliente

Fatura do pedido em JSON ou HTML

Parâmetros de caminho

iduuidobrigatório

Id do pedido.

Parâmetros de consulta

formatstring

html

html devolve a fatura renderizada com o modelo padrão da loja. Sem ele, o padrão é JSON. Mandar Accept: text/html tem o mesmo efeito.

langstring

Só em HTML: idioma do modelo (pt-BR, en).

template_iduuid

Só em HTML: id de um modelo de fatura específico da loja. Id desconhecido responde 404 template not found.

bash

curl "$BASE_URL/api/v1/storefront/orders/$ORDER_ID/invoice" \
  -H "Authorization: Bearer $TOKEN"

200Fatura em JSON

json

{
  "order": {
    "id": "6af86ed3-d949-474d-8e04-513c6e83bfe4",
    "order_number": "PEDIDO-20261011-0009",
    "status": "pending",
    "currency": "BRL",
    "created_at": "2026-10-11T20:55:25.558277Z"
  },
  "customer": {
    "name": "Maria Souza",
    "email": "maria.souza@example.com",
    "phone": "11987654321",
    "cpf": "123.456.789-09",
    "person_type": "F"
  },
  "vendor": { "company_name": "Loja Exemplo", "email": "contato@lojaexemplo.example.com" },
  "addresses": {
    "billing": {
      "name": "Maria Souza",
      "address_line1": "Avenida Paulista, 1000",
      "address_line2": "Apto 52",
      "district": "Bela Vista",
      "city": "São Paulo",
      "state": "SP",
      "postal_code": "01310-100",
      "country": "BR",
      "phone": "11987654321",
      "cpf": "123.456.789-09"
    },
    "shipping": { "name": "Maria Souza", "address_line1": "Avenida Paulista, 1000", "city": "São Paulo", "state": "SP", "postal_code": "01310-100", "country": "BR" }
  },
  "items": [
    {
      "product_name": "Caneca Exemplo",
      "product_sku": "CAN-002",
      "unit_price": 4990,
      "quantity": 1,
      "discount": 724,
      "tax": 0,
      "total": 4266,
      "options": {}
    }
  ],
  "totals": { "subtotal": 4990, "shipping_total": 1000, "tax_total": 0, "discount_total": 724, "total": 5266 },
  "tax": { "total_tax": 0 },
  "payment": { "method": "pix", "status": "pending", "details": { "payment_method": { "method": "pix" } } },
  "generated_at": "2026-10-11T20:55:29.455169Z"
}

Campos da resposta

orderobject

Identificação do pedido: id, order_number, status (código longo), currency e created_at.

customerobject

Dados do comprador. cpf é o CPF ou CNPJ gravado; person_type é F (pessoa física) ou J (jurídica).

vendorobject

Seller emissor: company_name e email.

addressesobject

billing e shipping, cada um com name, linhas de endereço, district, city, state, postal_code, country, phone e cpf.

itemsarray

Linhas: product_name, product_sku, unit_price, quantity, discount, tax, total (centavos) e options.

totalsobject

subtotal, shipping_total, tax_total, discount_total e total, todos em centavos.

paymentobject

method, status e details (por exemplo, o desconto de PIX aplicado: pix_discount.amount_cents e bps).

generated_atstring

Quando a fatura foi gerada, RFC 3339.

Com format=html a resposta é text/html; charset=utf-8 (sem cache), pronta para exibir ou imprimir. Se a loja não tem um modelo de fatura padrão, responde 404 no default invoice template configured.

GET/api/v1/storefront/orders/{id}/invoice.pdfCliente

Fatura do pedido em PDF

Devolve o arquivo PDF (A4) como download: Content-Type: application/pdf e Content-Disposition: attachment; filename="fatura-<número do pedido>.pdf". No navegador use o link direto; num aplicativo, baixe o corpo binário com o cabeçalho de autorização e salve ou compartilhe o arquivo.

Parâmetros de caminho

iduuidobrigatório

Id do pedido.

bash

curl "$BASE_URL/api/v1/storefront/orders/$ORDER_ID/invoice.pdf" \
  -H "Authorization: Bearer $TOKEN"

Erros

Status	Quando	Corpo
401	Sem token, ou token inválido ou expirado	`{"error":"missing authorization header"}` / `{"error":"invalid or expired token"}`
404	O id não existe ou o pedido não é seu (a API nunca diz qual dos dois)	`{"error":"order not found"}`
400	`template_id` de tipo errado (só HTML)	`{"error":"template type mismatch"}`
404	Modelo informado não existe, ou a loja não tem modelo padrão (só HTML)	`{"error":"template not found"}` / `{"error":"no default invoice template configured"}`
500	Falha ao gerar a fatura ou o PDF	`{"error":"failed to generate invoice PDF","detail":"..."}`

POST/api/v1/storefront/orders/{id}/invoice/sendCliente

Envia a fatura em PDF por e-mail

O cliente informa até 3 endereços de e-mail e a plataforma envia a fatura em PDF anexada. É útil para encaminhar a fatura ao financeiro da empresa. A rota fica desligada por padrão: a loja precisa ativar a configuração de fatura por e-mail do cliente, senão a resposta é 404. O idioma do e-mail segue o cabeçalho Accept-Language (en envia em inglês; qualquer outro, português).

Parâmetros de caminho

iduuidobrigatório

Id do pedido.

Corpo da requisição

emailstring

Um destinatário. Aceita o formato Nome <a@b.com>.

emailsarray

Lista de destinatários. Junto com email, no máximo 3 endereços; repetidos (sem diferenciar maiúsculas) contam uma vez. Pelo menos um dos dois campos é obrigatório.

bash

curl -X POST "$BASE_URL/api/v1/storefront/orders/$ORDER_ID/invoice/send" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "emails": [
    "financeiro@empresa.example.com",
    "maria.souza@example.com"
  ]
}'

200Fatura enviada

json

{
  "sent": true,
  "to": "financeiro@empresa.example.com",
  "recipients": ["financeiro@empresa.example.com", "maria.souza@example.com"],
  "order_id": "6af86ed3-d949-474d-8e04-513c6e83bfe4",
  "order_number": "PEDIDO-20261011-0009",
  "filename": "fatura-PEDIDO-20261011-0009.pdf"
}

Status	Quando	Corpo
400	Nenhum e-mail, e-mail inválido, mais de 3 destinatários, ou corpo que não é JSON	`{"error":"email is required"}` / `{"error":"invalid email address"}` / `{"error":"too many recipients"}`
401	Sem token, ou token inválido ou expirado	`{"error":"missing authorization header"}` / `{"error":"invalid or expired token"}`
404	Pedido que não é seu, ou recurso desligado na loja	`{"error":"order not found"}` / `{"error":"not found"}`
429	Um envio para o mesmo pedido nos últimos 30 segundos. O cabeçalho `Retry-After: 30` informa a espera.	`{"error":"invoice was just sent, try again shortly"}`
502	O provedor de e-mail recusou o envio	`{"error":"failed to send the invoice e-mail","detail":"..."}`
503	Serviço de e-mail indisponível na loja	`{"error":"email service not available"}`

Veja também

Fatura do pedido

Fatura em JSON, HTML ou PDF e envio da fatura por e-mail.

GET/api/v1/storefront/orders/{id}/invoiceCliente

Fatura do pedido em JSON ou HTML

Parâmetros de caminho

iduuidobrigatório

Id do pedido.

Parâmetros de consulta

formatstring

html

html devolve a fatura renderizada com o modelo padrão da loja. Sem ele, o padrão é JSON. Mandar Accept: text/html tem o mesmo efeito.

langstring

Só em HTML: idioma do modelo (pt-BR, en).

template_iduuid

Só em HTML: id de um modelo de fatura específico da loja. Id desconhecido responde 404 template not found.

bash

curl "$BASE_URL/api/v1/storefront/orders/$ORDER_ID/invoice" \
  -H "Authorization: Bearer $TOKEN"

200Fatura em JSON

json

{
  "order": {
    "id": "6af86ed3-d949-474d-8e04-513c6e83bfe4",
    "order_number": "PEDIDO-20261011-0009",
    "status": "pending",
    "currency": "BRL",
    "created_at": "2026-10-11T20:55:25.558277Z"
  },
  "customer": {
    "name": "Maria Souza",
    "email": "maria.souza@example.com",
    "phone": "11987654321",
    "cpf": "123.456.789-09",
    "person_type": "F"
  },
  "vendor": { "company_name": "Loja Exemplo", "email": "contato@lojaexemplo.example.com" },
  "addresses": {
    "billing": {
      "name": "Maria Souza",
      "address_line1": "Avenida Paulista, 1000",
      "address_line2": "Apto 52",
      "district": "Bela Vista",
      "city": "São Paulo",
      "state": "SP",
      "postal_code": "01310-100",
      "country": "BR",
      "phone": "11987654321",
      "cpf": "123.456.789-09"
    },
    "shipping": { "name": "Maria Souza", "address_line1": "Avenida Paulista, 1000", "city": "São Paulo", "state": "SP", "postal_code": "01310-100", "country": "BR" }
  },
  "items": [
    {
      "product_name": "Caneca Exemplo",
      "product_sku": "CAN-002",
      "unit_price": 4990,
      "quantity": 1,
      "discount": 724,
      "tax": 0,
      "total": 4266,
      "options": {}
    }
  ],
  "totals": { "subtotal": 4990, "shipping_total": 1000, "tax_total": 0, "discount_total": 724, "total": 5266 },
  "tax": { "total_tax": 0 },
  "payment": { "method": "pix", "status": "pending", "details": { "payment_method": { "method": "pix" } } },
  "generated_at": "2026-10-11T20:55:29.455169Z"
}

Campos da resposta

orderobject

Identificação do pedido: id, order_number, status (código longo), currency e created_at.

customerobject

Dados do comprador. cpf é o CPF ou CNPJ gravado; person_type é F (pessoa física) ou J (jurídica).

vendorobject

Seller emissor: company_name e email.

addressesobject

billing e shipping, cada um com name, linhas de endereço, district, city, state, postal_code, country, phone e cpf.

itemsarray

Linhas: product_name, product_sku, unit_price, quantity, discount, tax, total (centavos) e options.

totalsobject

subtotal, shipping_total, tax_total, discount_total e total, todos em centavos.

paymentobject

method, status e details (por exemplo, o desconto de PIX aplicado: pix_discount.amount_cents e bps).

generated_atstring

Quando a fatura foi gerada, RFC 3339.

GET/api/v1/storefront/orders/{id}/invoice.pdfCliente

Fatura do pedido em PDF

Parâmetros de caminho

iduuidobrigatório

Id do pedido.

bash

curl "$BASE_URL/api/v1/storefront/orders/$ORDER_ID/invoice.pdf" \
  -H "Authorization: Bearer $TOKEN"

Erros

Status	Quando	Corpo
401	Sem token, ou token inválido ou expirado	`{"error":"missing authorization header"}` / `{"error":"invalid or expired token"}`
404	O id não existe ou o pedido não é seu (a API nunca diz qual dos dois)	`{"error":"order not found"}`
400	`template_id` de tipo errado (só HTML)	`{"error":"template type mismatch"}`
404	Modelo informado não existe, ou a loja não tem modelo padrão (só HTML)	`{"error":"template not found"}` / `{"error":"no default invoice template configured"}`
500	Falha ao gerar a fatura ou o PDF	`{"error":"failed to generate invoice PDF","detail":"..."}`

POST/api/v1/storefront/orders/{id}/invoice/sendCliente

Envia a fatura em PDF por e-mail

Parâmetros de caminho

iduuidobrigatório

Id do pedido.

Corpo da requisição

emailstring

Um destinatário. Aceita o formato Nome <a@b.com>.

emailsarray

Lista de destinatários. Junto com email, no máximo 3 endereços; repetidos (sem diferenciar maiúsculas) contam uma vez. Pelo menos um dos dois campos é obrigatório.

bash

curl -X POST "$BASE_URL/api/v1/storefront/orders/$ORDER_ID/invoice/send" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "emails": [
    "financeiro@empresa.example.com",
    "maria.souza@example.com"
  ]
}'

200Fatura enviada

json

{
  "sent": true,
  "to": "financeiro@empresa.example.com",
  "recipients": ["financeiro@empresa.example.com", "maria.souza@example.com"],
  "order_id": "6af86ed3-d949-474d-8e04-513c6e83bfe4",
  "order_number": "PEDIDO-20261011-0009",
  "filename": "fatura-PEDIDO-20261011-0009.pdf"
}

Status	Quando	Corpo
400	Nenhum e-mail, e-mail inválido, mais de 3 destinatários, ou corpo que não é JSON	`{"error":"email is required"}` / `{"error":"invalid email address"}` / `{"error":"too many recipients"}`
401	Sem token, ou token inválido ou expirado	`{"error":"missing authorization header"}` / `{"error":"invalid or expired token"}`
404	Pedido que não é seu, ou recurso desligado na loja	`{"error":"order not found"}` / `{"error":"not found"}`
429	Um envio para o mesmo pedido nos últimos 30 segundos. O cabeçalho `Retry-After: 30` informa a espera.	`{"error":"invoice was just sent, try again shortly"}`
502	O provedor de e-mail recusou o envio	`{"error":"failed to send the invoice e-mail","detail":"..."}`
503	Serviço de e-mail indisponível na loja	`{"error":"email service not available"}`