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

Поведение при повторных запросах и сетевых сбоях

Гарантии платформы

Операции создания (Pay In, Pay Out, операции платёжной формы) идемпотентны по полю idTransactionMerchant в пределах одного мерчанта.

Гарантируется, что на пару (IDDomainEntity, idTransactionMerchant) существует не более одной операции. При повторной отправке запроса с использованным значением idTransactionMerchant возвращается ответ:

status: "Warning";
codeError: "duplicateIdentifier";
data: null.

Новая операция не создаётся. Состояние существующей операции получается через GET /operation/operation/platform/{idPlatform}.

Требования к значению `idTransactionMerchant`

Требование	Описание
Уникальность	значение не должно повторяться между разными заказами в пределах мерчанта, в том числе по истечении любого срока
Устойчивость	одной бизнес‑сущности в системе мерчанта соответствует одно неизменное значение
Детерминированность	значение не должно регенерироваться при повторных действиях пользователя, инициирующих один и тот же платёж
Совместимость с URL	допустимые символы — алфавитно‑цифровые, `_`, `-`

При повторных попытках оплаты одного заказа применяется суффикс с номером попытки, например, order-42-attempt-2.

Порядок действий при сетевом сбое

Сценарий: запрос на создание операции отправлен, ответ не получен в результате таймаута или разрыва соединения. Состояние операции на стороне платформы неизвестно.

Порядок действий:

Создание операции с новым значением idTransactionMerchant не выполняется.
Запрос повторяется с тем же значением idTransactionMerchant после интервала ожидания.
При получении ответа Success операция считается созданной.
При получении ответа Warning с codeError: "duplicateIdentifier" операция уже существует на платформе. Состояние получается через GET /operation/operation/platform/{idPlatform}. Идентификатор idPlatform определяется одним из способов:
- значение data.id из ответа на первый запрос, если ответ был получен и сохранён;
- получение операции через эндпойнт POST /operation/operation/list с поиском по idTransactionMerchant.

Код ошибки duplicateIdentifier не определяет состояние операции. Финальное состояние получается отдельным запросом.

Повторная отправка на стороне платформы

Сценарий	Реализация
Pay Out не принят провайдером с первой попытки	повторная отправка выполняется платформой; операция находится в статусе `pending_retry`; вмешательство мерчанта не требуется
Доставка webhook не подтверждена `2xx`	повторная доставка выполняется платформой; гарантируется доставка финального события не менее одного раза

Создание дублирующей операции на стороне мерчанта при наличии статуса pending_retry не требуется и приводит к нарушению учёта.

Реакция мерчанта на различные ответы

Условие	Действие
HTTP `5xx`, сетевой таймаут, разрыв соединения	повтор с тем же `idTransactionMerchant`, экспоненциальная задержка
`Success`	продолжение штатного сценария
`Warning`, `codeError = duplicateIdentifier`	получение состояния существующей операции
`Warning`, `codeError = internalError`	повтор с экспоненциальной задержкой
`Warning`, прочие коды	обработка в соответствии с разделом Ошибки
`AuthError`, `AccessError`	прекращение попыток, уведомление эксплуатации