Ambientes e autenticação

Toda requisição autentica com uma chave de API no header:

Authorization: Bearer pgz_live_...
Authorization: Bearer pgz_test_...

• A chave determina o ambiente. Não existe header de modo na superfície externa: pgz_live_ opera em produção; pgz_test_ opera no sandbox isolado.
• Isolamento de sandbox é total. Uma requisição pgz_test_ nunca alcança o provedor de pagamento, nunca gera cobrança real, e nunca aparece em dados de produção. Recursos criados com uma chave de um ambiente são invisíveis ao outro.
• Emissão de chaves. O merchant gera e revoga chaves de sandbox e live no cockpit autenticado. A chave em claro é exibida somente na criação; depois disso a plataforma guarda apenas key_hash.
• Chave inválida ou revogada → 401 (invalid_api_key). Escopo insuficiente → 403 (insufficient_scope). Permissão nunca retorna 404.
• Toda chave carrega escopos. Os escopos por endpoint estão na Referência.

---

Idempotência

Todo POST que cria um recurso exige o header:

Idempotency-Key: 3f1a9b2c-6d4e-4a71-9c2f-8e5b1d0a7c33

• Obrigatório em POST /v1/payment_links, POST /v1/quotes, POST /v1/quotes/{id}/accept e POST /v1/payment_intents. Ausente ou vazio → 400 (missing_idempotency_key); acima de 255 chars → 400 (invalid_idempotency_key). Qualquer string única serve — recomendamos UUID v4, mas o formato não é exigido (ADR-0010).
• TTL de 24h, numa tabela dedicada de idempotência. Um replay da mesma chave dentro do TTL retorna a resposta original, byte a byte, com o header Idempotent-Replay: true.
• Mesma chave com body diferente → 409 (idempotency_key_reuse).
• Após 24h a chave é liberada.

---

Envelope de erro

Toda resposta de erro tem a mesma forma. Todo response (sucesso ou erro) carrega o header X-Request-Id.

{
  "error": {
    "code": "invalid_request",
    "message": "...",
    "param": "amount",
    "request_id": "req_9f8c..."
  }
}

• param é o nome do campo quando o erro é de um campo específico; null caso contrário.
• request_id está no corpo e no header X-Request-Id — cite-o em qualquer suporte.

Schemas são estritos. Uma chave desconhecida no corpo de qualquer request → 400 com error.code = "unknown_parameter" e error.param = o nome da chave. Nunca há descarte silencioso.

---

Paginação

Listagens são cursor-based:

GET /v1/payments?limit=50&starting_after=pay_9f8c...

• limit: inteiro, default 20, máximo 100. Acima de 100 → 400 (invalid_request) — não é truncado silenciosamente, para você não paginar achando que recebeu a página inteira.
• starting_after: id do último objeto da página anterior.
• Resposta: { "data": [ ... ], "has_more": true }.

---

Versionamento e depreciação

• A versão vive no path: /v1/. Uma mudança breaking exige uma nova versão de path (/v2/).
• Adicionar um campo a um response não é breaking e acontece dentro de /v1/ sem aviso. Clientes devem ignorar campos desconhecidos.
• Depreciação: uma versão depreciada recebe aviso com no mínimo 12 meses de antecedência. Durante o período, os responses da versão carregam o header Sunset (RFC 8594) com a data de desligamento e um header Deprecation: true. A data de Sunset nunca é antecipada.

---