# API do Payflow — o que mudou

A versão da API vai no cabeçalho `Kingdom-Version` de cada resposta e no campo
`api_version` de cada webhook. Uma integração fica presa à versão com que foi
criada: mudanças que partem código só chegam a quem pedir a versão nova.

**O que nunca conta como mudança que parte código** — e por isso pode aparecer
sem versão nova: um campo novo num objecto, um tipo de evento novo (só chega a
quem o subscrever), um valor novo num `status`, um cabeçalho novo, um parâmetro
novo opcional. Escreve o teu código a ignorar o que não conhece.

---

## 2026-09-01 — a primeira

**API** em `https://api.kingdomcompny.com/v1`, especificada em
[`openapi.json`](https://payflow.kingdomcompny.com/api/openapi.json) (OpenAPI 3.1).

- Autenticação com `Authorization: Bearer sk_live_…` ou `sk_test_…`. Uma chave
  de teste só vê o modo de teste. Âmbitos por chave; IPs opcionais.
- Recursos: `products`, `orders`, `customers`, `events`, `refunds`,
  `checkout_sessions`, `webhook_endpoints` — listar (cursor com
  `starting_after`, `limit` de 1 a 100) e obter por id.
- Escrever: `POST /v1/checkout_sessions`, `POST /v1/checkout_sessions/{id}/expire`,
  `POST /v1/refunds`, e criar, mudar, apagar, rodar o segredo e testar
  `webhook_endpoints`.
- `Idempotency-Key` em todos os `POST` e `PATCH` (24 horas; a mesma chave com
  outro corpo é recusada com 409).
- Erros em `application/problem+json` (RFC 9457), sempre com `code` e `request_id`.
- `Request-Id` em todas as respostas; `RateLimit-Limit`, `RateLimit-Remaining`,
  `RateLimit-Reset` — 300 pedidos por minuto por chave.
- Valores em **subunidades** da moeda (R 149,00 = `14900`).
- Sem CORS: uma chave secreta não se usa a partir de um browser.

**Webhooks** — `order.paid`, `order.refunded`, `order.disputed`,
`order.dispute_resolved`, `integration.test`.

- Duas assinaturas em cada entrega: `X-Kingdom-Signature` (`t=…,v1=<hex>`) e a
  do Standard Webhooks (`webhook-id`, `webhook-timestamp`, `webhook-signature`).
- Rotação de segredo com 24 horas em que seguem as duas assinaturas.
- Oito tentativas ao longo de ~45 horas; ordem garantida por pedido.
- JSON Schema de cada evento em
  `https://payflow.kingdomcompny.com/api/schemas/<Tipo>.json`
  (por exemplo `Event.order.paid.json`).

**Link de compra** — `https://payflow.kingdomcompny.com/p/prod_…` com `email`,
`name`, `locale`, `ref` e `return_url`; os outros parâmetros vão para
`metadata`. O regresso acrescenta `status` (`success`, `failed`, `cancelled`) e
`reference`.