Idempotência
Nesta página
Como funciona em cada operaçãoA resposta guardadaO cartão fica fora da comparaçãoComo repetir uma chamadaErros de idempotênciaRepita com segurança uma chamada que ficou sem resposta, sem cobrar, assinar ou estornar duas vezes.
Como funciona em cada operação
Idempotency-Key | Rotas |
|---|---|
| Obrigatório | Criar uma fatura, Pagar uma fatura, Estornar uma fatura e Criar uma assinatura. |
| Opcional | Demais rotas POST, PATCH e DELETE com a chave de API. |
| Ignorado | Salvar um cartão, Cadastrar um webhook, Trocar o segredo de um webhook e Defender uma contestação. |
| Não usado | Geração de token de cartão e rotas do Checkout. |
A resposta guardada
O valor do cabeçalho tem até 255 caracteres e é único na conta inteira, qualquer que seja a chave de API usada. Acima disso, a chamada responde 400 de validação, com Idempotency-Key em fields. A primeira resposta fica guardada por 24 horas, com qualquer status, inclusive erro.
| Repetição com a mesma chave | Resposta |
|---|---|
| Mesmo método, caminho e corpo | A resposta da primeira chamada, com o mesmo status, o cabeçalho Idempotent-Replayed: true e sem X-Request-Id. |
| Outro corpo ou outra rota | 409, chave já usada com outra requisição. |
| Enquanto a primeira chamada ainda executa | 409, requisição ainda em processamento. |
Três respostas não ficam guardadas, porque acontecem antes de a chave ser registrada:
- os erros de autenticação;
- o
404da Recorrência não ativada; - os
400de validação dos dados.
Nas rotas que cobram, assinam ou estornam, também não fica guardado o erro que acontece antes de a cobrança seguir para a adquirente: a chave é liberada e pode ser usada de novo. Depois desse envio, a resposta fica guardada, inclusive a do cartão recusado e a de 5xx.
O cartão fica fora da comparação
Na comparação do corpo, não entram o número e o CVV de card nem o card_token: em credit_card no pagamento da fatura e na assinatura, e em payment.credit_card na criação da fatura.
| Repetição com a mesma chave | Resposta |
|---|---|
| Um token novo | A primeira resposta. |
| Cartão digitado com outro número e outro CVV, mas com a mesma validade e o mesmo titular | A primeira resposta. |
Outro card_id, outra validade, outro titular, ou o token trocado pelo cartão digitado e o contrário | 409, chave já usada com outra requisição. |
Em nenhum desses casos algo é cobrado de novo. Como cada token serve para uma operação só, a repetição com card_token pode levar um token novo.
Como repetir uma chamada
Gere a Idempotency-Key antes da primeira tentativa, como um UUID, guarde junto do pedido e reenvie a mesma chave com o mesmo corpo quando não souber o resultado. Para outra operação, ou para tentar outro cartão depois de uma recusa, use uma chave nova.
curl -X POST https://api.sandbox.payzu.dev/v1/invoices/in_7Kd2QmXvB9LtYc4WnRz8Hs/refunds \
-H "Authorization: Bearer SUA_CHAVE_DE_API" \
-H "Idempotency-Key: a3f1c9e2-7b4d-4e8a-9c6f-1d2e3f4a5b6c"Se a resposta for o 409 de requisição em processamento, espere a primeira chamada terminar e repita com a mesma chave. Se o 409 continuar, há duas possibilidades:
| Primeira chamada | O que fazer |
|---|---|
| Ainda executa | Repita com a mesma chave mais tarde. Quando ela terminar, a repetição recebe a resposta guardada ou, se ela terminou com um erro que não fica guardado, é feita como uma nova chamada. |
| Caiu sem resposta | A chave continua respondendo 409 até vencer, em 24 horas. |
Consulte se a fatura, a assinatura ou o estorno existe antes de repetir com outra chave.
Com outra chave, a operação pode ser feita duas vezes se a primeira chamada ainda terminar.
A resposta 422 de chave liberada também pede uma nova tentativa com a mesma chave.
Erros de idempotência
| Código | HTTP | Mensagem |
|---|---|---|
PZ010 | 400 | Envie o cabeçalho Idempotency-Key nesta operação. |
PZ011 | 409 | Idempotency-Key já usada com outra requisição. |
PZ012 | 409 | Requisição com esta Idempotency-Key ainda está em processamento. |
| - | 422 | Requisição com esta Idempotency-Key acabou de ser liberada. Tente novamente. |
Todos os códigos do PayZu Gateway estão no Catálogo de erros.