Жизненный цикл ваучера

Обзор

Данное руководство описывает полный жизненный цикл ваучера в системе — от создания до закрытия, включая процессы привязки и отвязки устройств, а также особенности биллинга.

Общая схема жизненного цикла ваучера

Жизненный цикл ваучера проходит через следующие основные этапы:

Создан → Привязан к устройству (Активирован) → [Эксплуатация] → Закрыт

В процессе эксплуатации можно:

Отвязать текущее устройство.
Привязать новое устройство.
Заменить транспортное средство.

Статусы ваучера

Ваучер может находиться в одном из статусов, отраженных в параметре VoucherStatusCycle:

Статус	Значение	Описание
0	Ожидает привязки	Ваучер создан, но устройство еще не привязано
1	Ожидает активации	Устройство привязано, система ожидает подтверждения
2	Активирован	Ваучер полностью активирован и функционирует
3	Ошибка активации	Возникла ошибка при активации
4	Замена транспортного средства	Происходит процесс замены ТС
5	Ошибка замены транспортного средства	Возникла ошибка при замене ТС
6	Ожидает деактивации	Запрошена деактивация ваучера, новые данные перестают собираться, но собранные данные продолжают быть доступны для просмотра и хранятся в системе
7	Деактивирован	Ваучер полностью деактивирован
8	Ошибка деактивации	Возникла ошибка при деактивации

Дополнительно ваучер имеет статус договора (ClientContractStatus):

0 - закрыт
1 - открыт

Шаг 1: Создание ваучера

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

После создания ваучер получает статус 0 (Ожидает привязки), а также идентификатор id, который используется для работы с сущностью ваучера.

Шаг 2: Привязка устройства и активация ваучера

Для активации ваучера необходимо привязать к нему устройство. Это двухэтапный процесс, включающий поиск устройства из общего пула и его привязку.

2.1 Поиск устройства по IMEI

Сначала необходимо найти устройство по его IMEI-номеру с помощью метода GetDeviceListImei:

curl -X GET "https://dev.api.exodrive.ai/api/v2/Device/list/imei?search=351579111983232" \
-H "Authorization: Bearer YOUR_TOKEN"

Пример ответа:

{
  "total": 1,
  "items": [
    {
      "id": 863,
      "title": "351579111983232"
    }
  ]
}

Этот запрос вернет список устройств, соответствующих поисковому запросу, с их идентификаторами.

2.2 Получение подробной информации об устройстве

После получения идентификатора устройства, необходимо запросить его детальную информацию с помощью метода GetDeviceById:

curl -X GET "https://dev.api.exodrive.ai/api/v2/Device/863" \
-H "Authorization: Bearer YOUR_TOKEN"

Пример ответа:

{
  "id": 863,
  "imei": "351579111983232",
  "serialNumber": "SNXFE32197",
  "terminalOctoStatus": 2
}

В ответе будет содержаться полная информация об устройстве, включая серийный номер.

Только устройства со статусом 2 (готово к использованию) будут доступны для привязки к ваучеру и будут возвращаться в списке доступных устройств из предыдущего метода. Устройства с другими статусами, например 4 (уже используется), не будут отображаться в списке доступных устройств, что исключает возможные проблемы при привязке.

2.3 Привязка устройства к ваучеру

После получения всех необходимых данных об устройстве, можно приступать к его привязке с использованием метода PostVoucherIdDeviceAttach:

curl -X POST "https://dev.api.exodrive.ai/api/v2/Voucher/4217/device/attach" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_TOKEN" \
-d '{
  "voucherId": 4217,
  "imei": "351579111983232",
  "deviceSerialNumber": "SNXFE32197"
}'

Пример ответа:

{
  "voucherId": 4217
}

Важно указать оба параметра - IMEI и серийный номер. Это защитный механизм, предотвращающий случайную привязку чужого устройства, так как требуется знание обоих параметров.

После успешной привязки устройства ваучер автоматически активируется, если это первая привязка. При этом:

Статус ваучера меняется на 2 (Активирован).
Ваучеру присваивается уникальный номер (voucherNumber).
Создается служебный идентификатор voucherObjectId, который используется для работы с непосредственно собранными данными.
Устанавливается дата активации (activationDate).
Начинается сбор данных с устройства.
Начинается биллинг.

Шаг 3: Эксплуатация ваучера

В процессе эксплуатации ваучер находится в статусе 2 (Активирован) и функционирует в штатном режиме. В этот период:

Система собирает данные с устройства.
Формируются скоринговые показатели.
Регистрируются события и аварии.
Происходит биллинг согласно выбранному типу контракта.

Замена устройства

В случае необходимости, к активному ваучеру можно привязать другое устройство. Для этого необходимо:

Отвязать текущее устройство.
Привязать новое устройство.

Отвязка текущего устройства:

Отвязка текущего устройства производится с помощью метода PostVoucherIdDeviceDettach:

curl -X POST "https://dev.api.exodrive.ai/api/v2/Voucher/4217/device/dettach" \
-H "Authorization: Bearer YOUR_TOKEN"

Пример ответа:

{
  "voucherId": 4217
}

После отвязки устройства ваучер все равно остается в статусе 2 (Активирован). Важно понимать, что даже после отвязки устройства ваучер продолжает считаться активным и биллинг не прекращается.

Привязка нового устройства:

Выполняется по той же схеме, что и первичная привязка (шаги 2.1-2.3).

Шаг 4: Закрытие ваучера

Заключительным этапом жизненного цикла является закрытие ваучера с использованием метода PostVoucherIdClose:

curl -X POST "https://dev.api.exodrive.ai/api/v2/Voucher/4217/close" \
-H "Authorization: Bearer YOUR_TOKEN"

Пример ответа:

{
  "voucherId": 4217
}

После успешного выполнения запроса:

Статус ваучера изменяется на 6 (Ожидает деактивации).
Статус договора меняется на 0 (Закрыт).
Устанавливается дата закрытия (closeDate).
Прекращается сбор новых данных.
Прекращается биллинг.
Все собранные ранее данные остаются доступными для просмотра и хранятся в системе.

Особенности биллинга

Биллинг ваучера имеет следующие особенности:

Начало биллинга: Биллинг начинается с момента первой успешной привязки устройства к ваучеру, то есть с даты активации (activationDate).
Продолжительность биллинга: Ваучер биллится непрерывно с момента активации до его закрытия, даже в периоды, когда к нему не привязано ни одно устройство.
Смена устройств: Замена устройств не влияет на биллинг. Ваучер продолжает биллиться непрерывно, даже в периоды между отвязкой одного устройства и привязкой другого.
Окончание биллинга: Биллинг прекращается только после явного закрытия ваучера.
Расчет стоимости: Стоимость услуг рассчитывается на основе выбранного типа контракта (contractTypeId), который определяет тарифный план и набор включенных услуг.

Схема изменения статусов

Создание             Первая привязка         Закрытие
ваучера              устройства              ваучера
   ↓                     ↓                     ↓
   0-1 ----------------→ 2-5 ----------------→ 6-8
(Ожидает привязки)   (Активирован)     (Ожидает деактивации)
                          ↑
                          |
                      Отвязка/привязка
                      устройства
                      (не меняет статус)