Working with new Tariscope API methods

Any self-written application or third-party application that is designed for this purpose can be used to test the Tariscope API functionality. The Postman application was used for testing in this article.

To work with the Tariscope API, first, you need to create a suitable user and grant him rights to all or individual API methods.

To create a API user, in the Tariscope menu, select Advanced options → Integrations. Click on the Tariscope API button. The corresponding page will appear.

Click on API users. Click on the Add icon on the toolbar.

The New API user window appears, where you need to enter the required parameters and click on the Save button.

In the list of API users, select the one you created and click on the Method rights icon. The Claims setup for user page will appear, an example of which is shown in Figure 1.

Figure 1

The figure highlights the methods that were added in Tariscope version 4.6.4. These methods have the following purpose:

• accounts.charges. This is a GET method that allows you to get all charges of a specific subscriber for the specified period.
• accounts.payment. This is a POST method that allows you to enter information about payments from the subscriber for the provided communication services into the Tariscope database.
• accounts.payments. This is a GET method that allows you to get information from the Tariscope database about payments from a specific subscriber for a given period.
• subscriber.create. This is a POST method that allows you to create a new subscriber without a list of phone numbers (DNs) that belong to him. The following method should be used to add phone numbers (DNs).
• subscriber.dnadd. This is the POST method that allows to add a phone number (DN) for the subscriber.

Work with the Tariscope API must begin with the authorization of the API user in the system, which is performed using the api.auth method. As a result of the execution of this method, you should receive a token that must be used when executing all other API methods. The token is valid for 6 hours. After that you should get a new token.

1. Receiving the token

To perform any API method, you should authorize in the system. Execute the /api/auth method.

As mentioned above, working with the Tariscope API methods will be demonstrated using the Postman program.

Select the Post method and enter a request to connect to the computer where Tariscope is installed (Figure 2).

Figure 2

An example of the request:

http://localhost:7000/api/auth

localhost is used only if the application from which the API request is executed is on the same server as the Tariscope software. Otherwise, use the IP address of the Tariscope server.

7000 is the IP port on which Tariscope is running. By default, when installing Tariscope, IP port of 8085 is used.

/api/auth is a method for authorization in the system.

Before sending a request, you should select the row value in the Body tab of the request, set the JSON format and enter the username and password in this format.

On the Authorization tab, select Bearer token.

After that, click on the Send button. If all parameters are set correctly, you will receive a response in JSON format, from where you should copy the token.

To execute all other Tariscope API methods, this token should be inserted on the Authorization tab in the Token textbox. We remind you once again that the token is valid for 6 hours.

2. Receiving subscriber's charges

Receipt of charges is performed using the GET method /api/accounts/charges

Method parameters:

• id – subscriber ID in the Tariscope system.
• fromdate – the date from which the charge should be received. The date is set in the format: yyyy-MM-dd, for example: 2023-05-01.
• todate – the date by which the charge must be received. The date is set in the format: yyyy-MM-dd, for example: 2023-05-31.

For example, we are interested in the billing of a subscriber with ID 6169 for May 2023. That is, in this case we have:

id = 6169, fromdate = 2023-05-01, todate = 2023-05-31. Accordingly, we set the GET request:

http://localhost:8085/api/accounts/charges/?id=6169&fromdate=2023-05-01&todate=2023-05-31

An example of such a request in the Postman program is shown in Figure 3. It should not be forgotten that, as in the previous request, the user's API name and password should be specified in its body.

If all parameters are specified correctly, Tariscope will return information about the subscriber's billing.

Figure 3

List of parameters for each calculation:

• id – subscriber ID in the Tariscope system.
• recdate – date of entry of charge in Tariscope.
• fromdate – the start date of the service billing period.
• todate – the date of the end of the service billing period.
• servicename – service name.
• charge – charged amount.
• numberofservices – the number of charged services. For calls, this is the number of seconds.

An example of the server's response is shown in Figure 4.

Figure 4

If the query is specified incorrectly, or the query parameters are incorrectly specified, Tariscope returns a message about this. An example of this is shown in Figure 5.

Figure 5

3. Entering payment information in Tariscope

Entering payment information from the subscriber is performed by a POST request: /api/accounts/payment

Parameters of the POST request to the Tariscope system:

• id – subscriber ID in the Tariscope system.
• paymentday – payment execution date in the format: yyyy-MM-dd.
• payment – amount of payment for communication services.
• paymenttype – type of payment (not specified – 0, cash – 1, by receipt – 2, by account – 3).
• bank – the bank through which the payment was made.

Example.

The subscriber with the identifier of 6193 paid for communication services in the amount of USD 370.00 on 05/17/2023 on account through XXXBank. This means: id=6193, paymentday=2023-05-17, payment=370.00, paymenttype=3, bank=XXXBank

The POST request will be as follows:

