Интеграция

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

Как повторять покупку после сетевой ошибки и не создавать лишние заказы.

REST API v12 мин чтения

Одна операция — один ключ

POST /orders требует заголовок Idempotency-Key: 16–80 символов из A–Z, a–z, 0–9, _ и -. UUID подходит. Ключ уникален в пределах аккаунта и не меняется при перевыпуске API-ключа.

Запишите ключ и точные параметры service, country, maxPrice в свою БД до отправки запроса. После сбоя процесса восстановите их из БД. Не генерируйте UUID внутри функции, которая автоматически повторяется.

Матрица решений

Матрица решений
РезультатДействие
200 + orderСохраните заказ. Не отправляйте новую покупку.
Таймаут / сеть / 5xxРезультат неизвестен. История → повтор с тем же ключом и телом.
409 + pending: trueОперация не завершена. Новый ключ запрещён для обхода ожидания.
409, другие параметрыВосстановите исходное тело. Не меняйте maxPrice при повторе.
Окончательный отказУстраните причину. Только новая намеренная покупка получает новый ключ.

Пример сохранённой операции

purchase-operation.json · example
{
  "idempotencyKey": "550e8400-e29b-41d4-a716-446655440000",
  "body": { "service": "tg", "country": 0, "maxPrice": 50 },
  "state": "created",
  "orderId": null
}

Восстановление после неопределённого результата

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

Не нашли ответ на свой вопрос?Помощь с интеграцией