Traffic report API v2

1. Introduction

The HORISEN Traffic Report API is used for creating traffic reports for the BULK SMS API.

This API returns information about traffic associated with an invoice with a given ID. It returns the number of sent messages, the price per message and the total amount for each pricing condition, country, operator and selling/buying price. The requests are carried out by using a GET method.

This API belongs to the Traffic Report domain. Subject Domain in the endpoint URL is:

https://api.horisen.pro/bulk/traffic-report/v2

The API uses the HORISEN implementation of the OAuth 2.0 protocol. For more information, please refer to the OAuth2 Authentication Guidelines page.

2. Methods Overview

2.1 TrafficReports

Endpoint for an invoice traffic report.

GET/customer-invoices/{invoiceId}/traffic-reports
Returns an invoice traffic report with a list of traffic items.Read More

2.2 ControlTrafficReports

Endpoint for a control invoice traffic report.

GET/control-invoices/{invoiceId}/traffic-reports
Returns a control invoice traffic report with a list of traffic items.Read More

3. Methods Details

3.1 TrafficReports

Endpoint for an invoice traffic report.

GET/customer-invoices/{invoiceId}/traffic-reports
Returns an invoice traffic report with a list of traffic items.Up

Method Overview

Returns an invoice traffic report with a list of traffic items for given customer invoice ID.
The required authorization privilege for this endpoint is bulk-traffic-report.view. Optional privilege used for this endpoint is bulk-traffic-report-own.view.
This endpoint accepts query parameters for filtering traffic report items described at URL Filtering Guidelines page.

Parameters

Name Type Description
invoiceId (required) integer (path) Invoice ID.
operator(fieldName) string (query) Search criteria by using the following operators: isnull, isnotnull, isempty, isnotempty, eq, neq, startswith, contains, endswith, doesnotcontain, lt, lte, gt, gte, in, notin, between, notbetween, and the following attributes: customerId, billingAccountId, billingAccountName, countryId, countryName, countryCode2, operatorId, operatorName, sellPrice, sellPriceSinceDt, sellCurrency, sellCurrencyCode, mcc, mnc.

  • If operator is one of isnull, isnotnull, isempty, isnotempty, a field value can be omitted.
  • If operator is in or notin, a field value must be a comma separated list of values.
  • If operator is between or notbetween, a field value must be a comma separated list of two values, representing the beginning and the end of a range.
  • Operator can be omitted, and in that case it will be treated as operator is eq (E.g. fieldName=fieldValue).
  • Example: startswith(clientName)=hor, starts with hor in field 'clientName'.
  • If fieldName is 'q' and operator is eq or omitted, a field value will be used in general search across multiple attributes.

Responses

Code Description Link
200 Invoice traffic report. No links.
Default Unexpected error. No links.

Success Response 200: Invoice Traffic Report

 {
  "data": [
    {
      "customerId": 0,
      "billingAccountId": 0,
      "billingAccountName": "string",
      "countryId": 0,
      "countryName": "string",
      "countryCode2": "string",
      "operatorId": 0,
      "operatorName": "string",
      "inSmsCnt": 0,
      "sellPrice": 0,
      "sellPriceSinceDt": "2022-02-09T10:29:34.738Z",
      "sellCurrency": 0,
      "sellCurrencyCode": "string",
      "mcc": "string",
      "mnc": "string",
      "startDt": "2022-02-09T10:29:34.738Z",
      "endDt": "2022-02-09T10:29:34.738Z",
      "totalAmount": 0
    }
  ],
  "meta": {
    "pagination": {
      "total": 0,
      "count": 0,
      "perPage": 0,
      "currentPage": 0,
      "totalPages": 0
    }
  }
}

Error Response Unexpected Error: Default

{
  "Code": 0,
  "Message": "string"
}

3.2 ControlTrafficReports

Endpoint for a control invoice traffic report.

GET/control-invoices/{invoiceId}/traffic-reports
Returns a control invoice traffic report with a list of traffic items.Up

