Перейти к основному содержимому

Идемпотентность

Идемпотентность позволяет безопасно повторять запись: если запрос не дошёл или ответ потерялся из-за сбоя сети, можно повторить его тем же ключом, не боясь записать данные дважды.

Как это работает​

Передайте в запросе на запись заголовок Idempotency-Key с уникальным значением (например, UUID):

curl -X POST "https://app.coverse.team/v1/documents/$DOCUMENT_ID/values/append" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9a1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e" \
  -d '{"range":"A1","values":[["Заявка",1500]]}'

Если запрос с этим ключом уже был выполнен, сервер вернёт исходный результат и не станет записывать данные повторно.

Где применяется​

Заголовок поддерживают операции записи:

  • PUT /v1/documents/{document}/values/{range}
  • POST .../values/batchUpdate
  • POST .../values/append
  • POST .../values/clear
  • POST .../documents/{document}/sheets (создание листа)

Рекомендации​

  • Генерируйте новый ключ на каждую логическую операцию (например, на каждую заявку из бота).
  • При повторе после сбоя используйте тот же ключ, что и в исходной попытке.
  • Ключ должен быть уникальным и труднопредсказуемым — подойдёт UUID.