Idempotência

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.
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 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.

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/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.

{
  "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"
}

Começar

Conceitos

Como gerar a chave

Quando reenviar e quando usar outra chave

Reenvio idempotente

Mesma chave, corpo diferente

​Como gerar a chave

​Quando reenviar e quando usar outra chave

​Reenvio idempotente

​Mesma chave, corpo diferente

Como gerar a chave

Quando reenviar e quando usar outra chave

Reenvio idempotente

Mesma chave, corpo diferente