Method Overview

Returns a control invoice traffic report with a list of traffic items for given control invoice ID.
The required authorization privilege for this endpoint is bulk-traffic-report.view. Optional privilege used for this endpoint is bulk-traffic-report-own.view.
This endpoint accepts query parameters for filtering traffic report items described at URL Filtering Guidelines page.

Parameters

Name Type Description
invoiceId (required) integer (path) Invoice ID.
operator(fieldName) string (query) Search criteria by using the following operators: isnull, isnotnull, isempty, isnotempty, eq, neq, startswith, contains, endswith, doesnotcontain, lt, lte, gt, gte, in, notin, between, notbetween, and the following attributes: supplierId, billingAccountId, billingAccountName, countryId, countryName, countryCode2, operatorId, operatorName, buyPrice, buyPriceSinceDt, buyCurrency, buyCurrencyCode, mcc, mnc.

  • If operator is one of isnull, isnotnull, isempty, isnotempty, a field value can be omitted.
  • If operator is in or notin, a field value must be a comma separated list of values.
  • If operator is between or notbetween, a field value must be a comma separated list of two values, representing the beginning and the end of a range.
  • Operator can be omitted, and in that case it will be treated as operator is eq (E.g. fieldName=fieldValue).
  • Example: startswith(clientName)=hor, starts with hor in field 'clientName'.
  • If fieldName is 'q' and operator is eq or omitted, a field value will be used in general search across multiple attributes.

Responses

Code Description Link
200 Control invoice traffic report. No links.
Default Unexpected error. No links.

Success Response 200: Control Invoice Traffic Report

{
  "data": [
    {
      "supplierId": 0,
      "billingAccountId": 0,
      "billingAccountName": "string",
      "countryId": 0,
      "countryName": "string",
      "countryCode2": "string",
      "operatorId": 0,
      "operatorName": "string",
      "outSmsCnt": 0,
      "buyPrice": 0,
      "buyPriceSinceDt": "2022-02-09T10:29:34.750Z",
      "buyCurrency": 0,
      "buyCurrencyCode": "string",
      "mcc": "string",
      "mnc": "string",
      "startDt": "2022-02-09T10:29:34.750Z",
      "endDt": "2022-02-09T10:29:34.750Z",
      "totalAmount": 0
    }
  ],
  "meta": {
    "pagination": {
      "total": 0,
      "count": 0,
      "perPage": 0,
      "currentPage": 0,
      "totalPages": 0
    }
  }
}

Error Response Unexpected Error: Default

{
  "Code": 0,
  "Message": "string"
}

4. Data Models

Data Models define the structure of a JSON document.

4.1 Data

Data describe all the data related to the Traffic Reports. It contains data for the Billing Account, Country, Operator, Prices, etc.

Name Type Description
TrafficReportCollection object TrafficReportCollection object

TrafficReportCollection object properties:

Name Type Description
data (required) array Array of TrafficReport objects.
meta (required) object Meta

TrafficReport object properties:

Name Type Description
customerId integer Customer ID.
billingAccountId integer ID of Pricing Conditions Template.
billingAccountName string Name of Pricing Conditions Template.
countryId integer Country ID.
countryName string Name of the Country.
countryCode2 string Country code.
operatorId integer Operator ID.
operatorName string Operator name.
inSmsCnt integer Quantity per unit.
sellPrice number($float) Price per unit.
sellPriceSinceDt string($date-time) Selling price from a given date.
sellCurrency integer ID of selling price currency.
sellCurrencyCode string SellCurrency code.
mcc string Mobile country code.
mnc string Mobile network code.
startDt string($date-time) Start date.
endDt string($date‑time) End date.
totalAmount number($float) TotalAmount is price per unit multiplied by quantity per unit (totalAmount = sellPrice * inSmsCnt).

JSON Example

