> For the complete documentation index, see [llms.txt](https://docs.giro.tech/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/idempotencia.md).

# Idempotência

Com o header `Idempotency-Key`, você pode reenviar um `POST` da API Originator após timeout, falha de rede ou dúvida sobre o resultado, sem duplicar a operação.

***

## Como funciona

Envie `Idempotency-Key` com um valor único por operação:

1. **Primeira requisição** com a chave: processada normalmente, e a resposta (status, body, content-type) é guardada.
2. **Mesma chave, requisição original concluída**: retorna a **mesma resposta** guardada, sem reprocessar, com o header `Idempotency-Replayed: true`.
3. **Mesma chave, requisição original em andamento**: `409 Conflict`.

```
Originador                              GTPayroll
    │                                       │
    │── POST /simulations ──────────────────>│
    │   Idempotency-Key: abc-123            │
    │                                       │  (processa e armazena resposta)
    │<───────── 201 Created ────────────────│
    │                                       │
    │── POST /simulations ──────────────────>│  (mesma chave)
    │   Idempotency-Key: abc-123            │
    │                                       │  (detecta duplicata, repete resposta)
    │<───────── 201 Created ────────────────│
    │           Idempotency-Replayed: true  │
```

***

## Header

| Header            | Tipo     | Obrigatório | Descrição                                        |
| ----------------- | -------- | ----------- | ------------------------------------------------ |
| `Idempotency-Key` | `string` | Não         | Chave única por operação. Máximo 255 caracteres. |

Sem o header, a requisição é processada sem controle de idempotência.

***

## Escopo e validade

* A chave vale **por originador**, e **não** por endpoint: a mesma chave reutilizada em outra rota é tratada como duplicata e devolve a resposta guardada da **primeira** rota, sem processar a nova requisição. Gere uma chave nova para cada requisição.
* A resposta é guardada com **qualquer status**, inclusive erro (`4xx`/`5xx`). Reenviar com a mesma chave repete o mesmo erro; para tentar de novo depois de um erro, use uma chave nova.
* A chave é retida por **7 dias**. Depois disso, uma requisição com a mesma chave é tratada como nova.

***

## Endpoints suportados

Todas as requisições `POST` da API Originator (`/api/v1/originator/*`). Uso recomendado principalmente em:

| Endpoint                                                         | Descrição       |
| ---------------------------------------------------------------- | --------------- |
| `POST /api/v1/originator/employees/{publicId}/simulations`       | Criar simulação |
| `POST /api/v1/originator/employees/{publicId}/proposals`         | Criar proposta  |
| `POST /api/v1/originator/proposals/{proposalPublicId}/contracts` | Criar contrato  |
| `POST /api/v1/originator/employees`                              | Criar employee  |

***

## Respostas

| Cenário                      | HTTP Status                  | Header adicional             | Body                                                                                    |
| ---------------------------- | ---------------------------- | ---------------------------- | --------------------------------------------------------------------------------------- |
| Primeira requisição          | Status original (ex.: `201`) | —                            | Resposta original                                                                       |
| Duplicata (já concluída)     | Status original (ex.: `201`) | `Idempotency-Replayed: true` | Resposta armazenada (idêntica)                                                          |
| Duplicata (em processamento) | `409 Conflict`               | —                            | `A request with this idempotency key is currently being processed. Please retry later.` |

***

## Boas práticas

1. **Use uma chave nova por requisição** — um UUID (v4) gerado no cliente antes do envio. Não reutilize chaves entre operações nem entre endpoints diferentes.

```
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
```

2. **Em timeout ou erro de rede, reenvie com a mesma chave.** Se a original foi processada, você recebe a resposta guardada. Se a resposta recebida foi um erro (ex.: `429`, `503`), a mesma chave vai repeti-lo: reenvie com uma chave nova.
3. **No `409`, aguarde alguns segundos e reenvie**: a original ainda está em processamento.

***

## Exemplo

### Requisição

```http
POST /api/v1/originator/employees/{publicId}/simulations HTTP/1.1
Host: api.giro.tech
Authorization: Bearer {token}
Content-Type: application/json
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

{
  "loanAmount": 5000.00,
  "installmentCount": 12,
  "monthlyInterestRate": 4.0,
  "loanDate": "2026-10-01"
}
```

### Primeira resposta

```http
HTTP/1.1 201 Created
Content-Type: application/json

{
  "publicId": "sim_abc123",
  ...
}
```

### Resposta de replay (mesma chave reenviada)

```http
HTTP/1.1 201 Created
Content-Type: application/json
Idempotency-Replayed: true

{
  "publicId": "sim_abc123",
  ...
}
```
