Работа с новыми методами Tariscope АРI

Для тестирования функции Tariscope API может использоваться любая самостоятельно написанная программа или другие программы, предназначенные для этого. В этой статье использовалась программа Postman.

Для работы с Tariscope API в первую очередь следует создать соответствующего пользователя и предоставить ему права на все или отдельные методы API. Для создания API пользователя в меню Tariscope выберите Дополнительные настройки → Интеграция. Щелкните по кнопке Tariscope API. Появится соответствующая страница.

Щелкните Пользователи API. На панели инструментов щелкните значок Добавить.

Появится окно Новый API пользователь, где необходимо ввести необходимые параметры и щелкнуть Сохранить.

В списке пользователей  API, выберите того, кого создали и щелкните по иконке права на методы. Появится страница Настройки прав пользователя, пример которой показан на рисунке 1.

 Рисунок 1

На рисунке выделены методы, добавленные в версии Tariscope 4.6.4. Эти методы имеют следующее назначение:

• accounts.charges. Это GET метод, позволяющий получить все начисления конкретного абонента за указанный период.
• accounts.payment. Это POST метод, позволяющий занести в базу данных Tariscope информацию об оплате от абонента за предоставленные услуги связи.
• accounts.payments. Это GET метод, позволяющий получить информацию из базы данных Tariscope по оплате от конкретного абонента за заданный период.
• subscriber.create. Это POST метод, позволяющий создать нового абонента без перечня принадлежащих ему телефонных номеров. Для добавления телефонных номеров следует использовать следующий способ.
• subscriber.dnadd. Это POST метод, позволяющий добавить абоненту телефонный номер.

Работа с API Tariscope должна начинаться с авторизации АРИ пользователя в системе, которая выполняется с помощью метода api.auth.В результате выполнения этого метода вы должны получить токен, который следует применять при выполнении всех других API методов. Срок действия токена 6 часов. После чего следует получить новый токен.

1. Получение токена

Для выполнения каких-либо методов API необходимо авторизироваться в системе. Выполните метод /api/auth.

Как упоминалось выше, работа с Tariscope API методами будет показана с использованием программы Postman.

Выберите метод Post, и введите запрос для подключения к компьютеру, где установлен Tariscope (рисунок 2)

Рисунок 2

Пример запроса: http://localhost:7000/api/auth

localhost используется только в случае, когда приложение, из которого выполняется API запрос, находится на том же сервере, где находится ПО Tariscope. В других случаях используйте IP-адрес сервера Tariscope.

7000 в этом примере – это IP порт, на котором работает Tariscope. По умолчанию при установке Tariscope предлагается IP-порт 8085.

/api/auth – это метод для авторизации в системе.

Перед отправкой запроса в теле (Body) запроса следует выбрать row, задать JSON формат и ввести в этом формате имя пользователя API (username) и его пароль (password).

На вкладке Authorization вибрать Bearer token.

После этого нажать кнопку Send. Если все параметры заданы правильно, то вы получите ответ в формате JSON, откуда следует копировать токен.

Для выполнения других методов Tariscope API этот токен следует вставить на вкладке Authorization в позицию Token. Напомним еще раз, что токен действителен в течении 6 часов.

2. Получение начислений абонента

Получение начислений производится с помощью GET метода /api/accounts/charges

Параметры метода:

• id – идентификатор абонента в системе Tariscope
• fromdate – дата, начиная с которой следует получить начисление. Дата сдается в формате: гггг-мм-дд, например: 2023-05-01.
• todate – дата, заканчивая которой нужно получить начисление. Дата сдается в формате: гггг-мм-дд, например: 2023-05-31.

К примеру, нас интересуют начисления абонента с идентификатором 6169 за май 2023 года. То есть в этом случае имеем:

id = 6169, fromdate = 2023-05-01, todate = 2023-05-31. Соответственно задаем строку GET запроса: http://localhost:8085/api/accounts/charges/?id=6169&fromdate=2023-05-01&todate=2023-05-31

