Consulta de pedidos

Pesquise o histórico de pedidos do cliente ou consulte um pedido por ID. As duas rotas são somente de leitura, incluem todos os status e estão restritas à loja autorizada.

Autenticação e permissão

Envie Authorization: Bearer API_KEY, X-Store-Slug e Accept: application/json. Em API Keys, abra Permissões na chave existente, marque orders:read e clique em Salvar permissões. O curinga * não concede esse acesso. O titular precisa de vínculo ativo com a loja e deve respeitar os IPs e a validade configurados na chave.

GET /v1/orders

Envie exatamente um cabeçalho: X-Customer-Email ou X-Customer-CPF. Ausência dos dois, envio simultâneo ou identificador inválido retorna 422. Não envie dados pessoais na URL.

  • E-mail: espaços externos removidos e conversão para minúsculas. Comparação exata; pontos e sufixos + são preservados.
  • CPF: 11 dígitos com verificadores válidos, com ou sem máscara. A leitura normaliza também a máscara armazenada. CNPJ não é aceito.
  • Todos os cadastros correspondentes na loja são considerados. Busca por e-mail não se expande para outros e-mails do mesmo CPF.
  • page: inteiro a partir de 1; per_page: de 1 a 50, padrão 20.
  • Ordem por criação decrescente e ID decrescente no empate. Percorra as páginas para obter todo o histórico, de qualquer status.
curl 'https://api.aproveicheckout.com.br/v1/orders?page=1&per_page=20' \
  -H 'Authorization: Bearer CREDENCIAL_FICTICIA' \
  -H 'X-Store-Slug: minha-loja' \
  -H 'X-Customer-Email: cliente@example.com' \
  -H 'Accept: application/json'

Para pesquisar por CPF, substitua o cabeçalho de e-mail por X-Customer-CPF: 012.345.678-90 (exemplo fictício).

{
  "orders": [],
  "pagination": {"page": 1, "per_page": 20, "total": 0, "total_pages": 1}
}

Cada pedido inclui id, transactionId, status (id, slug e name), currency, totalInCents, createdAt, updatedAt, paidAt, refundedAt e items. Cada item resumido inclui id, productId público (string), internalProductId, parentKitId e quantity.

GET /v1/orders/{orderId}

Use o ID interno positivo orders.id retornado na listagem. A consulta por ID não exige e-mail ou CPF. Pedido inexistente ou de outra loja retorna o mesmo erro ORDER_NOT_FOUND (404).

curl 'https://api.aproveicheckout.com.br/v1/orders/123' \
  -H 'Authorization: Bearer CREDENCIAL_FICTICIA' \
  -H 'X-Store-Slug: minha-loja' \
  -H 'Accept: application/json'

O corpo é {"order": {...}}. Além do resumo, o detalhe contém:

  • subtotalInCents, discountInCents e shippingInCents.
  • customer: name, email, cpf e phone do cadastro atual.
  • shippingAddress: zipcode, street, number, complement, neighborhood, city, state e country do endereço vinculado ao pedido.
  • trackingCode e deliveryStatus (id, slug e name), derivados dos envios.
  • shipments: envios com identificador, situação logística, transportadora, rastreios, datas de postagem/entrega e itens com quantidades. Etiqueta gerada permanece aguardando envio; entregas parciais não concluem o pedido inteiro.
  • payments: id, method, gatewayStatus original, amountInCents, installments, createdAt e paidAt, em ordem de criação e ID crescentes.
  • items: dados do resumo mais name, sku, unitPriceInCents, totalPriceInCents, externalProductId, externalVariantId, isCrossSell, isOrderBump e isUpsell.

Nome e SKU priorizam o registro histórico; quando ausentes, podem vir do cadastro do produto. Valores vêm exclusivamente do item comprado: unit_price, price_final, promotional_price ou price, nessa ordem; totalPriceInCents vem de total_price. Nunca se usa o preço atual do catálogo. Produtos excluídos não removem os itens do pedido.

Valores monetários são inteiros em centavos na moeda informada; datas são ISO 8601 em UTC, terminadas em Z. Campos sem dados são null. paidAt é o primeiro pagamento registrado em orders_payments, podendo continuar preenchido após estorno; consulte o status atual do pedido e dos pagamentos. A API não calcula elegibilidade, início de teste ou vigência de assinatura.

Erros e operação

Formato: {"status":"error","code":"...","message":"...","errors":{...}}. errors é incluído quando aplicável.

  • 401: credencial ausente, inválida ou expirada.
  • 403: falta de permissão explícita, acesso à loja negado ou IP não autorizado.
  • 404: pedido inexistente ou pertencente a outra loja.
  • 422: cabeçalhos, identificadores, ID ou paginação inválidos.
  • 429: limite de requisições; respeite Retry-After.
  • 503 ORDERS_UNAVAILABLE: falha na consulta, inclusive parcial. Não interpretar como lista vazia.

Respostas têm Cache-Control: no-store. As duas rotas compartilham 60 requisições/minuto por chave e loja, além de 600/minuto por IP antes da autenticação. A leitura não grava dados de negócio, auditoria em banco nem last_used_at; somente contadores do limitador podem mudar.

Credenciais, cabeçalhos de e-mail/CPF e conteúdo das respostas devem ficar fora de logs de acesso e observabilidade. A aplicação sanitiza erros e exclui as rotas do Debugbar; configure a mesma proteção no proxy/APM. Payloads internos de gateway, dados de cartão, custos e comissões não são retornados.