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.