Idempotencia

Envía Idempotency-Key en las creaciones. Así un reintento devuelve la respuesta original en vez de crear un segundo registro.

Cómo funciona

Elige cualquier cadena única por operación lógica — un UUID sirve — y envíala en la cabecera Idempotency-Key. Guardamos la respuesta completa (estado y cuerpo) durante 24 horas bajo esa clave, en el ámbito de tu workspace.

bash

curl -X POST https://api.zapyflow.com.br/api/orders \
  -H "Authorization: Bearer $ZAPYFLOW_API_KEY" \
  -H "Idempotency-Key: 8f14e45f-ea38-4f1b-9b0e-2c2a1b7e5d31" \
  -H "Content-Type: application/json" \
  -d '{"aiAgentId":"...","clientName":"Ana","clientPhone":"11987654321",
       "items":[{"name":"Corte","quantity":1,"price":60}],"total":60}'

Una repetición vuelve con la cabecera Idempotent-Replayed: true y el cuerpo exacto del primer intento.

La idea no es “ignorar la segunda llamada”. Es que un cliente que perdió la respuesta por un timeout pueda preguntar de nuevo y recuperar el resultado original — el id del registro que de verdad se creó.

Dos conflictos, y por qué son errores

Situación	Respuesta
Misma clave, cuerpo distinto	`409 IDEMPOTENCY_KEY_REUSED`. Repetir la respuesta antigua en silencio escondería un fallo real del cliente hasta convertirse en datos incorrectos.
Misma clave mientras la primera sigue en curso	`409 IDEMPOTENCY_IN_PROGRESS`. Reintenta con la misma clave en un momento — no `202`, porque no se te ha dado un resultado con el que seguir.

Dónde aplica

Enviar la cabecera en cualquier otro endpoint es inofensivo y no hace nada.

Endpoint	Ámbito
`POST /api/appointments`	`appointments.write`
`POST /api/contacts/import`	`contacts.import`
`POST /api/conversations/{id}/messages`	`conversations.write`
`POST /api/conversations/new`	`conversations.write`
`POST /api/crm/cards`	`crm.cards.write`
`POST /api/knowledge-bases`	`knowledge.write`
`POST /api/leads`	`leads.write`
`POST /api/marketing-campaigns`	`campaigns.write`
`POST /api/orders`	`orders.write`

Una excepción deliberada

POST /api/settings/api-keys no admite repetición idempotente, y nunca lo hará. Repetir esa respuesta significaría guardar el secreto de la clave en algún sitio durante 24 horas, y todo el diseño se apoya en que el secreto exista exactamente una vez. Crear una clave de más por accidente es barato de deshacer; guardar secretos no lo es.

Un fallo libera la clave

Un 5xx libera la reserva al instante, así que puedes reintentar con la misma clave. Sin eso, un error pasajero bloquearía esa clave durante 24 horas.