Smarty External API

Описание

External API предназначен для интеграции Smarty с внешними сервисами через, например, API биллинга или кинотеатра, а также для кастомизации поведения.

Создание интеграции

Интеграция - это скрипт на языке Python, который содержит класс, отнаследованный от класса SmartyBilling, в котором можно переопределять опеределённые методы, вызываемые в процессе работы Smarty. Полный список доступных методов приведён ниже. Краткий пример интеграции:

class CustomBillingClient(SmartyBilling):    
    def __init__(self, param1, param2, *args, **kwargs):
        # Инициализация интеграции, выполняется во время запроса от устройства и не должна содержать тяжёлых операций
        # Может принимать параметры в качестве аргументов, как например param1, param2 здесь,
        # которые заполняются в поле "Дополнительные атрибуты" в панели администрирования
        # Если параметр указан в аргументах, то и в настройках интеграции данный параметр должен присутствовать,
        # иначе интеграция не будет работать

        self.param1 = param1
        self.param2 = param2
        super(SmartyBilling, self).__init__(**kwargs)

    def get_customer_balance(self, params):
        # Получение баланса.
        customer = params.account.customer

        # здесь request - это некая функция, которая получает баланс из внешнего источника
        # customer.ext_id - это поле "Внешний ID у абонента"
        balance = request(self.param1, self.param2, customer.ext_id)
        return balance, payment, customer.id

Также, класс необходимо зарегистрировать операцией:

external_api.registry.add('custom_billing_client', CustomBillingClient)

Где 'custom_billing_client' - имя интеграции, которое будет отображаться в панели администрирования. Без данной операции интеграция будет игнорироваться.

Более подробные примеры интеграции можно найти по ссылке https://github.com/microimpuls/smarty-api-lib/tree/master/external-api.

Установка модуля

Установка модуля происходит следующим образом: - Файл с модулем необходимо поместить в /usr/share/microimpuls/smarty/modules_available/, после чего перезапустить сервис uwsgi. - В разделе "Общие настройки"-"Интеграция с API внешних систем" необходимо создать новую интеграцию, в поле "API handler class" выбрать нужный модуль, выставить флаг "По умолчанию для биллинга" и заполнить параметры. У оператора должна быть только одна интеграция с флагом "По умолчанию для биллинга".

Доступные методы

is_internal

Описание: Является ли встроенным обработчиком биллинга.

use_internal_billing

Описание: Разрешено ли использование внутреннего биллинга для данной интеграции.

check_ticket

Описание: Проверка состояния билета.

Аргументы:

Имя Тип Описание
code str Код билета.
sid str ID сессии.
params TVMiddlewareApiParams Параметры API.

Возвращаемое значение bool: Является ли билет активным.

get_customer_balance

Описание: Информация о балансе абонента.

Аргументы:

Имя Тип Описание
params TVMiddlewareApiParams Параметры API.

Возвращаемое значение Tuple[float, float, float]: Баланс абонента, рекомендуемую суммы оплаты и идентификатор аккаунта для оплаты.

get_customer_payment_list

Описание: Cписок транзакций пользователя за период.

Аргументы:

Имя Тип Описание
date_from datetime Дата начала периода.
date_to datetime Дата окончания периода.
params TVMiddlewareApiParams Параметры API.

Возвращаемое значение List[dict]: Список транзакций пользователя за период в фиксированном формате.

get_video_actions_list

Описание: Возвращает массив вариантов действий с видео. Если видео не куплено это может быть возможность покупки или аренды в разных форматах. Если куплено - запрос ссылки. Если пользователь не заргистрирован у поставщика - предложение регистрации.

Аргументы:

Имя Тип Описание
video Video Объект видео.
goods_id int Идентификатор товара или видео.
params TVMiddlewareApiParams Параметры API.

Возвращаемое значение List[dict]: Массив вариантов действий с видео в фиксированном формате.

perform_video_action

Описание: Выполнение действия с видео.

Аргументы:

Имя Тип Описание
video Video Объект видео.
action str Идентификатор действия с видео.
goods_id int Идентификатор товара или видео.
params TVMiddlewareApiParams Параметры API.

activate_account

Описание: Разблокировка аккаунта во внешнем биллинге.

Аргументы:

Имя Тип Описание
account Account Объект аккаунта.
account_device AccountDevice Устройство, с которого производится активация.
params TVMiddlewareApiParams

Возвращаемое значение str: Сообщение о результате или ошибке.

