Блокировки средств используются, когда тарифицируемая услуга продолжается во времени, и/или услуга тарифицируется в несколько этапов. В первую очередь приложение «блокирует» некоторое количество средств на Остатке, достаточное для начального этапа тарифицируемых процедур. Например, это может быть сумма, необходимая для оплаты первой минуты звонка или прохождения первого уровня игры.
Если на балансовом Остатке недостаточно средств, запрос о блокировке отвергается.
При наличии средств для части балансового Остатка создаётся блокировка с именем, заданным приложением или самим сервером. Общее количество средств, доступных на балансовом Остатке, уменьшается на размер блокировки, но запись о списании средств в журнале Остатка не создаётся.
Как только плата за тарифицируемые процедуры приближается к размеру блокировки, приложение может увеличить размер блокировки на некоторую дополнительную сумму. Если на балансовом Остатке достаточно «свободных» средств (не зарезервированных другими «блокировками»), то размер блокировки увеличивается.
Приложение может освободить созданные им блокировки. Информация о блокировке удаляется из данных Остатка, и блокированная сумма зачисляется к свободным средствам Остатка. Например, эта функция может быть использована, если исходящий звонок не состоялся (на него не ответили), и блокированные средства должны быть освобождены без списания их с Остатка.
Наконец, приложение может списать заблокированные средства, указав имя блокировки. Размер списания не должен превышать размер блокировки.
В журнале Остатка создаётся запись о транзакции, и размер списания вычитается из Остатка и из размера блокировки. По выбору приложения блокировка может быть освобождена, и блокированная сумма зачисляется к свободным средствам Остатка.
При создании или расширении блокировки приложение может указать время окончания блокировки. Блокировка освобождается автоматически в указанное время. Это свойство можно использовать, если приложение может завершить работу без явного освобождения блокировок.
При создании или расширении блокировки приложение может указать размер списания для случаев, когда блокировка освобождается автоматически. Например, когда игровое приложение расширяет блокировку при переходе на следующий уровень игры, оно может указать сумму, которая должна быть списана за уже пройденный уровень. Если приложение завершается без явного списания блокированных средств с Остатка, блокировка будет освобождена автоматически, но указанная для автоматического списания сумма будет списана.
Подсистема Тарификации 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
- общее число найденных звонков.
|
