Activating the overspend safeguard

Discover how you can activate your overspend safeguard option

This guide shows you how to activate your overspend safeguard option and later consult its state.

Endpoints

Below are all APIs url that you will need for this guide:

Transatel APIs	URL
Authentication	https://api.transatel.com/authentication/api
OCS Inventory	https://api.transatel.com/ocs/inventory/api
OCS Subscriptions	https://api.transatel.com/ocs/subscriptions/api

All Transatel APIs are available through our unique API gateway https://api.transatel.com

1. API Authentication

First thing first, let's get your access token by following the getting started guide!

2. Activate the overspend safeguard option

Now that you are authenticated, and you have an access token, let's use it to activate the option for one of your subscribers.

To do so, we will use the OCS Subscriptions API.

The below example shows how to activate the overspend safeguard option:

curl --location --request POST \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJidXNpbmVzc19lbnRpdGllcyI6WyJBbnkiXSwicHJpbmNpcGFsIjoib2NzLXN1YnNjcmlwdGlvbi1vcmRlci1tYW5hZ2VyIiwic2NvcGUiOlsiQ0FUQUxPR19QUk9EVUNUU19SRUFEX1RFQ0hOSUNBTCIsIkNBVEFMT0dfUFJPRFVDVFNfUkVBRCIsIlVTRVJfUkVBRCIsIklOVkVOVE9SWV9TVUJTQ1JJUFRJT05TX1JFQUQiXSwiZXhwIjoxNjE3MjYwNTYxLCJhdXRob3JpdGllcyI6WyJST0xFX0lOVEVSTkFMX1NZU1RFTSJdLCJqdGkiOiJmOTYwNTFmNS05ZmQzLTQxMDEtYjNkZC0xZjY2Y2Q2MWUzZjIiLCJjbGllbnRfaWQiOiJvY3Mtc3Vic2NyaXB0aW9uLW9yZGVyLW1hbmFnZXIifQ.KBTlltd459_4kPV0O3OfsBTFGBtoqRxG65o_NohK1U7IuJAvIjAa8Fj4Qon1ptFrrTR5M2o8l0f9Dl0D7r0Us6Ej6OsVlFXfQKUiXwVytNUTP7POB6l56Svc5CaVqkXgFKyt7_8h6Ii6R_RteujtSzJSWX7zeLSeemxsxKNtHLLIS_HLyNdQyIsVCZWRfFhdPJVQId_p6B08_A54sAwhrT7qssSbtpG1nGzdqsHdFfaqJt9ABhPedatHNlwcWtCnFthrOrD2rv0Yf8OnRLnt-ZWtypr0cqm6U-brtZeBMhcxgzF4afKlJbKN3K3drPJRrRPjL8L9bf2YvzsDWxY5lA' \
    --data \
    "{ 
      \"bind\": {
        \"msisdn\": \"33612345678\"
      },
      \"source\": \"api\",
      \"state\": \"active\",
      \"cutOff\": {
        \"currentLimit\": \"5000\",
        \"unit\": \"CENTS\",
      },
      \"transactionReference\": \"RX12345ZVGT\"
    }" \
    'https://api.transatel.com/ocs/subscriptions/api/orders/options/overspendSafeguard'

Above are highlighted the main information to provide to the API:

Authorization header: This is where you provide the previously retrieved access_token
msisdn: The mobile phone number of the subscriber
state: The target state you want to apply
currentLimit: The cutoff limit amount

If successful, the response returned will be as follows:

HTTP/1.1 201 Created
Content-Type: application/json
{
  "bind": {
    "msisdn": "33612345678"
  },
  "orderReference": "SUBIcuMJjmmcSOhm2i57dsSA",
  "source": "api",
  "status": "done",
  "state": "active",
  "submissionDate": "2019-08-24T14:15:22Z",
  "transactionReference": "RX12345ZVGT"
}

A successful response returns a HTTP/1.1 201 Created, meaning that your order was successfully processed and the overspend safeguard option state was successfully changed.

3. Retrieve the state of the overspend safeguard option (optional)

Now that you have activated the option, let's try to retrieve the state of the overspend safeguard option of this subscriber.

To do so, we will use OCS Inventory API.

The below example shows how to retrieve the overspend safeguard option for a given subscriber:

curl --location --request GET \
    --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJidXNpbmVzc19lbnRpdGllcyI6WyJBbnkiXSwicHJpbmNpcGFsIjoib2NzLXN1YnNjcmlwdGlvbi1vcmRlci1tYW5hZ2VyIiwic2NvcGUiOlsiQ0FUQUxPR19QUk9EVUNUU19SRUFEX1RFQ0hOSUNBTCIsIkNBVEFMT0dfUFJPRFVDVFNfUkVBRCIsIlVTRVJfUkVBRCIsIklOVkVOVE9SWV9TVUJTQ1JJUFRJT05TX1JFQUQiXSwiZXhwIjoxNjE3MjYwNTYxLCJhdXRob3JpdGllcyI6WyJST0xFX0lOVEVSTkFMX1NZU1RFTSJdLCJqdGkiOiJmOTYwNTFmNS05ZmQzLTQxMDEtYjNkZC0xZjY2Y2Q2MWUzZjIiLCJjbGllbnRfaWQiOiJvY3Mtc3Vic2NyaXB0aW9uLW9yZGVyLW1hbmFnZXIifQ.KBTlltd459_4kPV0O3OfsBTFGBtoqRxG65o_NohK1U7IuJAvIjAa8Fj4Qon1ptFrrTR5M2o8l0f9Dl0D7r0Us6Ej6OsVlFXfQKUiXwVytNUTP7POB6l56Svc5CaVqkXgFKyt7_8h6Ii6R_RteujtSzJSWX7zeLSeemxsxKNtHLLIS_HLyNdQyIsVCZWRfFhdPJVQId_p6B08_A54sAwhrT7qssSbtpG1nGzdqsHdFfaqJt9ABhPedatHNlwcWtCnFthrOrD2rv0Yf8OnRLnt-ZWtypr0cqm6U-brtZeBMhcxgzF4afKlJbKN3K3drPJRrRPjL8L9bf2YvzsDWxY5lA' \
    'https://api.transatel.com/ocs/inventory/api/subscriptions/options/overspendSafeguard?msisdn=33612345678'

Above are highlighted the main information to provide to the API:

Authorization header: This is where you provide the previously retrieved access_token
msisdn: The mobile phone number of the subscriber

If successful, the response returned will be as follows:

HTTP/1.1 200 OK
Content-Type: application/json
{
  "state": "active",
  "cutOff": {
    "currentLimit": 5000,
    "nextLimit": 5000,
    "unit": "CENTS",
    "currency": "EUR",
    "spent": 0,
    "reached": false
  },
  "nextRenewalDate": "2023-05-19T13:30:00Z",
  "eligibleStates": [
    "inactive"
  ]
}

A successful response returns a HTTP/1.1 200 OK, with the details of the overspend safeguard option. The eligibleStates array contains all possible states you can switch the option to.

What to do next?

Learn more about our OCS APIs by checking their overview & API references: