Chave de idempotência (Idempotency-key)
O mecanismo de chave de idempotência visa garantir que uma operação seja executada uma única vez, independente da quantidade de requisições realizadas dentro de um período de tempo específico.
Quando esse tempo houver expirado, qualquer requisição que utilize a mesma chave resultará em uma nova execução.
Nota
O período de duração da chave de idempotência poderá variar. Para conhecer o tempo de expiração dos endpoints que fazem uso da chave de idempotência, verifique a documentação específica de cada endpoint.
Chave de idempotência no Bankly
Alguns endpoints do Bankly utilizam a chave de idempotência para prevenir a ocorrência de requisições duplicadas.
Por exemplo, a API de criação de contas possibilita que uma mesma pessoa, física ou jurídica, crie mais de uma conta (Multicontas).
Portanto, um parceiro poderia, acidentalmente, enviar mais de uma requisição para um documento sem a intenção de criar uma conta extra e, mesmo assim, criá-la. O uso da chave de idempotência previne esse tipo de erro.
Funcionamento
A chave de idempotência deve ser enviada por meio do cabeçalho adicional Idempotency-key nas requisições dos endpoints que utilizam esse mecanismo.
Atualmente as APIs do Bankly aceitam como chave de idempotência uma string no formato UUID v4 com 128 bits.
Nota
Cabe ao parceiro Bankly a geração e garantia de unicidade da chave.
O Bankly armazena as requisições (request e response) de sucesso (status code 2XX) que utilizam a chave de idempotência. Desse modo, ao reutilizar a mesma chave para uma nova requisição dentro de um período válido, o resultado retornado será idêntico ao da primeira requisição.
Caso seja realizada uma requisição com uma chave de idempotência ainda ativa, porém com qualquer informação divergente da primeira requisição, as APIs poderão retornar o erro 400 - REQUEST_ERROR.
Nota
As informações divergentes podem variar de acordo com cada API, podendo ser o corpo, cabeçalho ou quaisquer outros parâmetros da requisição.
Endpoints
Confira a seguir os endpoints que utilizam a chave de idempotência (Idempotency-key) em seu header:
| Descrição | Endpoint | Contexto | Obrigatório |
|---|---|---|---|
| Criação de conta para pessoa física | POST /customers/{documentNumber}/accounts | Account | Somente para parceiros que utilizam a funcionalidade de Multicontas. |
| Criação de conta para pessoa jurídica | POST /business/{documentNumber}/accounts | Account | Somente para parceiros que utilizam a funcionalidade de Multicontas. |
| Criação de conta pocket | POST /accounts/{accountNumber}/pockets | Sim | |
| Depósito em uma conta pocket | POST /pockets/{pocketNumber}/transactions/savings | Sim | |
| Resgate de um valor da conta pocket | POST /pockets/{pocketNumber}/transactions/redeems | Sim | |
| Transferência via TED | POST /fund-transfers | TED | Não |
Erros
Na utilização da chave de idempotência, poderão ocorrer os seguintes erros:
| Status code | Código | Mensagem | Descrição |
|---|---|---|---|
| 400 | IDEMPOTENCY_KEY_NOT_FOUND | Idempotency-key header not found in request. | A requisição não apresenta o Idempotency-key em seu header. Esse erro é retornado apenas em endpoints para os quais a chave de idempotência é obrigatória. |
| 400 | INVALID_IDEMPOTENCY_KEY | Idempotency-key header is not a valid guid. | O header Idempotency-key precisa ser enviado no formato Uuid/Guid. |
| 400 | REQUEST_ERROR | Hash code is different from the one persisted with the same idempotency key and companykey. | O valor do header Idempotency-key já foi utilizado em outra requisição. A requisição atual apresenta alguma divergência em relação aos parâmetros fornecidos na primeira requisição. |
Updated 5 months ago