Ключ идемпотентности

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

#Как это работает в CryptoLike

API CryptoLike принимает заголовок Idempotency-Key на каждом POST: до 128 печатных ASCII-символов (от ! до ~), например номер вашего заказа. Пустой заголовок или заголовок из одних пробелов считается отсутствующим; более длинный ключ или другие символы дают 400 validation_error с полем Idempotency-Key. Повторный запрос с тем же ключом возвращает исходный ответ с заголовком Idempotent-Replayed: true, и ничего не создаётся дважды. Ключи хранятся 24 часа для каждого API-ключа, поэтому повтор в пределах этого срока не создаст второй платёж или вторую выплату.

Повтор должен быть тем же запросом — тот же метод, путь и тело. Другое тело с тем же ключом даёт 422 idempotency.mismatch: одна логическая операция — один ключ. Если первый запрос ещё выполняется, ответ — 409 idempotency.in_progress: подождите и повторите. Сохраняются только ответы с кодом ниже 400; ошибка освобождает ключ, и исправленный запрос выполнится заново. После 504 timeout повторяйте с тем же ключом. Официальные SDK добавляют заголовок к каждому POST сами.

Ещё две защиты работают без заголовка. В POST /v1/invoices флаг idempotency_by_order_id: true возвращает открытый платёж того же order_id вместо создания второго. В POST /v1/withdrawals ваш payout_id с той же монетой, суммой и адресом возвращает уже созданную выплату, а другие параметры дают 409 — повтор с тем же payout_id не заплатит дважды. На принимающей стороне вебхук отсеивает повторы по event_id.

#Пример

Запрос платежа CryptoLike с ключом идемпотентности: если соединение оборвалось до ответа, отправьте тот же запрос ещё раз — с тем же ключом и телом, но с новой подписью и меткой времени не раньше следующей секунды — и получите тот же платёж. $KEY_ID, $TS и $SIG — значения подписи из руководства по аутентификации API, тело запроса должно совпадать байт в байт:

curl -s https://api.cryptolike.net/v1/invoices \
  -H "Content-Type: application/json" -H "Idempotency-Key: order-A-1001" \
  -H "X-API-Key: $KEY_ID" -H "X-Timestamp: $TS" -H "X-Signature: $SIG" \
  -d '{"amount":"10.50","currency":"USD","order_id":"A-1001"}'