Idempotency Key

Visão Geral

A API Selectwin suporta chaves de idempotência (Idempotency Keys) para garantir que requisições sensíveis não sejam processadas mais de uma vez, mesmo em caso de falhas de rede, timeouts ou retentativas de requisição. Esta funcionalidade é essencial para operações críticas como criação de transações, saques ou quaisquer operações que não devam ser duplicadas.

O que é Idempotência?

Na teoria de sistemas, uma operação é considerada idempotente quando produz o mesmo resultado independentemente de ser executada uma ou múltiplas vezes. No contexto de APIs, isso significa que a mesma requisição pode ser repetida sem efeitos colaterais indesejados.

Por exemplo, se você envia uma requisição para criar uma transação de R$ 100, e ocorre um timeout antes de receber a resposta, você não sabe se a transação foi processada. Com idempotência, você pode enviar a mesma requisição novamente com segurança, garantindo que apenas uma única transação será criada.

Como Utilizar Chaves de Idempotência

Para usar esta funcionalidade, inclua um cabeçalho X-Idempotency-Key com um valor único em suas requisições:

curl -X POST "https://api.selectwin.io/v1/transactions" \
     -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ" \
     -H "Content-Type: application/json" \
     -H "X-Idempotency-Key: 2dfc6a63-5df5-4900-baca-e49d91ef393e" \
     -d '{
       "amount": 10000,
       ... Data
     }'

Requisitos para Chaves de Idempotência

As chaves de idempotência devem seguir estas regras:

1. Unicidade: Cada chave deve ser única para cada operação distinta
2. Formato: Recomendamos utilizar UUIDs v4 (36 caracteres)
3. Tamanho: Mínimo de 10 e máximo de 255 caracteres
4. Caracteres: Alfanuméricos, hifens e underscores apenas
5. Persistência: A mesma chave deve ser reutilizada em caso de retry da mesma operação

Comportamento da API com Chaves de Idempotência

Primeira Requisição

Quando uma requisição com uma chave de idempotência nunca vista antes é recebida:

1. A API processa a requisição normalmente
2. A resposta é armazenada associada à chave de idempotência
3. Um código de status apropriado é retornado (geralmente 200 OK ou 201 Created)

Requisições Subsequentes com a Mesma Chave

Quando uma requisição é recebida com uma chave de idempotência já utilizada:

1. A API verifica se o corpo da requisição é idêntico ao da requisição original
2. Se o corpo for idêntico, a API retorna a resposta armazenada, sem executar a operação novamente
3. Se o corpo for diferente, a API retorna um erro 422 (Unprocessable Entity) indicando conflito de idempotência

Exemplo de Resposta para Requisição Duplicada

{
  "error": {
    "status": "Conflict",
    "statusCode": 409,
    "category": "idempotency",
    "message": "Transaction Conflict",
    "details": "An operation with this idempotency key is already in progress. Please wait for completion or check the status later.",
    "idempotencyKey": "01957491-1080-7038-a505-7c08b60f9454",
    "retryAfterMinutes": 5
  }
}

Tempo de Expiração

As chaves de idempotência e suas respostas associadas são mantidas por 24 horas. Após este período, a mesma chave pode ser reutilizada e será tratada como uma nova requisição.

Implementação de Idempotência no Cliente

Geração de Chaves de Idempotência

É importante gerar chaves únicas para cada operação. Aqui estão exemplos em diferentes linguagens:

As chaves de idempotência funcionam em todos os verbos HTTP?

As chaves de idempotência são principalmente utilizadas em operações POST e PUT que modificam recursos. Elas não são necessárias para operações GET, DELETE ou HEAD, que já são naturalmente idempotentes.