Idempotência

Repita um POST sem medo de criar recursos duplicados.

Idempotency-Key: pedido-12345

Endpoints suportados

O header é aceito nos endpoints de criação:

POST /products
POST /checkouts
POST /webhooks

Endpoints GET, PATCH, DELETE e as ações /archive e /test não usam o header.

Comportamento

Situação	Resultado
Mesma chave + mesmo payload	Replay: a resposta original é devolvida, sem criar um novo recurso.
Mesma chave + payload diferente	409 `idempotency_conflict`
Chave nova	Requisição processada normalmente.

Retenção

As chaves de idempotência são guardadas por 24 horas por loja. Depois desse prazo a mesma chave volta a ser tratada como nova. A chave pode ter até 255 caracteres.

Gere um valor único por operação de negócio (por exemplo, o id do pedido no seu sistema) e reutilize-o em todas as retentativas dessa mesma operação.

curl -X POST https://pitra.com.br/api/public/v1/products \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-12345" \
  -d '{"nome":"Curso de Node","preco":197.9}'