Тарификация

Сервер 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

      общее число найденных звонков.