Пример такого запроса в Postman показан на рисунке 3. Следует не забывать, что как и в предыдущем запросе в его теле (Body) должно быть указано имя и пароль API пользователя.

Рисунок 3

Если все параметры указаны верно, Tariscope вернет информацию о начислении абонента. Список параметров по каждому начислению:

• id – идентификатор абонента в системе Tariscope;
• recdate –даты внесения начисления в Tariscope;
• fromdate – дата начала периода начисления услуги;
• todate – дата окончания периода начисления услуги;
• servicename – название услуги;
• charge – начисленная сумма;
• numberofservices – количество начисленных услуг. Для вызовов это количество секунд.

Пример ответа сервера показан на рисунке 4.

Рисунок 4

В случае, когда строка запроса указана неверно или неверно указаны параметры запроса, Tariscope выдает сообщение (message) об этом. Пример этого приведен на рисунке 5.

Рисунок 5

3. Занесение в Tariscope информации об оплате

Занесение информации об оплате от абонента производится POST запросом: /api/accounts/payment

Параметры POST запроса к системе Tariscope:

• id – идентификатор абонента в системе Tariscope;
• paymentday – дата выполнения оплаты в формате: гггг-мм-дд;
• payment – сумма платежа за услуги связи;
• paymenttype – тип платежа (не указано – 0, наличные – 1, по квитанции – 2, по счету – 3);
• bank – банк, через который производилась оплата..

Пример.

Абонент с идентификатором 6193 оплатил 17/05/2023 по счету через ПриватБанк услуги связи на сумму 370,00 грн. Это значит:

id=6193,

paymentday=2023-05-17,

payment=370.00,

paymenttype=3,

bank=ПриватБанк

То есть строка POST запроса будет следующей: http://localhost:8085/api/accounts/payment/?id=6193&paymentday=2023-05-17&payment=370.00&paymenttype=3&bank=ПриватБанк

Если параметры запроса верны, Tariscope вернет следующие данные:

• subscriberid – идентификатор абонента в системе Tariscope.
• paymentid – идентификатор записи по оплате.
• paymentday – дата выполнения оплаты в формате: гггг-мм-дд.

Пример ответа приведен на рисунке 6.

Рисунок 6

4. Получение информации об оплате от абонента за период

Получение такой информации выполняется GET запросом: /api/accounts/payments

Параметры этого запроса::

• id – идентификатор абонента в системе Tariscope.
• fromdate – дата, начиная с которой нужно получить платежи. Дата задается в формате: гггг-мм-дд, например: 2023-05-01.
• todate – дата, заканчивая которой нужно получить платежи. Дата задается в формате: гггг-мм-дд, например: 2023-05-31.
• paymentid – ідентифікатор запису по оплаті. Якщо цей ідентифікатор вказаний у запиті, то дати ігноруються, а перевіряється наявність такого запису в БД Tariscope. Якщо цей ідентифікатор = 0, то АРІ повинне повернути всі платежі за вказаний період.

Пример.

Получить информацию об оплате от абонента с идентификатором 6169 за период с 01.04.2023 по 31.05.2023. Это означает, что нужно задать следующие параметры: id=6169, fromdate=2023-04-01, todate=2023-05-31, paymenеtid=0

То есть весь GET запрос будет следующим: http://localhost:8085/api/accounts/payments/?id=6169&fromdate=2023-04-01&todate=2023-05-31&paymenеtid=0

Если все параметры указаны верно, Tariscope вернет следующие данные:

• subscriberid – идентификатор абонента в системе Tariscope.
• paymentid – идентификатор записи по оплате.
• paymentday – дата выполнения оплаты в формате: гггг-мм-дд.
• payment – сумма оплаты.

Пример результата выполнения такого запроса показан на рисунке 7.

Рисунок 7

5. Создание нового абонента

Создание нового абонента выполняется с помощью запроса POST: /api/subscriber/create

