Low-Level API JSON

From BlockChainTeleCom wiki
Revision as of 05:47, 31 July 2018 by Opravdin (talk | contribs)
Jump to: navigation, search

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

Supported formats:

* HTTPS POST JSON to Web API
* HTTPS PUT JSON to Web API
* Direct cUrl call to Blockchain_API
* Recommended json style: "snake_case", lower case only


Proactive commands

Create a new Service

"object": "create_service"
"params": {"account_id": 20, "ptservice_id": 196, "memo": "{\"Name\":\"Service_196\"}", "whitelist_accounts":[25, 30]}

Response:

200 OK

Requirements:

object name of the API method
account_id unique int64 Blockchain ID of the Offer Assignee
ptservice_id int64 ID of the Service assigned by the Offer Assignee. It should be unique among all services created by the participant
memo description of the Service as json, with multiple tags. Language for description: English
whitelist [optional] list of int64 Blockchain IDs (via comma) of other participants who can read the Service and create Requests based on the Service. Example: 10, 25, 36
Each Service can contain multiple Offers (Assets).




Update one of existing Services

"object": "update_service"
"params": {"account_id": 20, "ptservice_id": 196, "memo": "{\"Name\":\"Service_196\"}", "whitelist_accounts":[25, 30]}

Response:

200 OK

Requirements:

object name of the API method
account_id unique int64 Blockchain ID of the Offer Assignee
ptservice_id int64 ID of the Service assigned by the Offer Assignee when the Service was created
memo description of the Service as json, with multiple tags. Language for description: English
whitelist [optional] list of int64 Blockchain IDs (via comma) of other participants who can read the Service and create Requests based on the Service. Example: 10, 25, 36




Create a new Offer (Asset)

"object": "create_asset"
"params": {"account_id": 20, "ptservice_id": 196, "ptasset_id": 850, "memo": "{\"Name\":\"Asset_850\"}", "whitelist_accounts":[25, 30]}

Response:

200 OK

Requirements:

object name of the API method
account_id unique int64 Blockchain ID of the Offer Assignee
ptservice_id int64 ID of the Service assigned by the Offer Assignee when the Service was created. Each Asset should be assigned to a Service
ptasset_id int64 ID of the Asset assigned by the Offer Assignee. It should be unique among all assets created by the participant
memo description of the Asset as json, with multiple tags. Language for description: English
whitelist [optional] list of int64 Blockchain IDs (via comma) of other participants who can read the Asset and create Requests based on the Service. Example: 10, 25, 36




Update one of existing Offers (Assets)

"object": "update_asset"
"params": {"account_id": 20, "ptasset_id": 850, "memo": "{\"Name\":\"Asset_850\"}", "whitelist_accounts":[25, 30]}

Response:

200 OK

Requirements:

object name of the API method
account_id unique int64 Blockchain ID of the Offer Assignee
ptasset_id int64 ID of the Asset assigned by the Offer Assignee when the Asset was created
memo description of the Asset as json, with multiple tags. Language for description: English
whitelist [optional] list of int64 Blockchain IDs (via comma) of other participants who can read the Asset and create Requests based on the Service. Example: 10, 25, 36




Create a new Bid Request

"object": "create_bid_request"
"params": {"account_id": 20, "ptrequest_id": 650, "bcasset_ids":[850, 930], "memo": "{\"Name\":\"Request_650\"}", "timeout_sec": 600}

Response:

200 OK

Requirements:

object name of the API method
account_id unique int64 Blockchain ID of the Participant who creates the Requests
ptrequest_id int64 ID of the Request assigned by the Participant. It should be unique among all its requests
bcasset_ids list of int64 IDs of the Assets (via comma) created by other participants
memo description of the Request as json, with multiple tags. Language for description: English
timeout_sec expiration period of the Request, in seconds
Short-term request on one or several assets from one or several service-providers in order to receive bids from them.




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>
  <btoffer_id>nnnn</btoffer_id>
  <user_id>nnnn</user_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
btoffer_id Blockchain ID of the selected Offer received in "New Offer is published on Blockchain" callback
btrequest_id ID of the Request received in "One of own Offers is selected" callback
user_id [optional] MSISDN of the subscriber
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>
  <btoffer_id>nnnn</btoffer_id>
  <user_id>nnnn</user_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
btoffer_id Blockchain ID of the selected Offer received in "New Offer is published on Blockchain" callback
user_id [optional] MSISDN of the subscriber
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>
  <provider_id>nnnn</provider_id>
  <request_id>nnnn</request_id>
  <btoffer_id>nnnn</btoffer_id>
  <offer_id>nnnn</offer_id>
  <amount>10</amount>
  <country_id>ISO-3166 format</country_id>
  <publickey>hex</publickey>
  <user_id>nnnn</user_id>  
  <user_name>text</user_name>
  <user_data>xml</user_data>  
  <digital_id_hash>hex</digital_id_hash>
</params>

Response:

200 OK

Requirements:

object name of the API method
provider_id unique int64 Blockchain ID of the Request Issuer
request_id Unique int-64 ID defined by the Request Issuer
btoffer_id Blockchain ID of the selected Offer
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 its subscriber
country_id [optional] which country was selected by end-user. The country is specified in ISO3166-1 alpha-2 standard
publickey Public PGP-key of the Request Issuer to encrypt service_data section in the "Accept a received Request" API call
user_id MSISDN of the subscriber
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
digital_id_hash Hash of the Digital Identity data in order to verify their correctness

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>
  <btrequest_id>nnnn</btrequest_id>
  <user_id>nnnn</user_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
btrequest_id Blockchain ID of the Request received in "A Request is accepted by Offer Assignee" callback
user_id [optional] MSISDN of the subscriber
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>
  <btrequest_id>nnnn</btrequest_id>
  <user_id>nnnn</user_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
btrequest_id Blockchain ID of the Request received in "A Request is accepted by Offer Assignee" callback
user_id [optional] MSISDN of the subscriber
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>
  <user_id>nnnn</user_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 Blockchain ID of the Request received in "A Request is accepted by Offer Assignee" callback
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>
  <btoffer_id>nnnn</btoffer_id>
  <btrequest_id>nnnn</btrequest_id>
  <request_id>nnnn</request_id>
  <publickey>hex</publickey>
  <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:

btoffer_id Unique int-64 Offer ID assigned by Blockchain Nodes
btrequest_id Unique int-64 Request ID assigned by Blockchain Nodes
request_id int-64 Request ID assigned by Request Issuer
provider_id Unique Blockchain ID of the Request Issuer
publickey Public PGP-key of the Request Issuer to encrypt service_data section in the "Accept a received Request" API call
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>
  <user_id>nnnn</user_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
user_id [optional] MSISDN of the subscriber
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>
  <publickey>hex</publickey>
</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 or 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>
  <btoffer_id>nnnn</btoffer_id>
  <service_data>{"imsi":"xx", "ki":"xx", "opc":"xx", "plmnlist":"xx", "apdu_addon":"xx"}</service_data>
  <amount>0</amount>
</params>

Response:

200 OK

Description of the XML tags:

btrequest_id unique int64 Request ID assigned by the Blockchain Nodes
btoffer_id Unique int-64 Offer 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 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>
  <user_id>nnnn</user_id>
  <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
user_id [optional] MSISDN of the subscriber
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.