Supplier Rates Import API

1. Introduction

The Supplier Rates Import API can be used to programmatically create and activate a Supplier Price List Range for an existing Supplier Price List with a collection of the Price List Items describing the Price for a certain Country and Operator combination.

This API belongs to the Bulk Price List domain. The subject domain of an endpoint URL is:

https://api{separator}{platform_domain}/bulk/pricelists

Note: A domain is presented with placeholders as https://api{separator}{platform_domain}, where {separator} can be a dot (.) or a hyphen (-). Please, replace it with your actual platform domain name.

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

2. Methods Overview

3. Methods Details

POST/sms/buying/{plId}/ranges-import

Adds a Gate Price List Range and Items.Up

Method Overview

The method is used to add a Gate Price List Range and Items.

A fully valid request will create a new Date Range with given status if all Price List items are valid. A reason for non-valid items can be, that a country/operator combination is not valid. In that case, the endpoint returns a 409 Status Code with a full object including error message for invalid items.

To create a Date Range even with not having 100% valid items, but at least one, you can add a query parameter importOnlyIfAllValid=false (default for an omitted parameter is true). In that case, the endpoint returns a 201 Status Code with a full object, including error message for invalid (not created) items.

URL Parameters

Name	Type	Description
plid (required)	string (path)	Gate Price List ID to get.
importOnlyIfAllValid	string (query)	Only when all items are valid, a new range will be created. If there is one not valid item, no new range will be created and 409 status will be returned with input object enriched with comments about items (warnings and errors). If set to false, all valid items (at least one) will be imported and new range created. 201 status will be returned with input object enriched with comments about items (warnings and errors). Those items with errors are not imported! If there are no valid items, no new range will be created. And 409 status will be returned with input object enriched with comments about items (warnings and errors). Default value: true.
post data (required)	object	The status can be either imported or omitted. The 'startDate' variable has the following format: `YYYY-MM-DDTHH:MM:SSZ` and 'endDate' is set automatically to unlimited. 'comment' and 'importReport' can be omitted.

Data Parameters

Example JSON body parameters:

  {
    "startDate": "2050-01-01T00:00:00Z",
    "comment": "comment x",
    "importReport": "abc",
    "items": [
      {
        "status": "active",
        "price": 1.1,
        "comment": "comment 1",
        "country": {
          "countryIsoCode": 756,
          "mcc": "228"
        },
        "operator": {
          "mcc": "228",
          "mnc": "12"
        }
      },
      {
        "status": "active",
        "price": 1.1,
        "comment": "comment 2",
        "country": {
          "countryName": "All Countries"
        },
        "operator": {
          "operatorName": "All Networks"
        }
      },
      {
        "status": "active",
        "price": 1.1,
        "comment": "comment 3",
          "country": {
            "countryCode3": "ZWE"
          },
        "operator": {
          "mcc": "648",
          "mnc": "04"
        }
      }
    ]
  }

Items-list: status, price, country, operator. Country and Operator are separated objects in the list and has their own fields that are described in the tables below.

Name	Type	Description
GateImportItemsWO	object	Gate import object.
Status	string	Can be either in import or active. Default value 'R' = draft will be used.
Price	number($float)	Price.
Country	object	The object must have at least one parameter out of countryName, countryCode2, countryCode3 or countryIsoCode.
operator	object	Object must have at least - (mcc and mnc) or operator name. For further information check the table below.

Gate Import country WO object is related to the country of the Operator.

Name	Type	Description
GateImportCountryWO	object	Gate import object for the country.
countryIsoCode	integer	Country code.
mcc	string	Mobile country code.
countryCode2	string	Country code 2.
countryCode3	string	Country code 3.
countryName	string	Name of the country.

The object must have at least one parameter out of countryName,countryCode2, countryCode3 or countryIsoCode. We recommend using only one of the possible parameters for country and operator and omit the unused (see the example).

Gate Import operator WO: This object is related to the operator and it's country code and network code.

Name	Type	Description
GateImportOperatorWO	object	Gate import object for the operator.
mcc	string	Mobile country code.
mnc	string	Mobile network code.
operatorName	string	Name of the operator.

Success Response: 200 Gate Price List Range Added

Example

{
  "startDate": "string",
  "endDate": "string",
  "comment": "string",
  "status": "string",
  "importReport": "string",
  "items": [
    {
      "status": "string",
      "price": 0,
      "country": {
        "countryIsoCode": 0,
        "mcc": "string",
        "countryCode2": "string",
        "countryCode3": "string",
        "countryName": "string"
      },
      "operator": {
        "mcc": "string",
        "mnc": "string",
        "operatorName": "string"
      }
    }
  ],
  "operatorJoin": "off"
}

Error Response 409: Gate Price List Range not added as there are wrong input parameters

Example

{
  "startDate": "string",
  "endDate": "string",
  "comment": "string",
  "status": "string",
  "importReport": "string",
  "items": [
    {
      "status": "string",
      "price": 0,
      "country": {
        "countryIsoCode": 0,
        "mcc": "string",
        "countryCode2": "string",
        "countryCode3": "string",
        "countryName": "string"
      },
      "operator": {
        "mcc": "string",
        "mnc": "string",
        "operatorName": "string"
      }
    }
  ],
  "operatorJoin": "off"
}

