API legada/Referência completa/Vitrine /api/storefront

GETPedidos do cliente

Lista os pedidos do cliente logado, do mais recente para o mais antigo, com filtros por status, pagamento e texto.

Devolve os pedidos que o cliente autenticado fez, para a tela "Meus pedidos". Exige o JWT do cliente: chave sfk_ e token vat_ sozinhos não bastam, porque a lista é sempre "do usuário do token".

Se o cliente pertence a uma conta corporativa (vários usuários da mesma empresa B2B), a lista inclui os pedidos de todos os usuários vinculados à conta. Compras com produtos de mais de um seller aparecem como um pedido pai com sub-pedidos.

GET/api/storefront/ordersCliente

Listar os pedidos do cliente logado

Parâmetros de consulta

pageintegerpadrão: 1

Página, a partir de 1.

per_pageintegerpadrão: 20

Itens por página, de 1 a 100. Fora dessa faixa volta para 20.

statusstring

Filtra pelo status do pedido (a letra do cadastro de status da loja, por exemplo O).

payment_statusstring

Filtra pelo status do pagamento (pending, paid...).

searchstring

Texto livre, aplicado no servidor sobre os pedidos do cliente.

Cabeçalhos

Authorizationstringobrigatório

Bearer <jwt> do cliente. Opcionalmente acompanhado de X-API-Key: sfk_... com customer:read, ou de token vat_... com read_orders.

Exemplo de requisição

bash

curl "$BASE_URL/api/storefront/orders?per_page=5&payment_status=pending" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Pedidos do cliente (reduzido a 1 pedido)

json

{
  "orders": [
    {
      "id": "18566b6e-7857-4f00-9e62-52f644c2e78e",
      "order_number": "408316782",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "customer_id": "d4613dde-ac7a-431c-9232-50d8cd6ad5fc",
      "status": "I",
      "status_text": "cancelled",
      "subtotal": 11500,
      "shipping_total": 500,
      "tax_total": 0,
      "discount_total": 3306,
      "total": 8694,
      "currency": "BRL",
      "payment_method": "pix",
      "payment_method_name": "PIX",
      "payment_status": "pending",
      "shipping_method": "Motoboy",
      "customer_email": "maria@example.com",
      "customer_name": "Maria Souza",
      "is_guest": false,
      "items_count": 1,
      "created_at": "2026-10-09T06:30:10.932191Z",
      "updated_at": "2026-10-09T07:15:27.58017Z",
      "items": []
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 5,
  "total_pages": 1
}

Campos da resposta

ordersarray|null

Pedidos da página. Vem null (não lista vazia) quando nada corresponde aos filtros.

orders[].iduuid

Id do pedido. order_id repete o valor.

orders[].order_numberstring

Número do pedido para exibir ao cliente.

orders[].statusstring

Status como letra do cadastro de status da loja. status_text traz o nome em inglês (cancelled).

orders[].subtotalinteger

Soma dos itens em centavos. subtotal_str repete em reais.

orders[].shipping_totalinteger

Frete em centavos.

orders[].tax_totalinteger

Imposto em centavos.

orders[].discount_totalinteger

Descontos em centavos.

orders[].totalinteger

Total em centavos. total_str repete em reais.

orders[].currencystring

Moeda do pedido (BRL).

orders[].payment_methodstring

Código da forma de pagamento. payment_method_name traz o nome.

orders[].payment_statusstring

Situação do pagamento (pending, paid...).

orders[].shipping_methodstring

Nome da forma de envio.

orders[].vendor_iduuid

Seller dono do pedido (em compras de vários sellers, cada sub-pedido tem o seu).

orders[].is_guestboolean

true se o pedido foi feito como visitante.

orders[].items_countinteger

Quantidade de itens.

orders[].itemsarray

Itens do pedido.

total, page, per_page, total_pagesinteger

Paginação.

Erros

Status	Quando	Corpo
401	Sem `Authorization`	`{"error": "missing authorization header"}`
401	JWT inválido ou expirado	`{"error": "..."}`
403	Chave `sfk_` sem `customer:read`, ou token `vat_` sem `read_orders`	`{"error": "missing_scope", "required": "..."}`
500	Falha ao listar	`{"error": "failed to list orders", ...}`

Veja também