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

# Idempotência

> Como reenviar uma chamada sem repetir a ação.

A chave de idempotência evita repetir uma ação quando você reenvia a mesma chamada. Todo `POST` que muda um protocolo exige o cabeçalho `Idempotency-Key`:

* `POST /protocols`
* `POST /protocols/{protocol_id}/appointment`
* `POST /protocols/{protocol_id}/cancel`

Sem o cabeçalho, a API responde `400 idempotency_key_required`.

## Como gerar a chave

Gere uma chave nova para cada ação, como `pedido-12345-criar-1`. Use de 1 a 128 caracteres entre letras, números e `. _ : -`. Não inclua dados pessoais.

A chave não expira. Reenviar a mesma chave com o mesmo corpo sempre devolve o resultado da primeira chamada.

A chave vale por ação:

* `POST /protocols`: a chave é única para o parceiro. Uma chave que já criou um protocolo só serve para reenviar essa mesma criação.
* Agendar e cancelar: a chave vale dentro do protocolo e da ação. Mesmo assim, use uma chave diferente para cada ação, como `pedido-12345-agendar-1` e `pedido-12345-cancelar-1`.
* Reagendar ou tentar outro horário é uma nova ação. Use uma chave nova, como `pedido-12345-agendar-2`.

## Quando reenviar e quando usar outra chave

| Situação | O que fazer |
| - | - |
| A chamada excedeu o tempo limite ou teve um erro de rede. | Reenvie com a mesma chave e o mesmo corpo. |
| O erro traz `retryable: true`. | Siga a orientação de `code` e aguarde `Retry-After`, quando informado. Ao repetir, mantenha a chave e o corpo. |
| A resposta é um erro `4xx` com `retryable: false`, como `validation_error`. | Corrija a chamada e mantenha a chave. A API não registra uma chamada rejeitada com `4xx`. Se a chave já tiver sido usada com outro corpo, a API responde `409 idempotency_conflict`. |
| `POST /protocols` respondeu `422 holder_email_in_use` ou `400 validation_error` no e-mail. | O protocolo não foi aceito. Troque o e-mail e reenvie com a mesma chave e o mesmo `external_id`. |
| A resposta traz `error` no protocolo, como `provider_unavailable`. | A ação terminou com falha. Para tentar de novo, use uma nova chave. |
| O protocolo ficou em `creation_failed`, por exemplo com `error.reason` igual a `holder_email_in_use`. | A criação foi aceita e depois falhou. Crie outro protocolo com uma nova chave e outro `external_id`: os anteriores continuam em uso. |
| O resultado esperado ainda não aparece e não há `error` no protocolo. | Consulte o protocolo de novo. Não repita a ação com uma nova chave. Veja o [Ciclo de vida](https://docs.certificados.zapsign.com.br/ciclo-de-vida-do-protocolo.md). |
| Você quer fazer outra ação, ou mudar o corpo. | Use uma nova chave. |

## Reenvio idempotente

Ao reenviar com a mesma chave e o mesmo corpo, a API devolve o protocolo no estado atual. Ela não repete a ação nem desconta o saldo de novo. O cabeçalho `Idempotent-Replayed: true` indica que a API reconheceu uma chamada já enviada.

* `POST /protocols` responde `202`. O `Retry-After` só vale enquanto o `status` for `creating`.
* Agendar e cancelar respondem `200`.

O exemplo repete o agendamento do [Início rápido](https://docs.certificados.zapsign.com.br/quickstart.md) com o mesmo protocolo, a mesma chave e o mesmo corpo. Por isso a API não responde `409`. O exemplo usa um horário fixo: troque `date` e `time` por um horário que `GET /appointment-slots` devolver.

```bash theme={"system"}
curl -i -X POST https://certificados.zapsign.com.br/api/v2/partners/protocols/CPR_01K7Q3ZB8M4N6P2R5T9V1W3X5Y/appointment \
  -H "Authorization: Bearer czk_live_SUA_CHAVE" \
  -H "Idempotency-Key: pedido-12345-agendar-1" \
  -H "Content-Type: application/json" \
  -d '{ "date": "2026-10-22", "time": "10:00" }'
```

Resposta (resumida): o status e o cabeçalho. O corpo é o protocolo no estado atual.

```http theme={"system"}
HTTP/1.1 200 OK
Idempotent-Replayed: true
```

## Mesma chave, corpo diferente

Usar a mesma chave com dados diferentes responde `409 idempotency_conflict`. Para fazer a nova ação, troque a chave. Para repetir a ação original, reenvie o corpo original.

```json theme={"system"}
{
  "code": "idempotency_conflict",
  "message": "Esta Idempotency-Key já foi usada com outro corpo. Use uma nova chave.",
  "retryable": false,
  "status": 409,
  "type": "https://docs.certificados.zapsign.com.br/erros/idempotency_conflict",
  "request_id": "01K7Q4A1B2C3D4E5F6G7H8J9KM"
}
```


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