API for Mobile Operators

From BlockChainTeleCom wiki
Jump to: navigation, search

API for BT Participants consists of client-server calls and callbacks on specific events.

Supported formats:

* HTTPS POST XML to Web API
* HTTPS PUT XML to Web API
* Direct cUrl call to Blockchain_API


Proactive commands for Offer Assignee

Add a new Offer

Web API:

PUT https://api.blockchaintele.com

<object>AddOffer</object>
<params>
  <provider_id>nnnn</provider_id>
  <offer_id>nnnn</offer_id>
  <offer_name>text</offer_name>
  <offer_desc>text</offer_desc>
  <volume_mb>nnnn</volume_mb>
  <volume_minutes>nnnn</volume_minutes>
  <price>nnnn</price>  
  <validity_period>nnnn</validity_period>
  <auto_renew>Y/N</auto_renew>
  <countries>text</countries>
  <trial_packages>nnnn</trial_packages>
  <category>text</category>
  <whitelist>nnnn,nnnn,nnnn</whitelist>
</params>

Response:

200 OK

Requirements:

object name of the API method
provider_id unique int64 Blockchain ID of the Offer Assignee
offer_id unique int64 ID assigned by the Offer Assignee
offer_name any text in English language. Recommended length: 32 symbols
offer_desc any text in English language. Multiple lines, delimited with CHR(10), are supported
volume_mb included volume in megabytes
volume_minutes [optional] included volume in minutes. '0' is voice services are not allowed
price cost of the Offer in SDR
validity period validity period of the Offer, starting with the first registration in your mobile network. The timeframe is one hour, so please specify correct duration: 1 day = 24 hours, 1 week = 168 hours, 1 month = 720 hours
auto_renew [optional] "Y", if you're able to publish Report transactions on the service consumption
countries list of countries, where your mobile profile is workable with the specified price. List should be presented in ISO3166-1 alpha-2 standard, via comma (","). If you have different prices for different countries, please create several Offers.
category "Telecom" for mobile services. Other categories are in progress
whitelist [optional] list of int64 Blockchain IDs (via comma) of mobile operators who can read the Offers and create Requests on the Offers. Example: 10, 25, 36

Direct Blockchain "Create Asset" API call is described in Blockchain_API section.



Cancel one of existing Offers

Web API:

PUT https://api.blockchaintele.com

<object>CancelOffer</object>
<params>
  <provider_id>nnnn</provider_id>
  <offer_id>nnnn</offer_id>
</params>

Response:

200 OK

Requirements:

object name of the API method
provider_id unique int64 Blockchain ID of the Offer Assignee
offer_id Offer ID assigned by the Offer Assignee

There is no API to update an Offer. Please cancel the Offer and create a new one in order to modify it.

Direct Blockchain "Update Asset" API call is described in Blockchain_API section.



Accept a received Request

If the Offer Assignee is ready to start servicing a new Request, it should accept it and provide all required data (such as IMSI or Activate code) for authorization of the end-user.

Web API:

PUT https://api.blockchaintele.com

<object>AcceptRequest</object>
<params>
  <provider_id>nnnn</provider_id>
  <btrequest_id>nnnn</btrequest_id>
  <service_data>{"imsi":"xx", "ki":"xx", "opc":"xx", "plmnlist":"xx", "apdu_addon":"xx"}</service_data>
</params>

Response:

200 OK

Requirements:

object name of the API method
provider_id unique int64 Blockchain ID of the Offer Assignee
btrequest_id ID of the Request received in "One of own Offers is selected" callback
service_data json with all required data to start using the service. Mobile profiles downloaded via OTA platform, require imsi, ki, opc and plmnlist values. This section is encrypted with Public PGP-key of the Request Issuer sent in "Start a new Request" transaction

Direct Blockchain "Accept Limit Order" API call is described in Blockchain_API section.



Report service consumption on a Request

Blockchain Telecom Ecosystem is based on "pay-per-usage" principle, so any Offer Assignee should publish a "Report" transaction in order to state that the service was consumed by end-user. After the "Report" transaction, the cost of the consumed service is transferred to the Offer Assignee wallet.

Web API:

