Idempotência

Mande Idempotency-Key nas criações. Aí uma retentativa devolve a resposta original em vez de criar um segundo registro.

Como funciona

Escolha qualquer string única por operação lógica — um UUID serve — e mande no cabeçalho Idempotency-Key. Guardamos a resposta completa (status e corpo) por 24 horas sob essa chave, no escopo do seu 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}'

Um replay volta com o cabeçalho Idempotent-Replayed: true e o corpo exato da primeira tentativa.

O ponto não é “ignorar a segunda chamada”. É que um cliente que perdeu a resposta num timeout pode perguntar de novo e recuperar o resultado original — o id do registro que de fato foi criado.

Dois conflitos, e por que são erros

Situação	Resposta
Mesma chave, corpo diferente	`409 IDEMPOTENCY_KEY_REUSED`. Repetir a resposta antiga em silêncio esconderia um defeito real do cliente até ele virar dado errado.
Mesma chave enquanto a primeira ainda roda	`409 IDEMPOTENCY_IN_PROGRESS`. Retente com a mesma chave daqui a pouco — não `202`, porque você não recebeu resultado nenhum para seguir em frente.

Onde vale

Mandar o cabeçalho em qualquer outro endpoint é inofensivo e não faz nada.

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

Uma exceção deliberada

POST /api/settings/api-keys não tem replay idempotente, e nunca vai ter. Repetir aquela resposta significaria guardar o segredo da chave em algum lugar por 24 horas, e o desenho inteiro se apoia no segredo existir exatamente uma vez. Criar uma chave sobrando por acidente é barato de desfazer; guardar segredo não é.

Falha libera a chave

Um 5xx libera a reserva na hora, então você pode retentar com a mesma chave. Sem isso, um erro passageiro travaria aquela chave por 24 horas.