К содержанию
CheckcraftСкачать
Практический сценарий

Идемпотентность HTTP-запросов: как проверить, что повторный запрос не создаёт второй заказ

Checkcraft — программа для проверки API и логов без кода, есть бесплатная версия. Скачать без регистрации →

Платёжная песочница присылает уведомление дважды, клиент жмёт «Оплатить» второй раз, сеть рвётся и запрос повторяется. Если API не идемпотентен, появляется второй платёж или второй заказ. Разберём, что это значит и как это проверить.

Checkcraft ·

Поможем с первой проверкой →

Что такое идемпотентность

Запрос идемпотентен, если повторить его несколько раз — то же самое, что выполнить один раз: результат на сервере не меняется. По RFC 9110 идемпотентны PUT, DELETE и безопасные методы GET, HEAD, OPTIONS, TRACE. POST и PATCH по определению не идемпотентны, поэтому для создания платежей и заказов API добавляют ключ идемпотентности.

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

Клиент передаёт в заголовке уникальное значение для операции. Например, в ЮKassa это заголовок Idempotence-Key: значение уникально для операции на стороне магазина. Получив запрос с уже известным ключом, сервер возвращает результат первой операции, а не выполняет её заново.

Как проверить

Отправьте один и тот же запрос дважды с одним ключом и сравните ответы: идентификатор платежа должен совпасть. Затем проверьте последствия, а не только ответ: в базе одна запись, в логах по traceId одно событие «создан». Новый ключ должен давать новую операцию. Отдельно проверьте запрос без ключа и повтор с тем же ключом, но другим телом — что делает ваш API, решают требования.

# 1. Тот же запрос дважды с одним ключом
POST /payments   Idempotence-Key: 7f3a…   → 200, payment_id = P1
POST /payments   Idempotence-Key: 7f3a…   → 200, payment_id = P1  (тот же!)

# 2. Проверить последствия, а не только ответ
SELECT count(*) FROM payments WHERE order_id = 5001;   -- ожидаем 1
в логах по traceId — одна запись «payment created», а не две

# 3. Новый ключ — новая операция
POST /payments   Idempotence-Key: 9b1c…   → новый payment_id

Почему одного ответа мало

Оба ответа могут прийти со статусом 200 и одинаковыми полями, а в базе окажется две строки. Поэтому повторный запрос проверяют по трём источникам: ответ, лог по traceId и запись в базе. В Checkcraft это одна проверка: запрос, поиск записей в Kibana по traceId и SELECT в базе (база — в Pro).

Следующий шаг

Повторите это на своём API

Checkcraft — настольная программа: сохраняет проверки ответа API без кода и показывает, что не совпало. Начните с учебного примера, затем подставьте свои обезличенные данные. Free работает на Windows и Linux без ограничения срока.

Скачать FreeКак получить и запустить приложение

Скачивание без регистрации и почты, архив готов за пару минут. Состав бесплатной версии опубликован на странице тарифов.

Документация

RFC 9110: идемпотентные методы · ЮKassa: формат взаимодействия и Idempotence-Key

Начните с примера по ссылкам и сопоставьте результат с требованием своей проверки.

Можно спросить человека

Поможем с первой проверкой

Расскажите, что хотите проверить или на каком шаге остановились. Поможем запустить Checkcraft, подобрать пример и разобраться с первым прогоном. Можно написать до скачивания.

Telegram-группа открытая: не публикуйте пароли, токены и конфиденциальные рабочие данные. Для первого вопроса достаточно описания задачи.

Можно написать напрямую support@checkcraft.ru

Без регистрации. Ответим по email. Это обращение в поддержку, а не подписка на рассылку.