The available error codes are listed below:

"PRICELIST_RANGE_ITEM_IMPORT_COUNTRY_IS_MISSING"
"PRICELIST_RANGE_IMPORT_COUNTRY_IS_WRONG"
"PRICELIST_RANGE_IMPORT_COUNTRY_NOT_FOUND"
"PRICELIST_RANGE_ITEM_IMPORT_OPERATOR_IS_MISSING"
"PRICELIST_RANGE_ITEM_IMPORT_OPERATOR_IS_AMBIGIOUS"
"PRICELIST_RANGE_ITEM_IMPORT_OPERATOR_MCC_IS_MISSING"
"PRICELIST_RANGE_ITEM_IMPORT_OPERATOR_MNC_IS_MISSING"
"PRICELIST_RANGE_ITEM_IMPORT_OPERATOR_MCC_IS_WRONG"
"PRICELIST_RANGE_ITEM_IMPORT_OPERATOR_IS_WRONG"
"PRICELIST_RANGE_ITEM_IMPORT_ALLCOUNTRY_IS_ALREADY_IN_USE"
"PRICELIST_RANGE_ITEM_IMPORT_OPERATOR_IS_AMBIGIOUS"
"PRICELIST_RANGE_ITEM_STATUS_IS_WRONG"
"PRICELIST_RANGE_ITEM_IMPORT_STATUS_IS_MISSING"
"PRICELIST_RANGE_ITEM_PRICE_IS_MISSING"
"PRICELIST_RANGE_ITEM_IMPORT_PRICE_IS_WRONG"
"PRICELIST_RANGE_ITEM_IMPORT_SAME_OPERATOR_IN_MULTIPLE_ITEMS"
"PRICELIST_RANGE_ITEM_IMPORT_SAME_OPERATOR_DIFFERENT_PRICE"

Error Response Unexpected Error: Default

Example

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

POST/v2/sms/buying/{plid}/ranges/{rngid}/activate

Activates a Date Range.Up

Method Overview

The method is used to activate previously created Supplier Price List Data Range.

Authorization privilege needed for this endpoint: bulk-supplier-pricelist.

Manage Ranges in draft mode that have startDate in future will be activated.
EndDate of the actual active range will be set to be endDate of the new range.
StartDate of new range will be set to be EndDate of actual active range.
Ranges in Draft and Imported status can be activated.
When activating a range, approval_status will be set to 'manually_approved' and approval_status_dt will be set to the time of change.

URL Parameters

Name	Type	Description
plid	string	Gate Price List ID.
rngid	string	Gate Price List range ID.

Success Response: 200 Gate Price List Range found

Example

{
  "id": "string",
  "gatePriceListId": "string",
  "startDate": "string",
  "endDate": "string",
  "currencyId": 0,
  "currencyCode": "string",
  "baseCurrency": 0,
  "baseCurrencyCode": "string",
  "status": "string",
  "comment": "string",
  "importReport": "string",
  "isOverlaping": true,
  "overlaping": [
    {
      "startDate": "string",
      "endDate": "string"
    }
  ],
  "input": {
    "startDate": "string",
    "endDate": "string",
    "comment": "string",
    "status": "string",
    "importReport": "string",
    "items": [
      {
        "status": "string",
        "price": 0,
        "country": {
          "countryIsoCode": 0,
          "mcc": "string",
          "countryCode2": "string",
          "countryCode3": "string",
          "countryName": "string"
        },
        "operator": {
          "mcc": "string",
          "mnc": "string",
          "operatorName": "string"
        }
      }
    ],
    "operatorJoin": "off"
  }
}

Error Response Unexpected Error: Default

Example

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

4. Questions and Answers

Q: "...As I understand this API should be used to upload rates per supplier. I don't see option to specify the supplier ID / Name that should match suppliers already in your platform. There is also no place for currency of the rate. "

A: You don't need to specify both parameters, as the import is done in a previously via UI created Supplier Price List (in Bulk App, under Rates Manager/Suppliers/SMS Gate Price List).
This defines Supplier and Currency of Price List, you then can import rates and create a new date range from them.
(Explications on how Rates Manager and Date Ranges Management in Application work are available in our User Guides).

You can get the needed PLID (Price List ID) you need by going to Rates Manager/Suppliers/SMS Gate Price List in your Bulk SMS Application.

Once there you need to open the price list column link. You will see an URL like this:

/en/rates-manager/suppliers/pricelist/{PLID}/range?main:paging=1,10

Supplier Rates Import API

1. Introduction

2. Methods Overview

3. Methods Details

Method Overview

URL Parameters

Data Parameters

Success Response: 200 Gate Price List Range Added

Error Response 409: Gate Price List Range not added as there are wrong input parameters

Error Response Unexpected Error: Default

Method Overview

URL Parameters

Success Response: 200 Gate Price List Range found

Error Response Unexpected Error: Default

4. Questions and Answers

Information about cookies