Этот запрос содержит следующие параметры:

• fullname – полное имя юридического, физического лица или сотрудника оператора связи.
• departmentid – іидентификатор группы, к которой принадлежит абонент. Если абоненты не делятся на группы, то они относятся к корневой группе, которая называется как узел связи.
• subscribertype – тип абонента: 0 -физическое лицо, 1 – юридическое лицо, 2 – служебное, 3 – бюджетное, 4 – льготное.
• connectiondate - дата, с которой абонент считается подключенным в формате: гггг-мм-дд.
• contactnumber – номер контракта с абонентом.
• contractdate - дата контракта в формате: гггг-мм-дд.
• accountnumber - номер личного счета абонента, если он создается не автоматически в Tariscope.
• personalcode – индивидуальный налоговый номер для физических лиц.
• edrpou – код ЕГРПОУ для юридических лиц.
• taxcode – налоговый код для плательщиков НДС.
• bankcode – код банка для юридических лиц..
• bankname – название банка.
• bankaccount – номер банковского счёта.
• rateplanid – идентификатор тарифного плана, назначенный абоненту.

Пример.

Создать абонента юридическое лицо с именем JSC ABC, ЕГРПОУ 55667788, ИНН 123456789 с датой подключения с 02.06.2023, с которым заключен контракт на предоставление услуг связи по номеру 247-23 от 02.06.

Эта компания обслуживается в Кредобанке, код банка 325365, счет в банке UA125438790123456. Этот абонент будет обслуживаться по тарифному плану 'Базовый', имеющему идентификатор 43 в Tariscope. Абонента включить в группу абонентов с идентификатором 419.

Абоненту назначить лицевой счет 8640-fo.

Для этих параметров необходимо выполнить следующий POST запрос:

http://localhost:8085/api/subscriber/create/?fullname=JSC
ABC&departmentid=419&subscribertype=1&connectiondate=2023-06-02&contractnumber=247-23&contractdate=2023-06-01&accountnumber=8640-fo&personalcode=&edrpou=55667788&taxcode=&bankcode=361234&bankname=Кредобанк&bankaccount=UA125438790123456&rateplanid=43

При правильно заданных параметрах Tariscope возвращает следующую информацию:

• id – идентификатор абонента в системе.
• accountnumber - номер личного счета абонента. Если он создается автоматически в Tariscope, он будет совпадать с ID.
• fullname – полное имя юридического, физического лица или сотрудника оператора связи.

Пример полученной от Tariscope информации по этому запросу, приведенный на рисунке 8.

Рисунок 8

6. Добавление абоненту телефонного номера

Для добавления абоненту телефонного номера необходимо выполнить POST запрос: /api/subscriber/dnadd

Этот запрос содержит следующие параметры::

• SubscriberId. Идентификатор абонента, которому прилагается телефонный номер.
• DN. Телефонный номер, назначаемый абоненту.
• description. Описание телефонного номера. Необязательный параметр.
• fromdate. Дата, с которой этот номер принадлежит абоненту.
• pbxid. Идентификатор АТС, в которую входит телефонный номер.

Пример.

Абоненту с идентификатором 7334 следует назначить телефонный номер 2001 с 02.06.2023. Номер принадлежит АТС с идентификатором 292.

Для этих параметров необходимо создать следующий POST запрос: http://localhost:8085/api/subscriber/dnadd/?SubscriberId=7334&DN=2001&description=&fromdate=2023-06-02&pbxid=292

Якщо параметри запиту буди вказані вірно, то Tariscope поЕсли параметры запроса будут указаны верно, то Tariscope по  xid=292 вернет следующую информацию:

• id. Идентификатор телефонного номера Tariscope.
• subscriberid. Идентификатор абонента, которому прилагается телефонный номер.
• pbxid. Идентификатор АТС, в которую входит телефонный номер.
• dn. Телефонный номер.

Пример получения информации о добавлении номера показан на рисунке 9.

Рисунок 9