Жизненный цикл расчета

После приема купона Система расчета купонов SportAPI отслеживает результаты всех входящих в него ставок и обновляет состояние купона.

Текущий результат можно получать:

через запросы клиентского API;
через callback, если он подключен;
обоими способами одновременно.

Callback необязателен и не влияет на сам расчет. Даже если доставка callback не выполнена, состояние купона продолжает обновляться и доступно через API.

Общая схема

Купон создан
    ↓
Статус купона 0 — активен
    ↓
Рассчитываются отдельные ставки
    ↓
┌──────────────────────────────────────────┐
│ Все ставки рассчитаны                    │
│ → финальный статус купона 2, 4 или 8     │
└──────────────────────────────────────────┘

Отдельная ветка:
Купон возвращен на перерасчет
    ↓
Статус купона 15, статус исхода 4
    ↓
Ожидание повторного расчета
    ↓
Новый актуальный статус и новый callback

Статус купона и статусы отдельных ставок — разные значения. Например, частично рассчитанный экспресс может иметь статус купона 0, хотя некоторые ставки внутри него уже рассчитаны.

Состояние сразу после создания

Сразу после успешного создания:

Поле	Начальное значение
Статус купона	`0` (`NEW`)
Статус каждой ставки	`0` (`NET`)
`real_win`	`null`
`calculate_coef`	`null`
`calculate_date` купона	`null`
`calculate_date` ставок	`null`

Значение 0 вместо null для calculate_date не используется.

Купон считается активным до появления расчетного результата. Для экспресса статус 0 также используется во время частичного расчета.

Расчет ординара

Ординар содержит одну ставку, поэтому у него нет промежуточного расчета нескольких исходов.

После расчета ставки купон получает один из финальных статусов:

Статус купона	Результат
`2` (`WIN`)	Купон выиграл.
`4` (`LOSE`)	Купон проиграл.
`8` (`RETURN`)	Ставка возвращена.

Если callback подключен, после окончательного расчета ординара создается расчетный снимок и отправляется партнеру.

Частичный расчет экспресса

Экспресс состоит из нескольких ставок, которые могут рассчитываться в разное время.

Пока ни одна ставка не проиграла и не все ставки рассчитаны:

уже рассчитанные ставки получают свои расчетные статусы;
нерассчитанные ставки сохраняют статус 0;
купон сохраняет статус 0;
через API доступно его текущее состояние;
при подключенном callback после каждого нового расчетного статуса отправляется новый снимок всего экспресса.

Пример экспресса из пяти ставок:

1/0/0/0/0 → рассчитана первая ставка
1/1/0/0/0 → рассчитана вторая ставка
1/1/3/0/0 → третья ставка возвращена
1/1/3/1/0 → рассчитана четвертая ставка
1/1/3/1/1 → рассчитаны все ставки

Здесь каждое число — статус отдельной ставки:

0 — еще не рассчитана;
1 — выиграла;
3 — возврат.

Первые четыре состояния являются промежуточными. Последнее состояние завершает расчет экспресса.

В промежуточном callback:

статус купона равен 0;
realWin равен 0;
calculate_coefficient равен 0;
рассчитанные ставки содержат фактические статусы и расчетные данные;
нерассчитанные ставки остаются со статусом 0.

Промежуточный callback — это текущий снимок, а не окончательный результат купона.

Первый проигрыш экспресса

Как только хотя бы одна ставка получает статус 2 (LOSE), весь экспресс становится проигравшим:

1/1/2/0/0 → статус купона 4

Это происходит сразу, даже если остальные ставки еще не рассчитаны.

Если callback подключен, Система расчета немедленно отправляет снимок со статусом купона 4 (LOSE). Это позволяет партнеру не ждать завершения всех событий, чтобы узнать, что экспресс уже проиграл.

После первого проигрыша:

