Робота з новими методами Tariscope АРІ

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

Для роботи з Tariscope API в першу чергу треба створити відповідного користувача і надати йому права на всі або окремі методи API.

Для створення API користувача, в меню Tariscope виберіть Додаткові опції → Інтеграція. Клацніть по кнопці Tariscope API. З’явиться відповідна сторінка.

Клацніть по Користувачі АРІ. На панелі інструментів клацніть по іконці Додати.

З’явиться вікно Новий АРІ користувач, де слід ввести необхідні параметри та клацнути Зберегти.

В переліку користувачів АРІ виберіть того, що створили та клацніть по іконці права на методи. З’явиться сторінка Налаштування прав користувача, приклад якої показаний на малюнку 1.

 Малюнок 1

На малюнку виділені методи, які були додані у версії Tariscope 4.6.4. Ці методи мають наступне призначення:

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

Робота з Tariscope API повинна починатися з авторизації АРІ користувача в системі, яка виконується за допомогою методу api.auth. В наслідок виконання цього методу ви повинні отримати токен, який потрібно застосовувати при виконанні всіх інших АРІ методів. Строк дії токена 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 від 01.06.2023.

Ця компанія обслуговується у Кредобанку, код банку 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 поверне наступну інформації:

• id. Ідентифікатор телефонного номеру в Tariscope.
• subscriberid. Ідентифікатор абонента, якому доданий телефонний номер.
• pbxid. Ідентифікатор АТС, до якої належить телефонний номер.
• dn. Телефонний номер.

Приклад отримання інформації про додання номеру показаний на малюнку 9.

Малюнок 9