Nota de crédito

Gera o documento de nota de crédito de um pedido, em JSON, HTML ou PDF.

A nota de crédito é o documento que acompanha uma devolução ou um reembolso: ela repete os itens e os valores do pedido com o título "Nota de crédito". A plataforma monta o documento na hora, a partir do pedido; nada é gravado e a chamada pode ser repetida à vontade.

As três rotas abaixo respondem com o mesmo documento em formatos diferentes.

GET/api/v1/admin/orders/{id}/credit-noteAdmin

Nota de crédito (JSON ou HTML)

Devolve a nota de crédito em JSON (padrão). Com ?format=html ou Accept: text/html, devolve o HTML do modelo "nota de crédito" (credit_memo) salvo pelo lojista em Documentos; se a loja não tem esse modelo, responde 404. Exige view_orders ou manage_orders.

Path parameters

iduuidobrigatório

Id do pedido.

Query parameters

formatstringpadrão: json

jsonhtmlpdf

html usa o modelo da loja; pdf devolve o PDF (o mesmo que credit-note.pdf).

langstringpadrão: pt-BR

(HTML) Idioma do modelo.

POST/api/v1/admin/orders/{id}/credit-noteAdmin

Generate a credit note

Mesmo resultado do GET, por POST. Existe para telas e integrações que tratam "gerar documento" como uma ação. Cada chamada gera o documento de novo; nada fica salvo. Exige manage_orders e aceita os mesmos parâmetros de consulta.

Path parameters

iduuidobrigatório

Id do pedido.

GET/api/v1/admin/orders/{id}/credit-note.pdfAdmin

Credit note as PDF

A nota de crédito em PDF (application/pdf, arquivo nota-credito-<número>.pdf).

Path parameters

iduuidobrigatório

Id do pedido.

Exemplo de requisição

bash

# JSON
curl "$BASE_URL/api/v1/admin/orders/$ORDER_ID/credit-note" -H "Authorization: Bearer $TOKEN"

# PDF
curl -o nota-credito.pdf "$BASE_URL/api/v1/admin/orders/$ORDER_ID/credit-note.pdf" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Nota de crédito em JSON

json

{
  "document_type": "credit_note",
  "order_number": "PEDIDO-20261011-0003",
  "generated_at": "2026-10-11T20:15:27.083070Z",
  "order": { "id": "fdbcc184-7cdc-4cf9-aaf7-5a1f7b6370e2", "order_number": "PEDIDO-20261011-0003", "status": "pending", "currency": "BRL" },
  "customer": { "name": "Maria Souza", "email": "maria.souza@example.com", "phone": "11999990000" },
  "addresses": {
    "billing": { "name": "Maria Souza", "address_line1": "Avenida Paulista, 1000", "city": "São Paulo", "state": "SP", "postal_code": "01310-100", "country": "BR" },
    "shipping": { "name": "Maria Souza", "address_line1": "Avenida Paulista, 1000", "city": "São Paulo", "state": "SP", "postal_code": "01310-100", "country": "BR" }
  },
  "items": [
    { "product_name": "Notebook Slim Rosa", "product_sku": "SD-002373", "quantity": 1, "unit_price": 11500, "discount": 0, "tax": 0, "total": 11500 }
  ],
  "totals": { "subtotal": 11500, "shipping_total": 1000, "tax_total": 0, "discount_total": 0, "total": 12500 },
  "payment": { "method": "pagamento-na-entrega", "status": "pending" },
  "vendor": { "company_name": "Loja Seller Teste", "email": "contato@lojaseller.example.com" }
}

Campos da resposta

document_typestring

Sempre credit_note. Permite distinguir este documento de uma fatura sem olhar a URL.

order_numberstring

Número do pedido.

generated_atstring

Quando foi gerada. RFC 3339.

orderobject

Cabeçalho do pedido (id, order_number, status, created_at, currency).

customerobject

Comprador (name, email, cpf/cnpj, phone).

addressesobject

billing e shipping.

itemsarray

Linhas do pedido, com valores em centavos. A nota de crédito lista todos os itens do pedido, não só os devolvidos.

totalsobject

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

paymentobject

Forma e situação do pagamento.

vendorobject

Seller, quando o pedido é de um seller.

Erros