PUT https://api.blockchaintele.com

<object>ReportRequest</object>
<params>
  <provider_id>nnnn</provider_id>
  <btrequest_id>nnnn</btrequest_id>
  <amount>2</amount>
  <memo>text</memo>
</params>

Response:

200 OK

Requirements:

object name of the API method
provider_id unique int64 Blockchain ID of the Offer Assignee
btrequest_id ID of the Request received in "One of own Offers is selected" callback
amount [optional] Amount of the consumed service, 1 by default. For example, if the Offer is like "100 MB, 0.1 SDR", then "Amount = 3" means that 300 MB were consumed, and 0.3 SDR are transferred to the Offer Assignee wallet
memo [optional] json with any tags to add comments to the Report

Direct Blockchain "Sell Asset" API call is described in Blockchain_API section.

Proactive commands for Request Issuer

Start a new Request

Web API:

PUT https://api.blockchaintele.com

<object>StartRequest</object>
<params>
  <request_id>nnnn</request_id>
  <btoffer_id>nnnn</btoffer_id>
  <amount>10</amount>
  <country_id>ISO-3166 format</country_id>
  <user_id>nnnn</user_id>  
  <digital_id_hash>hex</digital_id_hash>
  <local_ota>
    <msisdn>nnnn</msisdn>
    <kic>hex</kic>
    <kid>hex</kid>
    <user_name>John Smith</user_name>
    <user_data><organization/><address/></user_data>
    <user_memo>Auxiliary text memo</user_memo>
  </local_ota>
</params>

Response:

200 OK

Requirements:

object name of the API method
request_id Unique int-64 ID defined by the Request Issuer
btoffer_id Blockchain ID of the selected Offer
amount [optional] Amount of the selected Offer, 1 by default. For example, if the Offer is like "100 MB, 0.1 SDR", then "Amount = 100" means that 10 SDR are reserved on the Request Issuer wallet, and up to 10 GB are available for its subscriber
country_id [optional] which country was selected by end-user. The country is specified in ISO3166-1 alpha-2 standard
user_id Unique int-64 ID of the subscriber purchasing the service.
digital_id_hash Hash of the Digital Identity data in order to verify their correctness
local_ota Optional section containing subscriber and his SIM card details used to download purchased profile to subscriber's eSIM. Those data are kept locally and are not transferred through blockchain.
user_name User name to identify a subscriber
user_data Digital Identity of the subscriber, in <xml> format. This information is encrypted with the public key of the Offer Assignee, specified in the "Add a new Offer" API call

Direct Blockchain "Sell Asset" API call is described in Blockchain_API section.



Confirm that Request is ready-to-use

The API call confirms that everything is ready for the service consumption. For example, the mobile profile is successfully downloaded on the subscriber's SIM-card.

Web API:

PUT https://api.blockchaintele.com

<object>ConfirmRequest</object>
<params>
  <provider_id>nnnn</provider_id>
  <request_id>nnnn</request_id>
  <memo>text</memo>
</params>

Response:

200 OK

Requirements:

object name of the API method
provider_id unique int64 Blockchain ID of the Request Issuer
request_id Request ID assigned by the Request Issuer
memo [optional] json with any tags to add comments to the transaction



Rate an active Request

In order to build a transparent and reliable ecosystem, any end-user should have an option to evaluate a service provided by the Offer Assignee. It helps making an independent rating of quality of the services presented inside the Blockchain Telecom Ecosystem.

Web API:

PUT https://api.blockchaintele.com

<object>RateRequest</object>
<params>
  <provider_id>nnnn</provider_id>
  <request_id>nnnn</request_id>
  <request_rating>nn</request_rating>
  <memo>text</memo>
</params>

Response:

200 OK

Requirements:

object name of the API method
provider_id unique int64 Blockchain ID of the Request Issuer
request_id Request ID assigned by the Request Issuer
request_rating user's evaluation of the service (1 .. 10)
memo [optional] json with any tags to add comments to the transaction



Complete an active Request

Any Request could be completed by end-user or the Request Issuer. For example, when the subscriber returns to his/her home country, the Home mobile operator (Request Issuer) cancels the Request.

