Pedidos

Requer scope READ_ORDERS em todas as rotas abaixo.

GET /merchant/orders → 200

Lista os pedidos da empresa dona da chave, do mais recente para o mais antigo (paginação por cursor — ver seção 5).

Query:

Campo	Tipo	Obrigatório	Regras / Default
q	string	não	busca em nome/e-mail/documento do cliente e externalRef; se q for um UUID válido, também casa pelo id
status	enum	não	OPEN | PAID | CANCELED | EXPIRED
source	enum	não	PAYMENT_LINK | API_DIRECT | CHECKOUT | MANUAL
customerId	string (uuid)	não	—
productId	string (uuid)	não	filtra pedidos que contêm o produto
limit	int	não	máx 100, default 50
cursor	string	não	cursor opaco da página seguinte

Resposta (200) — item de listagem:

{
  "items": [
    {
      "id": "uuid",
      "externalRef": "pedido-4821",
      "source": "API_DIRECT",
      "status": "PAID",
      "amountCents": 14990,
      "currency": "BRL",
      "customerId": "uuid",
      "customerName": "Maria Souza",
      "customerEmail": "maria@example.com",
      "paymentLinkId": null,
      "createdAt": "2026-07-16T12:00:00.000Z",
      "updatedAt": "2026-07-16T12:03:00.000Z",
      "paidAt": "2026-07-16T12:03:00.000Z",
      "expiresAt": "2026-07-17T12:00:00.000Z",
      "canceledAt": null
    }
  ],
  "nextCursor": null,
  "hasMore": false
}

Exemplo — pedidos pagos, primeira página:

Listar pedidos

curl -s https://goldpay-goldpay-api.f0czp0.easypanel.host/api/merchant/orders \
  -H "X-Api-Key: <SECRET_KEY>" \
  --get \
  --data-urlencode "status=PAID" \
  --data-urlencode "limit=50"

GET /merchant/orders/:id → 200

Detalhe de um pedido. Não encontrado / de outra empresa → 404.

GET /merchant/orders/by-external-ref/:externalRef → 200

Localiza o pedido pelo idempotencyKey/externalRef enviado na criação da cobrança PIX (ver §4 e §6.1). Busca exata (não é LIKE). Não encontrado → 404.

Exemplo — reconciliar pelo seu próprio ID de pedido (o idempotencyKey que você enviou):

Consultar por referência externa

curl -s https://goldpay-goldpay-api.f0czp0.easypanel.host/api/merchant/orders/by-external-ref/pedido-4821 \
  -H "X-Api-Key: <SECRET_KEY>"

Resposta (200, das duas rotas de detalhe acima) — todos os campos do item de listagem, mais customerPhone, documentType, documentNumber, zipCode, city, state, addressRaw, metadata, items[] (id, productId, title, unitPriceCents, quantity, externalRef, metadata) e financialAttempts[] (id, transactionId, providerTransactionId, amountCents, currency, status, paidAt, createdAt) — as tentativas de cobrança PIX associadas ao pedido.