deactivate_account

Описание: Деактивация аккаунта во внешнем биллинге.

Аргументы:

Имя Тип Описание
account Account Объект аккаунта.

Возвращаемое значение str: Ничего не возвращает, при ошибке вызывает ExternalApiException.

update_account

Описание: Обновление аккаунта во внешнем биллинге.

Аргументы:

Имя Тип Описание
account Account Объект аккаунта.
method str Метод авторизации. Доступные значения: 'ip', 'abomenent', 'phone', 'passoword'.
ip str IP-адрес абонента.
params TVMiddlewareApiParams Параметры API.
login_params LoginParams Параметры авторизации.

Возвращаемое значение str: Сообщение о результате или ошибке.

authorize_account

Описание: Авторизация аккаунта во внешнем биллинге.

Аргументы:

Имя Тип Описание
account Account Объект аккаунта.
method str Метод авторизации. Доступные значения: 'ip', 'abomenent', 'phone', 'passoword'.
ip str IP-адрес абонента.
device_uid str уникальный идентификатор устройства.
abonement int Логин.
password str Пароль, переданный при логине.
params TVMiddlewareApiParams Параметры API.

Возвращаемое значение str: Ничего не возвращает, при ошибке авторизации (ExternalApiException) возвращает error = 3.

check_account

Описание: Проверка статуса аккаунта во внешнем биллинге. При ошибке проверки нужно кидать исключение ExternalApiException.

Аргументы:

Имя Тип Описание
account Account Объект аккаунта.
ip str IP-адрес абонента.
device_uid str уникальный идентификатор устройства.
device_model str модель устройства.
params TVMiddlewareApiParams Параметры API.

Возвращаемое значение str: Сообщение о результате или ошибке.

register_account_new

Описание: Регистрация аккаунта во внешнем биллинге.

Аргументы:

Имя Тип Описание
register_params RegisterParams Параметры регистрации.
params TVMiddlewareApiParams Параметры API.

Возвращаемое значение AccountRegisterResponse: Результат регистрации.

get_account

Описание: Возвращает аккаунт во время авторизации, позволяет подменять логику авторизации.

Аргументы:

Имя Тип Описание
client Client Клиент.
abonement Optional[int] Логин.
password Optional[str] Пароль, переданный при логине.
device_uid Optional[str] Уникальный идентификатор устройства.
phone_number Optional[str] Номер телефона.
ip Optional[str] IP-адрес абонента.

Возвращаемое значение GetAccountResponse: Результат авторизации.

accept_legal_document

Описание: Подтверждает правовой документ.

Аргументы:

Имя Тип Описание
accept_params LegalAcceptParams Параметры подтверждения.

Возвращаемое значение LegalAcceptResponse: Результат подтверждения.

invoice_complete

Описание: Заканчивает обработку внешнего инвойса.

Аргументы:

Имя Тип Описание
invoice_complete_params InvoiceCompleteParams Параметры обработки.

Возвращаемое значение InvoiceCompleteResponse: Результат обработки.

customer_assign_nonbasic_tariff

Описание: Подключает дополнительный тариф.

Аргументы:

Имя Тип Описание
customer Customer Объект абонента.
tariff Tariff Объект тарифа.

customer_change_basic_tariff

Описание: Подключает базовый тариф.

Аргументы:

Имя Тип Описание
customer Customer Объект абонента.
tariff Tariff Объект тарифа.
check_balance bool Флаг проверки баланса при подключении тарифа

customer_unassign_nonbasic_tariff

Описание: Отключает дополнительный тариф.

Аргументы:

Имя Тип Описание
customer Customer Объект абонента.
tariff Tariff Объект тарифа.

get_customer_tariff_list

Описание: Возвращает список тарифов абонента.

Аргументы:

Имя Тип Описание
customer Customer Объект абонента.

Возвращаемое значение GetCustomerTariffListResponse: Список тарифов абонента.

on_tariff_add

Описание: Колбэк, который вызывается при подключении тарифов.

Аргументы:

Имя Тип Описание
customer Customer Объект абонента.
pk_set Set[int] Список id тарифов.

get_authkey

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

Аргументы:

Имя Тип Описание
account Account Объект аккаунта.
params TVMiddlewareApiParams Параметры API.
login_params LoginParams Параметры авторизации.

Возвращаемое значение Tuple[str, bool]: Ключ авторизации и флаг возможности продолжения авторизации штатными методами Smarty.