Idempotency

Send Idempotency-Key on creations. A retry then returns the original response instead of creating a second record.

How it works

Pick any unique string per logical operation — a UUID is fine — and send it as the Idempotency-Key header. We store the complete response (status and body) for 24 hours under that key, scoped to your 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}'

A replay comes back with the header Idempotent-Replayed: true and the exact body of the first attempt.

The point is not “ignore the second call”. It is that a client that lost the response to a timeout can ask again and recover the original result — the id of the record that was actually created.

Two conflicts, and why they are errors

Situation	Response
Same key, different body	`409 IDEMPOTENCY_KEY_REUSED`. Silently replaying the old response would hide a real client bug until it became wrong data.
Same key while the first is still running	`409 IDEMPOTENCY_IN_PROGRESS`. Retry with the same key in a moment — not `202`, because you have not been given a result to move on with.

Where it applies

Sending the header on any other endpoint is harmless and does nothing.

Endpoint	Scope
`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`

One deliberate exception

POST /api/settings/api-keys does notsupport idempotency replay, and it never will. Replaying that response would mean storing the key's secret somewhere for 24 hours, and the entire design rests on the secret existing exactly once. Creating a spare key by accident is cheap to undo; storing secrets is not.

Failures release the key

A 5xx releases the reservation immediately, so you can retry with the same key. Without that, one transient error would lock that key for 24 hours.