Web API:

PUT https://api.blockchaintele.com

<object>CompleteRequest</object>
<params>
  <error code=”0”>OK</error>
  <provider_id>nnnn</provider_id>
  <btrequest_id>nnnn</btrequest_id>
  <memo>text</memo>
</params>

Response:

200 OK

Requirements:

object name of the API method
error_code Reason why the Request is completed
provider_id unique int64 Blockchain ID of the Request Issuer
btrequest_id unique int64 Request ID assigned by the Blockchain Nodes
user_id [optional] MSISDN of the subscriber
memo [optional] json with any tags to add comments to the transaction

Direct Blockchain "Cancel Order" API call is described in Blockchain_API section.

Callbacks on events for Offer Assignee

One of own Offers is selected

When a "Start a new Request" transaction is created and validated onto Blockchain, the Offer Assignee receives the following API call:

PUT https://<Offer_Assignee_url>

<params>
  <provider_id>nnnn</provider_id>
  <offer_id>nnnn</offer_id>
  <btrequest_id>nnnn</btrequest_id>
  <request_id>nnnn</request_id>
  <user_id>nnnn</user_id>  
  <amount>5</amount>
  <service_data>Encrypted_hex</service_data>
  <digital_id_hash>hex</digital_id_hash>
</params>

Response:

200 OK

Description of the XML tags:

provider_id Unique Blockchain ID of the Request Issuer
offer_id Offer ID assigned by the Offer Assignee
btrequest_id Unique int-64 Request ID assigned by Blockchain Nodes
request_id int-64 Request ID assigned by Request Issuer
user_id MSISDN of the subscriber
amount [optional] Amount of the selected Offer, 1 by default. For example, if the Offer is like "100 MB, 0.1 SDR", then "Amount = 100" means that 10 SDR are reserved on the Request Issuer wallet, and up to 10 GB are available for the user
service_data The User's data encrypted with the Offer Assignee public key, specified in the "Add a new Offer" API call. Only the Offer Assignee can decrypt these data with own Private PGP-key. Decrypted data contain <user_id>, <user_name> and <user_data> sections, with Digital Identity in <xml> format, as described in "Start a new Request" API call
digital_id_hash Hash of the Digital Identity data in order to verify their correctness

Direct Blockchain "Get Limit Orders" API call is described in Blockchain_API section.



A Request is completed

When a "Complete an active Request" transaction is created and validated onto Blockchain, the Offer Assignee receives the following API call:

Web API:

PUT https://<Offer_Assignee_url>

<params>
  <error code=”0”>OK</error>
  <btrequest_id>nnnn</btrequest_id>
  <memo>text</memo>
</params>

Response:

200 OK

Description of the XML tags:

error_code Reason why the Request is completed
btrequest_id Unique int-64 Request ID assigned by Blockchain Nodes
memo [optional] json with any tags to add comments to the transaction

Callbacks on events for Request Issuer

New Offer is published on Blockchain

When a "Add a new Offer" transaction is created and validated onto Blockchain, all Participant receive the following API call:

PUT https://<Offer_Assignee_url>

<params>
  <btoffer_id>nnnn</btoffer_id>
  <offer_id>nnnn</offer_id>
  <provider_id>nnnn</provider_id>
  <offer_name>text</offer_name>
  <offer_desc>text</offer_desc>
  <volume_mb>nnnn</volume_mb>
  <volume_minutes>nnnn</volume_minutes>
  <price>nnnn</price>  
  <validity_period>nnnn</validity_period>
  <auto_renew>Y/</auto_renew>
  <countries>text</countries>
  <trial_packages>nnnn</trial_packages>
  <category>text</category>
</params>

Response:

200 OK

Description of the XML tags:

btoffer_id Unique int-64 Offer ID assigned by Blockchain Nodes
offer_id int64 Offer ID assigned by the Offer Assignee
provider_id Unique Blockchain ID of the Offer Assignee
other <xml> tags the same as for "Add a new Offer"

Direct Blockchain "List Assets" API call is described in Blockchain_API section.



One of existing Offers is canceled

When a "Cancel an existing Offer" transaction is created and validated onto Blockchain, all Participant receive the following API call:

PUT https://<Offer_Assignee_url>

<params>
  <btoffer_id>nnnn</btoffer_id>
</params>

Response:

200 OK
btoffer_id Unique int-64 Offer ID assigned by Blockchain Nodes

Direct Blockchain "List Assets" API call is described in Blockchain_API section.



A subscriber has selected one of third-party Offers

When a subscriber selects an Offer via build-in Bot Messenger or Bubbletone mobile app, the Home Operator receive the following API call:

PUT https://<Offer_Assignee_url>

<params>
  <btoffer_id>nnnn</btoffer_id>
  <offer_id>nnnn</offer_id>
  <amount>3</amount>
  <country_id>ISO3166</country_id>  
  <user_id>nnnn</user_id>  
  <retail_price>500</retail_price>
</params>

Response:

200 OK

Description of the XML tags:

btoffer_id Unique int-64 Offer ID assigned by Blockchain Nodes
offer_id If Aggregated Offer is selected, its Unique ID should be specified in this tag
amount [optional] Amount of the selected Offer, 1 by default. For example, if the Offer is like "100 MB, 0.1 SDR", then "Amount = 100" means that 10 SDR are reserved on the Request Issuer wallet, and up to 10 GB are available for the subscriber
country_id [optional] which country was selected by end-user. The country is specified in ISO3166-1 alpha-2 standard
user_id MSISDN of the subscriber
retail_price [optional] Retail price of the selected Offer

Alternatively http-GET request is supported:

https://<Offer_Assignee_url>/?btoffer_id=nnnn&country_id=CC&user_id=nnnn&amount=nnnn&retail_price=nnnn

Response:

* 200 OK
* 402 Payment Required.



A Request is updated by Offer Assignee

When the Offer Assignee accepts the Request, the Request Issuer receives the following API call:

Web API:

PUT https://<Offer_Assignee_url>

<params>
  <btrequest_id>nnnn</btrequest_id>
  <service_data>{"imsi":"xx", "ki":"xx", "opc":"xx", "plmnlist":"xx", "apdu_addon":"xx"}</service_data>
</params>

Response:

200 OK

Description of the XML tags:

btrequest_id unique int64 Request ID assigned by the Blockchain Nodes
service_data json with all required data to start using the service. Mobile profiles downloaded via OTA platform, require imsi, ki, opc and plmnlist values. This section is encrypted with Public PGP-key of the Request Issuer sent in "Start a new Request" transaction, so the Request Issuer can decrypt these data with own Private PGP-key
amount Amount of the consumed service. For example, if the Offer is like "100 MB, 0.1 SDR", then "Amount = 3" means that 300 MB were consumed, and 0.3 SDR are transferred to the Offer Assignee wallet

Direct Blockchain "Get Account History" API call is described in Blockchain_API section.



A Request is reported by Offer Assignee

When the Offer Assignee publishes a "Report" transaction on the Request, the Request Issuer receives the following API call:

Web API:

PUT https://<Offer_Assignee_url>

<params>
  <btrequest_id>nnnn</btrequest_id>
  <amount>2</amount>
  <service_data>{"details":"xx"}</service_data>
</params>

Response:

200 OK

Description of the XML tags:

btrequest_id unique int64 Request ID assigned by the Blockchain Nodes
amount Amount of the consumed service. For example, if the Offer is like "100 MB, 0.1 SDR", then "Amount = 3" means that 300 MB were consumed, and 0.3 SDR are transferred to the Offer Assignee wallet
service_data json with all details regarding the Report transaction. This section is encrypted with Public PGP-key of the Request Issuer sent in "Start a new Request" transaction, so the Request Issuer can decrypt these data with own Private PGP-key

Direct Blockchain "Get Account History" API call is described in Blockchain_API section.




A Request is completed

When a "Complete an active Request" transaction is created and validated onto Blockchain, the Request Issuer receives the following API call:

Web API:

PUT https://<Offer_Assignee_url>

<params>
  <error code=”0”>OK</error>
  <btrequest_id>nnnn</btrequest_id>
  <refund_sum>nnnn.nn</refund_sum>
  <memo>text</memo>
