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

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

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

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

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

curl -X POST "https://app.coverse.team/api/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]]}'

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

Что важно знать​

  • Ключ хранится 24 часа. После этого запрос с тем же ключом выполнится заново.
  • Ключ действует в пределах пользователя: один и тот же ключ в разных токенах одного пользователя считается одним ключом.
  • Длина ключа — до 255 символов, иначе вернётся 422.
  • Повторный ответ помечен заголовком Idempotency-Replayed: true.
  • Сохраняется любой завершённый ответ, включая ошибки 4xx: повтор с тем же ключом вернёт ту же ошибку. Ответы 5xx не сохраняются — такой запрос можно повторять тем же ключом.
  • Если запрос с тем же ключом ещё выполняется, параллельный повтор получит 409.
  • Тело запроса не сравнивается: тот же ключ с другими данными вернёт прежний ответ, новые данные записаны не будут. Не используйте один ключ для разных операций.

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

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

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

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

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