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

Связь оборвалась, ответ не пришёл — создался заказ или нет? С заголовком Idempotency-Key ответ на этот вопрос не важен: повторите запрос с тем же ключом, и Orda вернёт ответ первого запроса, не выполняя его снова.

curl -s -X POST "$ORDA_API/orders" -H "X-Api-Key: $ORDA_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-РТ-00001-v1" \
  -d '{ "number": "РТ-00001", "deliveryDate": "2026-11-20", "address": "Алматы, ул. Абая, 1" }'

Правила

• Работает для любых POST, PATCH, PUT, DELETE. Ключ — 1–255 печатных ASCII-символов (UUID, номер документа с версией, номер пакета).
• Ответ хранится 24 часа. Повтор с тем же ключом и тем же телом → тот же код и тело ответа плюс заголовок Idempotent-Replayed: true.
• Тот же ключ с другим телом → 422 IDEMPOTENCY_KEY_REUSED (ключ привязан к содержимому).
• Первый запрос ещё выполняется → 409 IDEMPOTENCY_IN_PROGRESS, повторите чуть позже.
• Ошибки 4xx тоже сохраняются (повтор вернёт ту же ошибку — исправьте данные и возьмите новый ключ). Ошибки 5xx не сохраняются — можно повторить с тем же ключом.
• Ключи разделены по компаниям и по API-ключам: одинаковые строки у разных интеграций не мешают друг другу.

Как выбирать ключ

• Новый ключ — на каждое намерение (одна выгрузка пакета, одна отмена), один и тот же — на все повторы этого намерения.
• Пример: orders-bulk-2026-11-20-<номер пакета>; при изменении содержимого — новый номер пакета.
• Для пакетной загрузки заказов идемпотентность есть и без заголовка (обновление по externalId), но заголовок избавляет от лишней работы и даёт тот же ответ.