</params>

Response:

200 OK

Description of the XML tags:

error_code Reason why the Request is completed
btrequest_id unique int64 Request ID assigned by the Blockchain Nodes
refund_sum [optional] Unlocked Sum for the Request Issuer
memo [optional] json with any tags to add comments to the transaction

Call Flow for main cases

Easy start for Offer Assignee

It takes just 10 minutes to publish own Offers onto Blockchain and upload mobile profiles with pre-activated packages of mobile services:



Easy start for Request Issuer

Usage of build-in Bot Messenger or Bubbletone mobile app simplifies all integration process dramatically. The Request Issuer should make following steps:

1. Web-account: customize Offers (localize description and setup retail prices in local currency) for its subscribers
2. Web-account: customize Bot Messenger under section "Settings / Localization"
3. Web-account: input settings of own SMPP server to provide downloading of encrypted SMS with mobile profiles
4. Web-account: upload MSISDN's of subscribers and OTA keys of SIM-cards for built-in OTA platform
5. Support an easy http-GET Credit Control request, with response 200 (OK) / 402 (Payment is required). Details are described at "A subscriber has selected one of third-party Offers"
6. Distribute Multi-Account SIM-cards among subscribers.

WikiLiteIntegration.png



Integration with own Provisioning Control

That's the most optimal case for any Offer Assignee:

Integration with Provisioning Control.png

1. New Offers are published via Web-account
2. When a "Start a new Request" transaction is created and validated onto Blockchain, the Offer Assignee receives the "One of own Offers is selected" API call
3. If the Offer Assignee is ready to start servicing this Request, it makes "Accept a received Request" API call, with "service_data" section encrypted with the public PGP-key of the Request Issuer
4. When the service is started using by end-user, the Offer Assignee publishes "Report" transaction by making the "Report service consumption on a Request" API call, with details of the service consumption
5. All limits and validity period are controlled by the Billing system of the Offer Assignee.



Integration with own UI (mobile app, web account, etc)

Any Request Issuer can use own user interfaces for communication with own subscribers. In order to provide access to multiple Offers published in Blockchain Telecom ecosystem, the Issuer should implement the following business logic:


Integration with own UI.png

1. New Offers and Canceled Offers are updated via "New Offer is published on Blockchain" and "One of existing Offers is canceled" callbacks. It's important to process these events to have an actual list of Offers
2. These Offers are represented to subscribers via own interfaces, with own descriptions and retail prices
3. On selection an Offer, the Request Issuer should make a "Start a new Request" call, with the subscriber's Digital Identity, encrypted with the Offer Assignee public PGP-key
4. When the Offer Assignee accepts the Request, the Request Issuer receives "A Request is accepted by Offer Assignee API call, with details regarding the service such as mobile profile data, activation code and so on
5. The last step is to provide subscriber with the information required for the service usage. Now she/he is ready to be server by the Offer Assignee.


Billing and Cash Flow

BTBillingDiagram.png

Direct Billing and "Pay-per-Usage" principle provide easy implementation for Participants and fair policy for subscribers. It means that Assignee has guarantee payment for its services, and Issuer pays for consumed services only.

It allows building very flexible packages for subscribers, with combination of mobile services from multiple Operators and of value-added services from multiple Providers. Major cases are described at "Use Cases" section.

Every time a new Request is created, appropriate amount of SDRs is reserved (blocked) on the Issuer's wallet. It provides payment guarantee for the service, so Assignee is able to start servicing the subscriber directly. It's necessary to publish "Report" transaction to notify that the customer was served, otherwise the reserved sum is unblocked after expiration of the validity period and become available for other payments.


How to detect an indecent Participant

There could be some Providers who publish "Report" transaction without servicing the customers. But there is an effective way to detect them in short terms:

  1. Issuer creates a new Request with "faked" User ID. It means that such user is not able to start consuming the service
  2. If Assignee publishes "Report" transaction for this User, it means that indecent Provider has been detected. As a result, such Provider could be fined or even eliminated by voting of "Report" BT members.

So the only way to keep own reputation is to be honest with other Participants. Such method helps building reliable and trusted community.