Idempotency-Key

Что такое Idempotency-Key

Idempotency-Key — это header, который помогает безопасно повторять запрос создания счёта.

Если backend продавца отправил запрос, но не получил ответ из-за timeout, сетевой ошибки или сбоя соединения, он может повторить тот же запрос с тем же Idempotency-Key.

В таком случае Weelay вернёт уже созданный счёт вместо создания дубля.

Зачем это нужно

Без защиты от дублей одна и та же операция может создать несколько счетов для одного заказа.

Это плохо для продавца и покупателя:

• покупатель может увидеть несколько ссылок на оплату;
• заказ может получить несколько разных счетов;
• поддержке сложнее разбирать спор;
• backend продавца может сохранить не тот счёт.

Idempotency-Key снижает этот риск.

Где используется

На текущем этапе Idempotency-Key используется при создании счёта:

POST /merchant/invoices

Header:

Idempotency-Key: order-1001

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

Лучше всего использовать стабильный ключ, связанный с конкретной операцией создания счёта.

Хорошие варианты:

• id заказа продавца;
• номер заказа с префиксом;
• уникальный id платежной попытки;
• UUID, сохранённый у продавца до отправки запроса.

Примеры:

• order-1001;
• shop-42-order-1001;
• invoice-create-550e8400-e29b-41d4-a716-446655440000.

Главное правило

Один Idempotency-Key должен соответствовать одной операции создания счёта.

Не используйте один и тот же ключ для разных заказов.

Не меняйте ключ при повторе того же запроса после timeout.

Правильный сценарий

Правильный порядок такой:

1. Продавец создаёт заказ у себя.
2. Продавец генерирует или выбирает Idempotency-Key.
3. Продавец сохраняет этот ключ у себя.
4. Продавец отправляет POST /merchant/invoices.
5. Если ответ получен, продавец сохраняет invoice id и payment_url.
6. Если ответ не получен из-за сбоя, продавец повторяет запрос с тем же Idempotency-Key.

Так повторный запрос безопасно вернёт уже созданный счёт.

Неправильный сценарий

Неправильно генерировать новый Idempotency-Key при каждом повторе одного и того же создания счёта.

В таком случае Weelay будет считать запрос новой операцией и может создать новый счёт.

Неправильно использовать один общий ключ для всех заказов, например payment, invoice или test.

Такой ключ не показывает, к какому заказу относится операция.

Что возвращает повторный запрос

Если счёт уже создан с таким Idempotency-Key, повторный запрос возвращает существующий счёт.

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

Главные поля для сохранения:

• id;
• order_id;
• status;
• payment_url;
• payment_expires_at.

Связь с order_id

order_id и Idempotency-Key решают разные задачи.

order_id помогает продавцу связать счёт с заказом.

Idempotency-Key помогает Weelay понять, что повторный запрос относится к той же операции создания счёта.

На практике можно использовать одинаковое значение, например ORDER-1001, но смысл у полей разный.

Можно ли не использовать Idempotency-Key

Технически создание счёта может работать и без Idempotency-Key.

Но для production-интеграции лучше использовать его всегда.

Это особенно важно, если backend продавца автоматически повторяет запросы после timeout или сетевой ошибки.

Что делать при ошибке сети

Если backend продавца отправил запрос создания счёта и не получил ответ, не нужно сразу создавать новый заказ или новый ключ.

Правильнее повторить тот же запрос с тем же Idempotency-Key.

Если повторный запрос успешен, используйте возвращённый счёт.

Что делать при ошибке validation

Если API вернул VALIDATION_ERROR, сначала исправьте данные запроса.

Если это всё ещё та же операция создания счёта для того же заказа, можно оставить тот же Idempotency-Key.

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

Безопасность

Idempotency-Key не является secret key.

Но его всё равно не стоит делать бессмысленным или общим для всех заказов.

Хороший ключ должен быть уникальным для операции и удобным для поиска в логах продавца.

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

Для production:

• используйте Idempotency-Key при каждом создании счёта;
• сохраняйте ключ у себя до отправки запроса;
• повторяйте запрос с тем же ключом при timeout;
• не используйте один ключ для разных заказов;
• не генерируйте новый ключ при повторе той же операции;
• сохраняйте invoice id и payment_url после успешного ответа.

Итог

Idempotency-Key защищает создание счетов от дублей.

Один заказ или одна операция создания счёта — один стабильный ключ.

При повторе после сбоя используйте тот же ключ.