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, *args, **kwargs):
        # Получение баланса.
        customer = params.account.customer

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

Реализованные методы должны принимать позиционные и именованные аргументы (*args и **kwargs).

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

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

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

Аргументы:

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

get_customer_balance

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

Аргументы:

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

get_customer_payment_list

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

Аргументы:

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

get_video_actions_list

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

Аргументы:

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

perform_video_action

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

Аргументы:

activate_account

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

Аргументы:

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

deactivate_account

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

Аргументы:

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

update_account

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

Аргументы:

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

authorize_account

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

Аргументы:

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

check_account

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

Аргументы:

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

register_account_new

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

Аргументы:

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

validate_registration_params

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

Аргументы:

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

Исключения:

post_account_registration

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

Аргументы:

get_account

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

Аргументы:

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

accept_legal_document

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

Аргументы:

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

invoice_complete

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

Аргументы:

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

customer_assign_nonbasic_tariff

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

Аргументы:

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

customer_change_basic_tariff

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

Аргументы:

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

customer_unassign_nonbasic_tariff

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

Аргументы:

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

get_customer_tariff_list

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

Аргументы:

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

on_tariff_add

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

Аргументы:

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

get_authkey

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

Аргументы:

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

disable_autopayment

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

Аргументы:

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

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

Аргументы:

get_tariff_price

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

Аргументы:

get_payment_sum

Описание: Возвращает стоимость для всех тарифов абонента.

Аргументы:

get_payment_sum_no_discount

Описание: Возвращает стоимость для всех тарифов абонента без дисконта.

Аргументы:

customer_payment_info

Описание: Возвращает детализацию платежа.

Аргументы:

Возвращаемое значение CustomerPaymentInfoResponse: Детализация платежа

get_account_by_phone_number_1

Описание: Возвращает аккаунт по полю phone_number_1.

Аргументы:

Возвращаемое значение QuerySet[Account]: результат запроса к таблице модели Account