Status	Quando	Corpo
401	Sem credenciais ou token expirado	`{"error":"invalid or expired token"}`
403	Sem permissão (`manage_orders` no POST)	`{"error":"insufficient privileges", ...}`
404	Pedido inexistente; ou HTML pedido e a loja não tem modelo de nota de crédito	`{"error":"order not found"}` ou `{"error":"no default credit_memo template configured"}`
500	Falha ao gerar o documento	`{"error":"failed to generate credit note","detail":"..."}`

Veja também

Nota de crédito

Gera o documento de nota de crédito de um pedido, em JSON, HTML ou PDF.

As três rotas abaixo respondem com o mesmo documento em formatos diferentes.

GET/api/v1/admin/orders/{id}/credit-noteAdmin

Nota de crédito (JSON ou HTML)

Path parameters

iduuidobrigatório

Id do pedido.

Query parameters

formatstringpadrão: json

jsonhtmlpdf

html usa o modelo da loja; pdf devolve o PDF (o mesmo que credit-note.pdf).

langstringpadrão: pt-BR

(HTML) Idioma do modelo.

POST/api/v1/admin/orders/{id}/credit-noteAdmin

Generate a credit note

Path parameters

iduuidobrigatório

Id do pedido.

GET/api/v1/admin/orders/{id}/credit-note.pdfAdmin

Credit note as PDF

A nota de crédito em PDF (application/pdf, arquivo nota-credito-<número>.pdf).

Path parameters

iduuidobrigatório

Id do pedido.

Exemplo de requisição

bash

# JSON
curl "$BASE_URL/api/v1/admin/orders/$ORDER_ID/credit-note" -H "Authorization: Bearer $TOKEN"

# PDF
curl -o nota-credito.pdf "$BASE_URL/api/v1/admin/orders/$ORDER_ID/credit-note.pdf" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Nota de crédito em JSON

json

{
  "document_type": "credit_note",
  "order_number": "PEDIDO-20261011-0003",
  "generated_at": "2026-10-11T20:15:27.083070Z",
  "order": { "id": "fdbcc184-7cdc-4cf9-aaf7-5a1f7b6370e2", "order_number": "PEDIDO-20261011-0003", "status": "pending", "currency": "BRL" },
  "customer": { "name": "Maria Souza", "email": "maria.souza@example.com", "phone": "11999990000" },
  "addresses": {
    "billing": { "name": "Maria Souza", "address_line1": "Avenida Paulista, 1000", "city": "São Paulo", "state": "SP", "postal_code": "01310-100", "country": "BR" },
    "shipping": { "name": "Maria Souza", "address_line1": "Avenida Paulista, 1000", "city": "São Paulo", "state": "SP", "postal_code": "01310-100", "country": "BR" }
  },
  "items": [
    { "product_name": "Notebook Slim Rosa", "product_sku": "SD-002373", "quantity": 1, "unit_price": 11500, "discount": 0, "tax": 0, "total": 11500 }
  ],
  "totals": { "subtotal": 11500, "shipping_total": 1000, "tax_total": 0, "discount_total": 0, "total": 12500 },
  "payment": { "method": "pagamento-na-entrega", "status": "pending" },
  "vendor": { "company_name": "Loja Seller Teste", "email": "contato@lojaseller.example.com" }
}

Campos da resposta

document_typestring

Sempre credit_note. Permite distinguir este documento de uma fatura sem olhar a URL.

order_numberstring

Número do pedido.

generated_atstring

Quando foi gerada. RFC 3339.

orderobject

Cabeçalho do pedido (id, order_number, status, created_at, currency).

customerobject

Comprador (name, email, cpf/cnpj, phone).

addressesobject

billing e shipping.

itemsarray

Linhas do pedido, com valores em centavos. A nota de crédito lista todos os itens do pedido, não só os devolvidos.

totalsobject

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

paymentobject

Forma e situação do pagamento.

vendorobject

Seller, quando o pedido é de um seller.

Erros

Status	Quando	Corpo
401	Sem credenciais ou token expirado	`{"error":"invalid or expired token"}`
403	Sem permissão (`manage_orders` no POST)	`{"error":"insufficient privileges", ...}`
404	Pedido inexistente; ou HTML pedido e a loja não tem modelo de nota de crédito	`{"error":"order not found"}` ou `{"error":"no default credit_memo template configured"}`
500	Falha ao gerar o documento	`{"error":"failed to generate credit note","detail":"..."}`