> ## Documentation Index
> Fetch the complete documentation index at: https://docs-koolisys.eixoassistencia.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Idempotência

> Por que toda criação exige uma chave, e o que acontece ao repetir a chamada.

Timeout de rede acontece. Quando acontece no meio de um `POST /v1/attendances`, o integrador não
sabe se o atendimento foi criado ou não — e a resposta errada para essa dúvida é tentar de novo sem
proteção, arriscando abrir dois atendimentos para o mesmo caso.

`POST /v1/attendances` é o único endpoint de criação da API pública, e é o único que exige o
cabeçalho `Idempotency-Key`.

## Como usar

Gere um identificador único para cada **tentativa lógica** de abertura de atendimento — um UUID
serve bem — e envie no cabeçalho `Idempotency-Key`:

```bash theme={null}
curl --request POST https://api-koolisys.eixoassistencia.com.br/v1/attendances \
  --header "Authorization: Bearer <token>" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: 6f1c2e3a-9b4d-4a1e-8c3f-2d1e0a9b8c7d" \
  --data '{
    "attendanceTypeId": 7,
    "customerDocument": "12345678900",
    "vehiclePlate": "ABC1D23",
    "origin": {
      "addressLine": "Av. Paulista, 1000",
      "city": "São Paulo",
      "state": "SP",
      "latitude": -23.561414,
      "longitude": -46.655881
    }
  }'
```

A mesma chave é reaproveitada **só** quando a chamada anterior falhou de um jeito que deixa dúvida
sobre o resultado (timeout, erro de conexão, `5xx`). Uma nova tentativa lógica — outro atendimento,
outro cliente — sempre usa uma chave nova.

## O que acontece ao repetir

A chave de idempotência é única por contratante (duas contratantes podem usar o mesmo valor sem
conflito). Repetir a chamada com **a mesma chave e o mesmo corpo**:

* Não cria um segundo atendimento.
* Devolve `200` (em vez do `201` da criação original) com o mesmo atendimento já criado.
* É seguro repetir quantas vezes precisar — inclusive em paralelo, uma corrida entre duas
  requisições simultâneas com a mesma chave sempre resolve para um único atendimento.

Repetir a mesma chave com um **corpo diferente** é tratado como um erro do integrador, não como uma
segunda tentativa: a API devolve `409 IDEMPOTENCY_CONFLICT` e não altera nada. Isso normalmente
significa que a chave foi reaproveitada por engano entre duas tentativas lógicas diferentes — gere
uma chave nova para o novo atendimento.

## O que a chave não faz

A chave de idempotência não substitui a checagem de elegibilidade nem valida o corpo da requisição
— ela só decide se uma tentativa de criação é uma repetição ou uma tentativa nova. Uma chamada
inválida (documento inexistente, cliente sem cobertura) continua devolvendo o erro correspondente
mesmo com uma chave de idempotência válida, e essa chave só passa a "significar" alguma coisa depois
que um atendimento é de fato criado com sucesso.

## Retenção

A chave fica associada ao atendimento enquanto ele existir — não há uma janela de expiração curta
depois da qual o mesmo valor passa a criar um atendimento novo. Trate cada chave como
permanentemente ligada à tentativa que ela representa, e nunca a reutilize para outra coisa.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.