Vendas

A API de vendas é somente leitura.

Não existem operações de POST, PATCH, PUT ou DELETE em vendas. Esses verbos respondem 405 method_not_allowed. Cancelamento e reembolso não são feitos pela API.

O objeto venda

{
  "object": "sale",
  "id": "9c8b7a6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
  "codigo": "PTR-4821",
  "product_id": "6f1b1c9e-6a0a-4a2f-9d0c-2b1c4a5e7f10",
  "status": "approved",
  "valor": 197.9,
  "metodo_pagamento": "pix",
  "email": "cliente@exemplo.com",
  "whatsapp": "5511999999999",
  "origin": "checkout",
  "bump_product_id": null,
  "bump_valor": null,
  "created_at": "2026-07-30T12:00:00.000Z"
}

A resposta contém exatamente estes campos. Dados internos de processamento não fazem parte do contrato público.

Listar vendas

GET/api/public/v1/salesscope sales:read

Ordenadas da mais recente para a mais antiga, com paginação por cursor.

curl "https://pitra.com.br/api/public/v1/sales?status=approved&limit=50" \
  -H "Authorization: Bearer sk_live_..."

{ "object": "list", "data": [ /* vendas */ ], "has_more": true, "next_cursor": "..." }

Filtros de vendas

Parâmetro	Tipo	Descrição
`limit`	integer	1–100, padrão 20.
`starting_after`	string	Cursor da página anterior.
`status`	string	Status exato da venda (ex.: pending, approved, refunded).
`product_id`	uuid	Vendas de um produto específico.
`codigo`	string	Código PTR da venda.
`email`	string	E-mail do comprador.
`created_after`	ISO 8601	Vendas criadas a partir dessa data.
`created_before`	ISO 8601	Vendas criadas até essa data.

Parâmetros fora desta lista devolvem 400 invalid_request. Datas inválidas e product_id que não seja UUID também são rejeitados.

Consultar venda

GET/api/public/v1/sales/{id}scope sales:read

curl https://pitra.com.br/api/public/v1/sales/9c8b7a6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d \
  -H "Authorization: Bearer sk_live_..."

Resposta 200: o objeto venda. Venda de outra loja devolve 404 not_found.