Начисление подписаний (API)

Цель документа — описать требования к интеграционному API для подключения информационных систем партнеров к платформе подписания HotDocs, дя начисления подписей пользователю.

Термины и определения

Термин	Определение
Услуга/Пакет	Тарифный план с определенным количеством подписаний на платформе
ИС	Информационная система
РК	Республика Казахстан
Hotdocs/Платформа	Платформа позволяющая пользователям подписывать документы, используя электронный ключ (ЭЦП) выпущенный УЦ Aitu Passport посредством биометрической идентификации
Trial услуга	Триальные услуги предоставляются на 14 дней и включают 50 подписей, независимо от исходного размера пакета. Триальные услуги имеют уникальные ID и могут быть активированы для ознакомления с услугой перед основной покупкой.

Описание методов

Клиент купил пакеты: Клиент покупает, например, 100 пакетов, которые означают, что он может использовать 100 подписей. Пакеты действуют в течение одного месяца.

Триальные услуги: Триальные услуги предоставляются на 14 дней и включают 50 подписей, независимо от исходного размера пакета.

Триальные услуги имеют уникальные ID и могут быть активированы для ознакомления с услугой перед основной покупкой.

Отключение услуги (disable): При запросе с методом disable все оставшиеся пакеты удаляются.

Блокировка услуги (suspend): При запросе с методом suspend все оставшиеся пакеты замораживаются до конца текущего месяца.

Разблокирование услуги (resume): Если запрос с методом resume отправлен, когда до конца текущего месяца осталось например 5 дней, клиент может использовать оставшиеся пакеты в течение этих 5 дней. По истечении месяца все неиспользованные пакеты сгорают.

Методы взаимодействия

Включение/Разблокирование услуги

Запрос

POST /api/v1/billing/subscribe?trial=false&method=ENABLE&serviceId=4&msisdn=77773132185&transactionId=40

Параметры запроса

Параметр	Тип	Описание	Пример заполнения
trial	boolean	Признак триальной услуги	false
method	enum	Метод	Пример: enable (включение) или resume (разблокирование)
serviceId	number	ID услуги (тарифный план)	415926-“Триал Цифровая подпись 100” 415930 - “Триал Цифровая подпись 500” 415931 - “Триал Цифровая подпись 1000”
userId	string	Абонентский номер (на который начисляются подписания)	77001231231
transactionId	bigint	Уникальный номер транзакции	999

Отключение/Блокирование услуги

Запрос

POST /api/v1/billing/unsubscribe?userId={msisdn}&trial={trial}&serviceId={serviceId}&transaction={transactionId}&method={method}

Параметр	Тип	Описание	Пример заполнения
trial	boolean	Признак триальной услуги	false
method	enum	Метод	Пример: disable (отключение) или suspend (блокирование)
serviceId	number	ID услуги (тарифный план)	415926-“Триал Цифровая подпись 100” 415930 - “Триал Цифровая подпись 500” 415931 - “Триал Цифровая подпись 1000”
userId	string	Абонентский номер (на котором блокируется или отключается услуга)	77001231231
transactionId	bigint	Уникальный номер транзакции	999

Списание абонентской платы

Запрос

POST /api/v1/billing/payment?userId={msisdn}&serviceId={serviceId}&transaction={transactionId}

Параметр	Тип	Описание	Пример заполнения
userId	string	Абонентский номер (на который начисляются подписания)	77001231231
serviceId	number	ID услуги (тарифный план)	415926-“Триал Цифровая подпись 100” 415930 - “Триал Цифровая подпись 500” 415931 - “Триал Цифровая подпись 1000”
transactionId	bigint	Уникальный номер транзакции	999