Idempotência
Como repetir com segurança uma chamada que cria algo, usando o cabeçalho Idempotency-Key no fechamento de compra, e o que fazer nas demais rotas.
Uma operação é idempotente quando repeti-la produz o mesmo resultado que fazê-la uma vez. Isso importa porque redes falham: se a sua chamada deu tempo esgotado, você não sabe se o servidor chegou a processá-la. Repetir uma criação sem proteção pode gerar dois pedidos para a mesma compra.
O cabeçalho Idempotency-Key no fechamento de compra
Gere um identificador único por tentativa de compra (um UUID v4 serve) e envie em Idempotency-Key. Use o mesmo valor em todas as repetições da mesma tentativa. O servidor guarda a chave junto com o pedido criado.
| Situação da chave | Resposta |
|---|---|
| Primeira vez | A compra é processada normalmente e o pedido criado fica associado à chave. |
| Repetida, compra já concluída | 200 com o mesmo corpo da primeira resposta. Nenhum pedido novo. |
| Repetida enquanto a primeira ainda está sendo processada | 409 {"error":"in_progress","retry_after_ms":1500}. Espere e tente de novo. |
| Mesma chave em outra sessão de checkout | 422 idempotency key reused with a different checkout session. |
| A primeira tentativa falhou | A chave é liberada e a repetição reprocessa a compra. |
| Sem o cabeçalho | Sem proteção: cada chamada tenta criar um pedido. |
A chave identifica uma intenção de compra, não um cliente. Uma nova compra, mesmo do mesmo cliente, usa uma chave nova.
KEY=$(uuidgen)
curl -X POST "$BASE_URL/api/v1/storefront/checkout/$SESSION_ID/place" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $KEY" \
-d '{}'O corpo e as regras do fechamento de compra são documentados na seção de vitrine desta referência. Aqui importa só o comportamento da chave.
Proteção por conteúdo
Além da chave, o fechamento de compra recusa duplicidades pelo conteúdo, mesmo quando as chaves são diferentes ou ausentes:
| Status | error | Quando |
|---|---|---|
| 409 | cart_already_ordered | Outra requisição já transformou este carrinho em pedido. |
| 409 | order_in_progress | A mesma chave está sendo processada neste instante. |
| 409 | duplicate_order | Um pedido equivalente do mesmo e-mail foi feito há menos de 10 minutos. |
Se você recebe um desses, não crie de novo: consulte os pedidos do cliente para achar o que já foi criado.
Outras rotas de criação
Rotas que criam registros (produtos, clientes, pedidos pelo painel) não aceitam Idempotency-Key e uma repetição cria um segundo registro. Se a chamada deu tempo esgotado ou erro 5xx:
- Não repita às cegas. Consulte primeiro, filtrando por um campo que você controla (SKU do produto, e-mail do cliente, número da ordem de compra) na rota de listagem.
- Só crie de novo se a consulta mostrar que o registro não existe.
- Para reduzir o risco, preencha os campos que devem ser únicos na loja (como SKU de produto e e-mail de cliente): a plataforma recusa um segundo cadastro com o mesmo valor.
Operações de atualização (PUT, PATCH) e de remoção (DELETE) podem ser repetidas. Em uma remoção repetida o segundo DELETE costuma responder 404; trate como sucesso.
Erros comuns
- Gerar a chave dentro do laço de repetição. A chave nova faz o servidor tratar como outra compra. Gere uma vez, fora do laço.
- Reaproveitar a chave entre compras. Cada compra tem a sua; senão a segunda devolve o pedido da primeira.
- Repetir imediatamente em um 409
in_progress. Espereretry_after_ms. - Confiar no cabeçalho em outras rotas. Fora do fechamento de compra ele é ignorado.