CommuniGate Pro
Версия 6.3
 

Тарификация

Сервер CommuniGate Pro может работать как платформа для Тарификации.

Каждый Пользователь может иметь один или несколько Остатков. Модули и компоненты CommuniGate Pro могут списывать из этих остатков плату за услуги и пополнять остатки, осуществлять различные операции возмещения средств и т.п.

Для каждого Остатка поддерживается текущая сумма, учитывающая активные блокировки средств.

Журнал всех транзакций хранится в файлах данных Пользователя. Формат Журнала позволяет легко производить операции резервного копирования и восстанавливать данные после различных аппаратных сбоев.

В качестве имени Остатка "по умолчанию" ("обычного" Остатка) используется пустая строка.

Денежные значения (денежные средства) представлены как целочисленные 64-битные целые значения со знаком.



Блокировки средств

Блокировки средств используются, когда тарифицируемая услуга продолжается во времени, и/или услуга тарифицируется в несколько этапов.

В первую очередь приложение «блокирует» некоторое количество средств на Остатке, достаточное для начального этапа тарифицируемых процедур. Например, это может быть сумма, необходимая для оплаты первой минуты звонка или прохождения первого уровня игры.
Если на балансовом Остатке недостаточно средств, запрос о блокировке отвергается.
При наличии средств для части балансового Остатка создаётся блокировка с именем, заданным приложением или самим сервером. Общее количество средств, доступных на балансовом Остатке, уменьшается на размер блокировки, но запись о списании средств в журнале Остатка не создаётся.

Как только плата за тарифицируемые процедуры приближается к размеру блокировки, приложение может увеличить размер блокировки на некоторую дополнительную сумму. Если на балансовом Остатке достаточно «свободных» средств (не зарезервированных другими «блокировками»), то размер блокировки увеличивается.

Приложение может освободить созданные им блокировки. Информация о блокировке удаляется из данных Остатка, и блокированная сумма зачисляется к свободным средствам Остатка. Например, эта функция может быть использована, если исходящий звонок не состоялся (на него не ответили), и блокированные средства должны быть освобождены без списания их с Остатка.

Наконец, приложение может списать заблокированные средства, указав имя блокировки. Размер списания не должен превышать размер блокировки.
В журнале Остатка создаётся запись о транзакции, и размер списания вычитается из Остатка и из размера блокировки. По выбору приложения блокировка может быть освобождена, и блокированная сумма зачисляется к свободным средствам Остатка.

При создании или расширении блокировки приложение может указать время окончания блокировки. Блокировка освобождается автоматически в указанное время. Это свойство можно использовать, если приложение может завершить работу без явного освобождения блокировок.
При создании или расширении блокировки приложение может указать размер списания для случаев, когда блокировка освобождается автоматически. Например, когда игровое приложение расширяет блокировку при переходе на следующий уровень игры, оно может указать сумму, которая должна быть списана за уже пройденный уровень. Если приложение завершается без явного списания блокированных средств с Остатка, блокировка будет освобождена автоматически, но указанная для автоматического списания сумма будет списана.

Интерфейсы

Подсистема Тарификации CommuniGate Pro доступна в:

  • приложениях CG/PL, выполняющихся на сервере (PBX Задачи, WebUser аплеты и т.п.).
  • сессиях протокола XIMSS, использующихся клиентскими программами.
  • клиентских приложениях ParlayX.
  • программах и сценариях, использующих интерфейс CLI.

Операции

Доступны следующие операции Тарификации:

list
Эта операция возвращает все Остатки, доступные для этого Пользователя.
Параметры:
отсутствуют
Результаты:
balance
массив имён доступных Остатков.
credit
Эта операция добавляет средства на Остаток.
Параметры:
balance
строка: название Остатка. Если Остаток с таким названием не существует, то он будет создан.
amount
неотрицательное число: зачисляемая сумма.
reference
строка: произвольные данные, используемые для указания ссылки, полезной при разрешении спорных ситуаций и т.д.
description
объект (обычно - строка или массив строк): произвольные данные, описывающие транзакцию.
Результаты:
amount
число: текущее значение Остатка.
remove
Эта операция удаляет Остаток.
Обратите внимание: история Остатков не удаляется. Если текущее значение Остатка ненулевое, то в историю Остатков добавляется запись, обнуляющая значение Остатка.
Параметры:
balance
строка: название Остатка. Остаток с таким названием будет удалён.
Результаты:
amount
число: размер удалённого Остатка.
reserve
Эта операция блокирует средства на Остатке. Заблокированная сумма не может быть использована для оплаты других услуг. Блокировка может отменяться явно, с возвращением заблокированных средств на Остаток, или она может прекращаться автоматически после заданного интервала времени.
Параметры:
balance
строка: название Остатка. Этот Остаток уже должен существовать.
amount
число: размер блокируемых средств. Если блокировка уже существует, это значение используется для увеличения блокируемой суммы.
reserve
строка: если этот параметр задан, то он должен указывать на существующую блокировку. Сумма amount будет добавлена к этой блокировке. Если этот параметр отсутствует, то создаётся новая блокировка.
expires
отметка о времени: если этот параметр задан, то он определяет, когда закончится срок действия этой операции блокировки средств.
overdraft
число: если этот параметр задан, то с его помощью можно будет зарезервировать сумму, превышающую значение текущего Остатка. Если этот параметр не задан, то попытка списать сумму, превышающую текущий Остаток, будет отвергнута.
charge
число: сумма к списанию при автоматическом освобождении блокировки.
reference, description
эти строки могут быть указаны, если задан атрибут charge. Они используются так же, как в операции credit, и применяются при списании средств при автоматическом освобождении блокировки.
Результаты:
reserve
строка: имя резерва (аналогично параметру reserve, если он задан).
amount
число: текущее значение резерва.
total
число: текущее значение свободных средств на Остатке.
release
Эта операция освобождает блокированные средства. Заблокированная сумма зачисляется на Остаток.
Параметры:
balance
строка: название Остатка. Этот Остаток уже должен существовать.
reserve
строка: имя существующей блокировки.
Результаты:
reserve
строка: имя блокировки (аналогично параметру reserve, если он задан).
amount
число: текущее значение блокировки.
total
число: текущее значение свободных средств на Остатке.
charge
Эта операция списывает средства с Остатка или из блокированных средств.
Параметры:
balance
строка: название Остатка. Этот Остаток уже должен существовать.
amount
число: списываемая сумма.
reserve
строка: если этот параметр задан, то сумма списывается из указанной блокировки. Если этот параметр отсутствует, то списывание осуществляется из Остатка.
overdraft
необязательно, не может быть указан совместно с параметром reserve: задание этого параметра позволяет списать сумму, превышающую текущий Остаток. Если этот параметр не задан, то попытка списать сумму, превышающую текущий Остаток, будет отвергнута.
release
необязательно, не может быть указан без параметра reserve: если параметр задан, то блокировка освобождается после списания средств.
reference, description
аналогично операции credit.
Результаты:
amount
число: текущее значение свободных средств на Остатке или сумма блокированных средств.
total
число: текущее значение свободных средств на Остатке (только при указании параметра reserve).
expires
отметка о времени: время окончания срока действия операции блокировки (только если был указан параметр reserve и установлено время окончания срока действия).
read
Эта операция читает текущий Остаток или текущий размер блокировки.
Параметры:
balance
строка: название Остатка. Этот Остаток уже должен существовать.
reserve
необязательная строка: если этот параметр существует, то он должен указывать на существующую блокировку. Операция читает размер блокировки. Если этот параметр отсутствует, то операция читает сумму Остатка.
Результаты:
amount
число: текущее значение Остатка или размера блокировки.
expires
отметка о времени: время окончания срока действия операции блокировки (только если был указан параметр reserve и установлено время окончания срока действия).
history
Эта операция читает журнал транзакций Остатка.
Параметры:
balance
строка: название Остатка. Этот Остаток уже должен существовать.
timeFrom, timeTill
отметки о времени: Записи, которые были записаны, начиная с timeFrom (включительно) и до timeTill (не включая последнюю отметку).
limit
число: максимально число отображаемых записей.
Если это число положительно, то сначала возвращаются самые последние записи, а более старые отбрасываются при достижении лимита.
Если это число отрицательно, то сначала возвращаются самые старые записи, а более новые отбрасываются при достижении лимита.
Результаты:
history
массив записей с транзакциями. Каждая запись содержит следующие элементы:
Date
отметка времени: время транзакции.
amount
число: сумма транзакции (положительно для операций credit).
balance
число: значение Остатка после этой транзакции.
reference, description
копии этих параметров операций credit и charge.
calllog
Эта операция читает журналы звонков.
Параметры:
timeFrom, timeTill
записи, которые были внесены в журнал, начиная с timeFrom (включительно) и до timeTill (не включая последнюю отметку).
limit
число: максимально число отображаемых записей.
Если это число положительно, то сначала возвращаются самые последние записи, а более старые отбрасываются при достижении лимита.
Если это число отрицательно, то сначала возвращаются самые старые записи, а более новые отбрасываются при достижении лимита.
filter
необязательная строка: если указана, то операция возвращает только записи, в которых адрес или реальное имя абонента соответствуют указанной строке.
Результаты:
callHistory
массив записей с транзакциями. Каждая запись содержит следующие элементы:
Date
отметка времени: время начала звонка в GMT.
direction
строка "inp" для входящих звонков, строка "out" для исходящих звонков.
To
строка с адресом абонента
RealName
(необязательно) "настоящее имя" абонента.
Call-ID
строка с Call-ID.
disconnected
отметка времени: время окончания звонка (GMT).
connected
отметка времени: время соединения. Если отсутствует, то соединения не было.
dialogError
(необязательно) строка с ошибкой при установлении звонка.
dialogApp
(необязательно) Если звонок принимался приложением УПАТС, то этот атрибут содержит имя приложения.
amount
общее число найденных звонков.

Руководство CommuniGate Pro. Copyright © 2020-2023, АО СталкерСофт