Idempotência
Redes falham. Com Idempotency-Key você pode repetir uma criação quantas vezes precisar sem cobrar, emitir ou sacar duas vezes.
Como funciona
- Envie o cabeçalho Idempotency-Key: <valor único> em operações POST de criação (8–100 caracteres de A-Za-z0-9_.:-). Um UUID ou o id do seu pedido servem.
- Obrigatório em POST /api/pixout/create; recomendado em todas as outras criações.
- As chaves valem por conta. A impressão digital da requisição inclui método, rota e corpo: reutilizar a chave em outra rota ou com outro corpo gera 422.
| Situação | Resultado |
|---|---|
| Mesma chave + mesmo corpo (já concluída) | Devolve a resposta original, com o cabeçalho Idempotent-Replayed: true. Nada é criado de novo. |
| Mesma chave + corpo diferente | 422, code idempotency_key_reused. |
| Mesma chave ainda em processamento | 409, code idempotency_in_progress — aguarde e repita. |
| Chave ausente (saque) | 400, code idempotency_key_required. |
| Chave com formato inválido | 400, code idempotency_key_invalid. |
#!/usr/bin/env bash
# Repetir a MESMA operação com a MESMA Idempotency-Key: a 2ª chamada devolve a resposta original
# (cabeçalho Idempotent-Replayed: true) e NÃO cria um segundo registro.
set -euo pipefail
: "${SHARKPAY_BASE_URL:?}" "${SHARKPAY_TOKEN:?}"
KEY="pedido-$(date +%s)-retry-demo"
BODY='{"name":"Cliente Idempotente","document":"'$(date +%s)'","document_type":"CPF","zipcode":"01001000","country_id":30,"state":"SP","city":"São Paulo","district":"Sé","street":"Praça da Sé","number":"1","email":"idem-'$(date +%s)'@example.com","phone":"1133334444","mobilephone":"11999998888"}'
for i in 1 2; do
curl -sS -i -X POST "$SHARKPAY_BASE_URL/api/customer" \
-H "Authorization: Bearer $SHARKPAY_TOKEN" -H "Content-Type: application/json" \
-H "Idempotency-Key: $KEY" -d "$BODY" | grep -iE '^(HTTP/|idempotent-replayed)'
doneBoas práticas
- Derive a chave do pedido (ex.: pix-PED-1042), não de um aleatório novo a cada tentativa — assim um reenvio do seu job também é seguro.
- Guarde a chave junto do pedido antes de chamar a API.
- Se mudar o corpo (novo valor), use uma nova chave.
- Em timeout ou 5xx, repita a mesma chamada com a mesma chave. Em 4xx de validação, corrija o corpo e use nova chave.