Idempotência
Como a Idempotência Funciona#
A idempotência é um mecanismo de segurança essencial em nossa API, projetado para garantir que uma operação seja executada apenas uma única vez, mesmo que a requisição seja enviada múltiplas vezes. Isso previne o processamento duplicado de eventos (como pagamentos ou reembolsos), assegurando a consistência e a integridade dos dados em todas as transações.
Utilização do x-Idempotency-Key#
Para ativar a idempotência, você deve incluir o cabeçalho x-Idempotency-Key em suas requisições de pagamentos e reembolsos.
Formato: O valor de x-Idempotency-Key deve ser uma string única para cada operação, com um limite de tamanho definido (geralmente até 255 caracteres, mas verifique a documentação específica da API para o limite exato).
Comportamento da API#
A chave x-Idempotency-Key atua como um identificador exclusivo para cada tentativa de operação.
Primeira Requisição:
Se o x-Idempotency-Key enviado não tiver sido utilizado anteriormente, a API processará a requisição normalmente.
Requisição Repetida (Chave Já Processada):
Se você reenviar uma requisição com um x-Idempotency-Key que já foi processado com sucesso, a API não executará a operação novamente. Em vez disso, ela retornará o mesmo resultado da primeira execução bem-sucedida. Isso garante que não haverá duplicação de pagamentos ou reembolsos.
Requisição Repetida (Chave em Processamento):
Caso você envie uma requisição com um x-Idempotency-Key para uma operação que já está em processamento (ainda não finalizada), a API retornará o status HTTP 208 - Already Reported. Neste cenário, é crucial que você repita a chamada após um breve intervalo para obter o status final da operação.
Gerenciamento de Erros#
A idempotência também influencia como os erros são tratados:
Erros Retentáveis: Se uma requisição falhar com um erro que pode ser retentado (ex: problemas temporários de conexão), uma nova tentativa com a mesma chave de idempotência resultará em uma retentativa da operação.
Erros Não Retentáveis: Para erros que não são retentáveis (ex: parâmetros inválidos, problemas de validação), o resultado da requisição com a mesma x-Idempotency-Key será sempre o mesmo erro, impedindo novas tentativas de processamento da mesma operação falha.
A tabela a seguir contém uma classificação dos tipos de erros não retentáveis:
| Erro Type PicPay | Status Code | Message |
|---|---|---|
| Duplicated_Transaction | (400) Bad Request | Duplicated transaction |
| Funding_source_unavailable | (403) Forbidden | Funding source unavailable |
| Insufficient_funds | (406) Not Acceptable | Insufficient funds |
| Invalid_funding_source | (406) Not Acceptable | Invalid founding source |
| Account_closed | (406) Not Acceptable | The account is closed |
| Account_on_hold | (406) Not Acceptable | The account is on hold |
| Invalid_Permission_refund | (406) Not Acceptable | Invalid Permission |