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 Параметры API.

Возвращаемое значение 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: Результат регистрации.

validate_registration_params

Описание: Проверка параметров регистрации во внешнем биллинге. В зависимости от исключения, TVMW API метод AccountRegister вернет определенный код ошибки:

Аргументы:

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

Возвращаемое значение None: Ничего не возвращает, в случае ошибки вызывает исключение.

Исключения:

Имя Описание
Exception error = 1
AccountRegisterException.RegistrationNotAllowedForClient error = 2
AccountRegisterException.IPLimitExceeded error = 3
AccountRegisterException.AutoActivationPeriodInvalid error = 4
AccountRegisterException.InvalidPhoneNumber error = 5
AccountRegisterException.PhoneBusyError error = 6
AccountRegisterException.PhoneOrDeviceUIDIsRequired error = 7
ExternalApiException error = 8
ConfirmationError.VerificationCodeWasSent error = 9
ConfirmationError.VerificationCodeIsWrong error = 10
AccountRegisterException.ExternalApiWasNotCreated error = 11
AccountRegisterException.CaptchaRequired error = 12
AccountRegisterException.InvalidCaptcha error = 13
AccountRegisterException.CaptchaLimitExceeded error = 14
AccountRegisterException.InvalidDealerId error = 15
ConfirmationError.ConfirmPhoneWithCall error = 16
ConfirmationError.PhoneWithCallConfirmationWaiting error = 17
AccountRegisterException.RegistrationNotAllowed error = 18
ConfirmationError.VerificationCodeWithPhoneNumberWasSent error = 19
ConfirmationError.VerificationCodeWithPhoneNumberIsWrong error = 20
ConfirmationError.VerificationWithCodeConfirmationWaiting error = 21
ConfirmationError.VerificationWithPhoneNumberConfirmationWaiting error = 22
AccountRegisterException.InvalidBillingApiId error = 23
AccountRegisterException.PhoneNumberDoesntMatch error = 24
ConfirmationError.VerificationCodeSendingFrequencyExceeded error = 25

post_account_registration

Описание: Выполнение действие с аккаунтом после регистрации.

Аргументы:

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

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 Объект тарифа.
is_free bool Флаг для бесплатного подключения тарифа.
free_for_inactive bool Флаг бесплатного подключения тарифа для неактивных абонентов.

Возвращаемое значение TariffAssignResponse: Объект TariffAssignResponse.

customer_change_basic_tariff

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

Аргументы:

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

Возвращаемое значение TariffAssignResponse: Объект TariffAssignResponse.

customer_unassign_nonbasic_tariff

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

Аргументы:

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

Возвращаемое значение None:

get_customer_tariff_list

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

Аргументы:

Имя Тип Описание
customer Customer Объект абонента.
ip str IP-адрес с которого выполняется запрос.
country geo_models.Country Объект страны с которого выполняется запрос.
city geo_models.City Объект города с которого выполняется запрос.

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

on_tariff_add

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

Аргументы:

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

Возвращаемое значение None:

get_authkey

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

Аргументы:

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

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

disable_autopayment

Описание: Отключение автоплатежа у абонента.

Аргументы:

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

Возвращаемое значение None:

post_payment_complete

Описание: Действие после успешного получения статуса транзакции.
Описание объекта CustomerTransaction
transaсtion.customer (tvmiddleware.models.Customer) - Объект абонента, от имени которого осуществляется транзакция.
transaсtion.amount (Decimal) - сумма транзакции. Может принимать положительные значения (пополнение баланса) и отрицательные (списание с баланса).
transaction.datetime (datetime) - дата и время создания транзакции.
transaction.source (int) - тип платежного шлюза, через который осуществляется транзакция
0 - Wallet One
1 - Wallet One Card
2 - PayPal
3 - API (транзакция создана через Billing API)
4 - Manual (транзакция создана вручную через панель администрирования Smarty)
5 - Internal (внутренний биллинг Smarty)
6 - Armenian Card
7 - Paymaster
8 - Paymaster Card
9 - Square Up
10 - Payture
11 - Null (только для тестов)
12 - Fortebank
13 - Stripe
14 - Sber
transaction.status (int) - статус транзакции. Принимает значения:
0 - не обработана, статус неизвестен
1 - обработана, транзакция прошла успешно
2 - ошибка, транзакция не прошла
transaction.is_autopayment (bool) - флаг указывающий, является ли транзакция автоплатежом (рекуррентным).
Описание объекта TVMiddlewareApiParams
params.request (django.http.request.HttpRequest) - объект запроса к TVMW API методу PaymentComplete.
params.params_dict (dict) - словарь, содержащий GET и POST параметры запроса, в зависимости от http метода.
params.ip (str) - IP-адрес с которого производится запрос.
params.authkey (str) - authkey запроса.
params.client (clients.models.Client) - объект клиента Smarty.
params.account (tvmiddleware.models.Account) - объект аккаунта, от лица которого осуществляется запрос.
params.device_uid (str) - uid устройства, с которого осуществляется запрос.
params.auth (bool) - флаг указывающий, авторизован ли аккаунт.
params.lang (str) - код языка источника запроса.
Описание объекта PaymentSource
source.payment_type (int) - тип платежного шлюза. Может принимать значения
0 - Wallet One
1 - Wallet One Card
2 - PayPal
3 - Armenian Card
4 - Paymaster
5 - Paymaster Card
6 - Square Up
7 - Payture
8 - Null (только для тестов)
9 - Fortebank
10 - Stripe

Аргументы:

Имя Тип Описание
transaction CustomerTransaction (billing.models.CustomerTransaction) Объект транзакции с актуальным статусом.
params TVMiddlewareApiParams (tvmiddleware.api_base.TVMiddlewareApiParams) Параметры API запроса.
source PaymentSource (billing.payment.PaymentSource) Объект источника платежа, соответствующий используемому платежному шлюзу.

get_tariff_price

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

Аргументы:

Имя Тип Описание