Разработка
Идемпотентность: как повторить запрос без второго действия
Свойство операции: повтор одинакового запроса имеет тот же предполагаемый эффект, что и однократное выполнение. Границы этого свойства определяются правилами операции и системы.
Редакция:
Форма показала таймаут. Это ещё не означает, что получатель ничего не сделал: запись могла появиться, а ответ — потеряться по дороге. Если повтор создаёт новую запись, посетитель или сотрудник получает два результата одного намерения.
В RFC 9110, раздел 9.2.2 идемпотентность относится к предполагаемому эффекту одинаковых запросов. Ответы могут различаться, а журнал — сохранять каждую попытку. Поэтому одинаковый текст ответа и отсутствие повторных строк в журнале сами по себе не определяют это свойство.
Учебная заявка RETRY-34: ответ потерян после создания
Вымышленная интеграция создаёт обращение по согласованному API. Её контракт поддерживает ключ повтора для одного действия. Ключ хранится на стороне отправителя и получателя в пределах установленного срока; параметры повторной попытки сверяются. Это условия учебной модели, не описание любой CRM.
| Шаг | Что наблюдает отправитель | Что произошло у получателя |
|---|---|---|
| 1. Отправлены данные с ключом K-34 | Ожидает ответ | Создано обращение L-34, результат связан с K-34 |
| 2. Соединение оборвалось | Не знает результат | L-34 уже существует; отмены операции не было |
| 3. Повторены те же данные с K-34 в допустимый срок | Получает подтверждение исходного результата | Возвращена ссылка на L-34, вторая заявка не создаётся |
| 4. Проверен результат | Сверяет идентификатор и поля | В согласованной области учёта одна запись этого действия |
Ключ K-34 здесь — короткая подпись для чтения примера. Рабочий ключ генерируют по правилам поставщика; контакт, телефон или адрес почты в него не включают. Если при каждом нажатии создавать новый ключ, получатель может увидеть два разных действия. Отключённая кнопка уменьшает случайные нажатия, но не заменяет обработку повтора на стороне системы.
Где заканчивается защита ключа
| Изменение ситуации | Что нужно выяснить до повтора |
|---|---|
| Тот же ключ, но изменились поля | Как API отклоняет конфликт параметров; нельзя молча принять старый результат за новую редакцию |
| Два одинаковых запроса пришли одновременно | Как получатель связывает конкурирующие попытки и что сообщает о незавершённой обработке |
| Истёк срок хранения ключа | Может ли запрос стать новым действием; как сначала установить исходный результат |
| Другой ключ для того же намерения | Как на уровне заказа или обращения распознаётся повтор бизнеса, если API считает ключи разными |
| Другая операция, аккаунт или среда | Где действует уникальность ключа; переносить его между контекстами без правил нельзя |
| Первый запрос завершился ошибкой | Сохраняется ли ошибка и допустим ли повтор; какой результат нужно сверить отдельно |
Для конкретного примера Stripe API v1 сохраняет статус и тело после начала исполнения, включая ошибку 500. Тот же ключ возвращает сохранённый ответ; изменённые параметры вызывают ошибку. Ключ может быть удалён после хранения не менее 24 часов, а его повторное использование после удаления создаёт новый запрос. Это правила указанной версии API; в той же документации у API v2 описано другое поведение повторов. Условия вашей системы проверяют отдельно.
Что это означает для платежа
Учебный заказ O-34 связан с одной попыткой платёжной операции. После таймаута нужно установить состояние этой операции предусмотренным провайдером способом. Создание новой операции с новым ключом может привести к дополнительному действию; одного сообщения браузера об ошибке недостаточно для такого решения.
Ключ запроса не доказывает окончательное списание, доставку уведомления или правильность статуса заказа. Согласуйте идентификатор платёжной операции, состояния и способ сверки. Повторное уведомление об одном результате тоже должно обрабатываться по правилам получателя. Проверки выполняйте в тестовой среде провайдера с разрешёнными данными, без реальных списаний ради демонстрации.
Идемпотентность одной операции не обещает отсутствие всех дублей во всех системах. Человек может оформить новый заказ с теми же товарами, сотрудник — создать запись вручную, а другой канал — передать похожее обращение. Правила таких случаев определяются отдельно от ключа технического повтора.
Что попросить показать при приёмке
Попросите исполнителя воспроизвести потерю ответа после выполнения в разрешённой тестовой среде, затем повторить то же действие и сверить результат у получателя. В доказательстве нужны версия API, границы и срок ключа, безопасный идентификатор операции, число результатов и состояние интерфейса. Секреты и реальные контакты в отчёт не включают.
Отдельно проверьте изменённые поля, одновременные попытки и повтор после окончания срока. Если система не предоставляет нужного механизма, зафиксируйте ограничение и согласованный способ выяснения результата. Автоматический повтор без такого основания не считается готовым решением.
Запишите правила в паспорт интеграции. Для уведомлений о событиях также разберите webhook: подтверждение доставки и завершение обработки могут быть разными этапами.