REST não é um protocolo, é um conjunto de convenções sobre HTTP. Numa API de pagamentos, seguir essas convenções reduz surpresa: o desenvolvedor já sabe o que esperar de um POST, de um 404 e de um 409.
Verbos e recursos
| Verbo | Uso típico |
|---|---|
| POST | Criar uma cobrança Pix ou um checkout. |
| GET | Consultar uma cobrança, listar vendas ou produtos. |
| PATCH/PUT | Atualizar um recurso existente. |
| DELETE | Remover um recurso, quando permitido. |
Códigos de status que importam
| Código | Significado prático |
|---|---|
| 200 / 201 | Sucesso. 201 quando um recurso foi criado. |
| 400 | Payload inválido — corrija os campos antes de repetir. |
| 401 | Credencial ausente ou inválida. |
| 404 | Recurso inexistente ou de outra loja. |
| 409 | Conflito, geralmente idempotência em andamento ou duplicidade. |
| 429 | Limite de requisições atingido — aplique backoff. |
| 5xx | Falha do lado do provedor — pode repetir com backoff. |
Idempotência e retentativa
Toda operação que move dinheiro precisa de chave de idempotência. Enviar a mesma chave duas vezes deve resultar na mesma cobrança, nunca em duas. Isso torna seguro repetir uma requisição que caiu por timeout.
Paginação por cursor
Listas financeiras crescem e mudam durante a leitura. Paginação por cursor evita itens repetidos ou pulados, problema comum na paginação por offset.
Perguntas frequentes
- Posso repetir uma requisição que deu timeout?
- Sim, desde que use a mesma chave de idempotência. Sem ela, existe risco real de cobrança duplicada.