(10) Referência

Idempotência

O cabeçalho Idempotency-Key, e como repetir um pedido sem cobrar duas vezes.

Repetir sem cobrar duas vezes

A rede falha no pior momento: o teu servidor manda criar a sessão (ou o estorno), a API grava, e a resposta perde-se no caminho. Se repetires o pedido, não pode nascer uma segunda sessão nem um segundo estorno. Para isso, todos os POST de /v1 levam o cabeçalho Idempotency-Key, com um valor teu, único por operação.

Terminal

curl -s -i "$SPOLLY_API_URL/v1/checkout/sessions" \
  -H "Authorization: Bearer $SPOLLY_SECRET_KEY" \
  -H "Idempotency-Key: encomenda-1042" \
  -H "Content-Type: application/json" \
  -d '{"amount": 1500000, "currency": "AOA", "description": "Vestido de capulana"}'

Repetido com a mesma chave e o mesmo corpo, o pedido devolve a mesma resposta (o mesmo código e o mesmo corpo, com o mesmo id), com o cabeçalho Idempotent-Replayed: true, e não cria nada outra vez. Oito pedidos iguais ao mesmo tempo dão uma escrita e oito respostas iguais.

As regras

Situação	Resposta
Sem o cabeçalho	`400 idempotencia_em_falta`
Chave com mais de 255 carateres	`400 idempotencia_invalida`
A mesma chave, o mesmo corpo	A resposta guardada, com `Idempotent-Replayed: true`
A mesma chave, outro corpo (ou outra rota)	`422 idempotencia_reutilizada`
A mesma chave noutro modo (teste e produção)	São chaves diferentes: o modo conta

As chaves guardam-se durante 24 horas; depois disso, a mesma chave volta a valer como nova. Um pedido que falhou com um erro de validação (4xx antes de gravar) não fica guardado: corriges e repetes com a mesma chave.

Que chave usar

Uma que identifique a operação na tua loja, e não o pedido HTTP: encomenda-1042 para a sessão da encomenda 1042, estorno-1042-1 para o primeiro estorno dela. Assim, um processo que reinicia a meio e volta a tentar dá com a mesma chave. Um UUID novo por operação também serve, desde que o guardes antes de enviar. Os SDK geram um UUID por chamada se não deres nenhuma, e usam o mesmo em todas as retentativas dessa chamada.