http://localhost:8085/api/accounts/payment/?id=6193&paymentday=2023-05-17&payment=370.00&paymenttype=3&bank=XXXBank

If the query parameters are correct, Tariscope will return the following data:

• subscriberid – subscriber ID in the Tariscope system.
• paymentid – payment record identifier.
• paymentday – date of payment in the format: yyyy-MM-dd.

An example of the answer is shown in Figure 6.

Figure 6

4. Receiving information on subscriber payments for the period

Obtaining such information is performed with a GET request: /api/accounts/payments

This request has the following parameters:

• id – subscriber ID in the Tariscope system.
• fromdate – the date from which payments are to be received. The date is set in the format: yyyy-MM-dd, for example: 2023-05-01.
• todate – the date by which payments are to be received. The date is set in the format: yyyy-MM-dd, for example: 2023-05-31.
• paymentid – payment record identifier. If this identifier is specified in the request, then the dates are ignored, and the presence of such a record in the Tariscope database is checked. If this identifier = 0, then the ARI must return all payments for the specified period.

Example.

Get information about payments from the subscriber with the identifier 6169 for the period from 04/01/2023 to 05/31/2023. This means that the following parameters must be set: id=6169, fromdate=2023-04-01, todate=2023-05-31, paymenеtid=0

That is, the entire GET request will be as follows:

http://localhost:8085/api/accounts/payments/?id=6169&fromdate=2023-04-01&todate=2023-05-31&paymenеtid=0

If all parameters are specified correctly, Tariscope will return the following data:

• subscriberid – subscriber ID in the Tariscope system.
• paymentid – payment record identifier.
• paymentday – date of payment in the format: yyyy-MM-dd.
• payment – payment amount.

An example of the result of executing such a request is shown in Figure 7.

Figure 7

5. Creating a new subscriber

Creating a new subscriber is done using a POST request: /api/subscriber/create

This request has the following parameters:

• fullname – full name of a legal entity, individual, or employee of a communications operator.
• departmentid – ID of the group to which the subscriber belongs. If the subscribers are not divided into groups, then they belong to the root group, which has the same name as the communication node.
• subscribertype – subscriber type: 0 - individual, 1 - legal entity, 2 - official, 3 - budget, 4 - preferential.
• connectiondate - date from which the subscriber is considered connected in the format: yyyy-MM-dd.
• contactnumber – contract number with the subscriber.
• contractdate - contract date in the format: yyyy-MM-dd.
• accountnumber - subscriber's personal account number, if it is not created automatically in Tariscope.
• personalcode – individual tax number for individuals.
• edrpou – legal entity code.
• taxcode – tax code for legal entity.
• bankcode – bank code for legal entities.
• bankname - name of bank.
• bankaccount – bank account number.
• rateplanid – identifier of the rate plan assigned to the subscriber.

Example.

Create a subscriber, a legal entity with the name of JSC ABC, its code is 55667788, a tax code is 123456789, with a date of connection from 02.06.2023, with which a contract for the provision of communication services under the number 247-23 dated 01.06.2023 was concluded. This company is served by XXXBank, the bank code is 325365, the bank account is UA125438790123456. This subscriber will be served with the “Basic” rate plan, which has the identifier 43 in Tariscope. The subscriber belongs to the group of subscribers with the identifier of 419. The personal account of8640-fo should be assigned to the subscriber

For these parameters, the following POST request must be performed:

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=XXXBank&bankaccount=UA125438790123456&rateplanid=43

With the correct settings, Tariscope returns the following information:

• id – subscriber ID in the system.
• accountnumber - subscriber's personal account number. If it is generated automatically in Tariscope, it will match the id.
• fullname – full name of a legal entity, an individual, or an employee of the telecommunications provider.

An example of information received from Tariscope for this request is shown in Figure 8.

Figure 8

6. Adding a phone number to the subscriber

To add a phone number to a subscriber, you need to perform a POST request: /api/subscriber/dnadd

This request has the following parameters:

• SubscriberId. Subscriber ID to which the phone number is assigned.
• DN. The phone number assigned to the subscriber.
• description. Description to the phone number. Optional parameter.
• fromdate. The date from which this number belongs to the subscriber.
• pbxid. The identifier of the PBX to which the telephone number belongs.

Example.

The subscriber with the identifier 7334 must be assigned the telephone number 2001 from 02.06.2023. The number belongs to the PBX with identifier 292.

The following POST request should be created for these parameters:

http://localhost:8085/api/subscriber/dnadd/?SubscriberId=7334&DN=2001&description=&fromdate=2023-06-02&pbxid=292

If the request parameters are specified correctly, Tariscope will return the following information:

• id. Phone number identifier in Tariscope.
• subscriberid. Subscriber ID to which the phone number is assigned.
• pbxid. The identifier of the PBX to which the telephone number belongs.
• dn. Phone number.

An example of obtaining information about adding a number is shown in Figure 9.

Figure 9