> ## Documentation Index
> Fetch the complete documentation index at: https://base39-release-notes-06-mar.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Idempotência

A idempotência é um conceito importante em sistemas distribuídos e em APIs web. Uma operação idempotente é aquela que pode ser repetida várias vezes e sempre produzirá o mesmo resultado, independentemente do número de vezes que for chamada. Isso é particularmente crucial em ambientes onde chamadas de API podem ser repetidas devido a falhas de rede, timeouts ou outros problemas.

## Quando e por que usar

* **Falhas de rede**: Quando uma requisição não recebe resposta devido a um erro de rede, a idempotência permite que a mesma seja reenviada sem o risco de duplicar a operação.
* **Prevenção de duplicações**: Em cenários onde a mesma operação pode ser enviada mais de uma vez, a idempotência evita resultados duplicados ou inconsistentes.
* **Operações seguras para retentativas**: Especificamente útil para operações que modificam dados ou estados (como `POST`, ou `PUT` em APIs web).

## Como funciona

Geralmente, a idempotência em APIs é gerenciada por meio do uso de identificadores únicos para cada requisição. Na Base39, utilizamos chaves de idempotência como identificador único.
Ao realizar uma requisição que deseja garantir a idempotência, é necessário fornecer a chave de idempotência (Idempotency-Key) no header da requisição.

<Accordion title="cURL de exemplo">
  ```bash
  curl --location 'https://api.base39.io/v1/invoices' \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'Idempotency-Key: c9b82808-b864-45eb-bc40-87b705fc41e0' \
  --header 'Authorization: Bearer 4cHD54272jaxwMW2DS6lG1j5SHJqS1NEEEEEEEEE' \
  --data '
  {
  "type": "pay_off",
  "payer": "comp_65141b68f88ebbf1ec2afb73",
  "beneficiary": "fund_65141b68f88ebbf1ec2afb73",
  "dueDate": "2024-10-10"
  }
  '
  ```
</Accordion>

## Melhores práticas

* **Geração de chaves únicas**: As chaves de idempotência (Idempotency-Key) devem ser únicas. Recomendamos o uso de UUIDs, ou métodos similares para garantir a unicidade.
  <Note> A geração e o gerenciamento das chaves de idempotência são responsabilidades dos nossos clientes e não da Base39.</Note>
* **Validade temporal**: Para melhor gerenciamento, as chaves de idempotência possuem um período de validade (24h), após o qual uma nova operação com a mesma chave será tratada como distinta.

### Limitações e considerações

* **Operações não-aplicáveis**: Nem todas as operações necessitam de idempotência. Geralmente, requisições `GET`, que são naturalmente idempotentes, não precisam de idempotência.

## Comportamentos esperados e possíveis cenários

### Reenviar uma operação bem-sucedida

Suponhamos que você não tem certeza se sua primeira requisição foi bem-sucedida devido a problemas de rede e decide reenviá-la em um intervalo de 24 horas com a mesma chave de idempotência. Nesse caso, o serviço reconhece de forma inteligente que a operação anterior com essa chave já foi concluída com sucesso e simplesmente retorna o resultado daquela primeira operação bem-sucedida. Não há risco de duplicação.

### Retentativa após uma falha

Se a sua primeira tentativa falhou e você decide tentar novamente com a mesma chave, o serviço permite essa nova tentativa. A resposta desta tentativa refletirá o sucesso ou falha desta nova operação, como se fosse a primeira vez.

### Operação em andamento

Digamos que você reenvie uma requisição com a mesma chave enquanto a primeira ainda está sendo processada. Neste caso, para evitar conflitos e duplicações, o serviço de idempotência retorna um erro específico, o erro HTTP 409 (Conflito). Isso indica que uma operação com essa chave já está em andamento, e você deve aguardar a sua conclusão antes de tentar novamente.

### Utilizar a mesma chave após um longo intervalo

Se após um longo intervalo (por exemplo, mais de 24 horas) você usar a mesma chave novamente, o serviço tratará isso como uma nova operação, pois a chave anterior já expirou.
<Warning>A idempotência só funciona se a chave de idempotência (Idempotency-Key) for incluida na requisição.</Warning>

## Endpoints disponíveis

A grande maioria dos nossos endpoints do tipo `POST` e `PUT`estão disponíveis para o uso de idempotência.
Para certificar-se se o endpoint que você precisa está disponível, consulte a [documentação](https://docs.base39.com.br/development/api-reference/endpoint/get-v1-loans-loan) do mesmo e confira no header se a funcionalidade está disponível.
Confira abaixo uma lista de endpoints que, no contexto de crédito consignado, podem interessantes de garantir a idempotência:

* [Criar intenção de pagamento](https://docs.base39.com.br/development/api-reference/endpoint/post-v1-payment-intents)
* [Criar item da fatura](https://docs.base39.com.br/development/api-reference/endpoint/post-v1-invoice-items)
* [Criar parcela](https://docs.base39.com.br/development/api-reference/endpoint/post-v1-loans-loan-installments)
* [Desembolsar empréstimo](https://docs.base39.com.br/development/api-reference/endpoint/post-v1-loans-disburse)