{
  "data": [
    {
      "customerId": 0,
      "billingAccountId": 0,
      "billingAccountName": "string",
      "countryId": 0,
      "countryName": "string",
      "countryCode2": "string",
      "operatorId": 0,
      "operatorName": "string",
      "inSmsCnt": 0,
      "sellPrice": 0,
      "sellPriceSinceDt": "2022-02-09T13:36:16.124Z",
      "sellCurrency": 0,
      "sellCurrencyCode": "string",
      "mcc": "string",
      "mnc": "string",
      "startDt": "2022-02-09T13:36:16.124Z",
      "endDt": "2022-02-09T13:36:16.124Z",
      "totalAmount": 0
    }
  ],
  "meta": {
    "pagination": {
      "total": 0,
      "count": 0,
      "perPage": 0,
      "currentPage": 0,
      "totalPages": 0
    }
  }
}
Name Type Description
ControlTrafficReportCollection object ControlTrafficReportCollection object

ControlTrafficReportCollection object properties:

Name Type Description
data (required) array Array of ControlTrafficReport objects.
meta (required) object Meta

ControlTrafficReport object properties:

Name Type Description
supplierId integer Supplier ID.
billingAccountId integer ID of Pricing Conditions Template.
billingAccountName string Name of Pricing Conditions Template.
countryId integer Country ID.
countryName string Name of the Country.
countryCode2 string Country code.
operatorId integer Operator ID.
operatorName string Operator name.
outSmsCnt integer Quantity per unit.
buyPrice number($float) Buying price per unit.
buyPriceSinceDt string($date-time) Buying price from a given date.
buyCurrency integer ID of buying price currency.
buyCurrencyCode string BuyCurrency code.
mcc string Mobile country code.
mnc string Mobile network code.
startDt string($date-time) Start date.
endDt string($date-time) End date.
totalAmount number($float) TotalAmount is price per unit multiplied by quantity per unit (totalAmount = buyPrice * outSmsCnt).

JSON Example

{
  "data": [
    {
      "supplierId": 0,
      "billingAccountId": 0,
      "billingAccountName": "string",
      "countryId": 0,
      "countryName": "string",
      "countryCode2": "string",
      "operatorId": 0,
      "operatorName": "string",
      "outSmsCnt": 0,
      "buyPrice": 0,
      "buyPriceSinceDt": "2022-02-09T13:36:16.133Z",
      "buyCurrency": 0,
      "buyCurrencyCode": "string",
      "mcc": "string",
      "mnc": "string",
      "startDt": "2022-02-09T13:36:16.133Z",
      "endDt": "2022-02-09T13:36:16.133Z",
      "totalAmount": 0
    }
  ],
  "meta": {
    "pagination": {
      "total": 0,
      "count": 0,
      "perPage": 0,
      "currentPage": 0,
      "totalPages": 0
    }
  }
}
Name Type Description
Error object Error object

Error object properties:

Name Type Description
code (required) integer($int32) Error code.
message (required) string Error message.

JSON Example

{
  "Code": 0,
  "Message": "string"
}

Error list

Response code Response body Message
401 NOT_AUTHORIZED Not authorized.
500 INT_APP_ERROR BULK_GATE instance not found.
500 INT_APP_ERROR Internal server error.
400 REQUEST_ERROR Query parameter: 'propertyName' error: 'error message'.
404 BULK_TRAFFIC_REPORT_API_V2:BULK_RATES_SETTINGS_NOTFOUND Bulk rates settings not found.

4.2 Meta

Meta contains the data for the number of rows and pages that have been received for an API call.

Name Type Description
collectionMeta object CollectionMeta object

CollectionMeta object properties:

Name Type Description
collectionMetaPagination object CollectionMetaPagination object

CollectionMetaPagination object properties:

Name Type Description
total (required) integer Total number of rows.
count (required) integer A number of rows in the current page.
perPage (required) integer The maximum rows per page.
currentPage (required) integer The current page number.
totalPages (required) integer Total number of pages.