расчет остальных ставок продолжается;
текущее состояние можно получать через API;
отдельные промежуточные callback по оставшимся ставкам не отправляются.

Например:

1/1/2/1/0 → новый промежуточный callback не отправляется

Когда рассчитаны все ставки проигравшего экспресса, отправляется последний полный снимок:

1/1/2/1/3 → финальный callback

Статус купона в раннем и финальном снимках остается 4, но финальный снимок содержит итоговые статусы всех ставок.

Финальный расчет экспресса

Расчет экспресса считается завершенным, когда каждая ставка внутри него получила расчетный статус.

Итоговый статус зависит от результатов ставок:

если есть проигравшая ставка — купон получает 4 (LOSE);
если купон не проиграл и имеет выигрыш — 2 (WIN);
если все ставки завершились возвратом или push — 8 (RETURN).

Возврат отдельной ставки не делает весь экспресс возвращенным. Такая ставка получает расчетный множитель 1 и не увеличивает итоговый коэффициент.

Подробные коэффициенты, множители и выплаты описаны в разделе «Статусы и расчет выплаты».

Несколько версий одного купона

Один экспресс может штатно обновляться несколько раз. Каждый callback содержит полный расчетный снимок купона на конкретный момент времени.

Не путайте идентификаторы:

Поле	Что идентифицирует
`coupon_code`	Сам купон.
`events_data[].id`	Ставку внутри полной модели купона.
`events_data[].uuid`	Эту же ставку внутри callback; передается строкой.
`batchId`	Конкретную версию пакета callback.

Поэтому один coupon_code может прийти:

в нескольких последовательных callback;
с разными состояниями ставок;
с разными значениями batchId.

Это не дублирование купона. Партнер должен обновлять существующую запись по coupon_code, а повтор одной и той же доставки определять по batchId.

Новая расчетная версия получает новый batchId. Повторная HTTP-доставка уже созданной версии сохраняет прежний batchId.

Правила дедупликации подробно описаны в разделе «Повторы и идемпотентность».

Возврат на перерасчет

Ранее рассчитанный исход может быть возвращен на перерасчет.

В этот момент:

купон получает статус 15 (UPDATE);
возвращенный исход получает статус 4 (RECALCULATE);
при подключенном callback снимок с этим состоянием отправляется сразу;
купон ожидает повторного расчета;
после перерасчета при подключенном callback отправляется новый снимок с актуальными статусами.

Статус 15 не является окончательным результатом купона. Для партнера он означает: «Купон возвращен на перерасчет».

Название UPDATE остается техническим и не означает обычное обновление данных.

Финансовое действие при статусе `15`

Если предыдущий результат купона уже был обработан в системе партнера, при первом получении статуса 15 необходимо:

повторно списать с баланса пользователя сумму ставки amount;
перевести локальную запись купона в состояние ожидания нового результата;
дождаться следующего расчетного статуса;
после получения нового финального результата начислить пользователю новое значение real_win.

Callback не содержит поле amount. Партнеру необходимо сохранить сумму при создании купона либо получить полную модель купона через API.

Повторное списание выполняется только один раз для каждого нового перехода купона в статус 15. Повторная доставка callback с тем же batchId не должна создавать еще одно списание или начисление. При получении состояния через polling защищайтесь от повторной операции по сочетанию coupon_code и уже обработанного перехода статуса.

Что должна делать система партнера

Хранить coupon_code как связующий ключ.
Обновлять состояния купона и ставок при получении более новой версии.
Не считать статус 0 окончательным результатом экспресса.
Учитывать, что статус 4 может появиться до расчета всех ставок.
Не считать повторное появление одного coupon_code ошибкой.
При первом переходе уже рассчитанного купона в статус 15 повторно списать amount и ожидать обновленного результата.
После нового финального результата начислить новое значение real_win.
При необходимости периодически сверять состояние через API, даже если используется callback.

Следующий раздел: «Статусы и расчет выплаты».