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
Описание: Возвращает стоимость тарифа.
Аргументы:
Имя | Тип | Описание |
---|---|---|