Difference between revisions of "Low-Level API JSON"

From BlockChainTeleCom wiki
Jump to: navigation, search
Line 256: Line 256:
  
  
<div id="Anchor_Accept_Request"></div>
+
<div id="Anchor_Accept_Order"></div>
=== Accept a received Request ===
+
=== Accept a received Order ===
  
If the [[Terms_and_Conditions#Anchor_Definitions|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.
+
  "object": "accept_order"
 
+
"params": {"account_id": 20, "bcorder_id": 2450, "memo": "{\"accept_code\":\"Order_2450\"}"}
'''Web API:'''
 
 
 
PUT <nowiki>https://api.blockchaintele.com</nowiki>
 
 
 
  <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:  
 
Response:  
Line 282: Line 270:
 
|name of the API method
 
|name of the API method
 
|-
 
|-
|'''provider_id'''
+
|'''account_id'''
|unique int64 Blockchain ID of the [[Terms_and_Conditions#Anchor_Definitions|Offer Assignee]]
+
|unique int64 Blockchain ID of the Participant who creates the Requests
 
|-
 
|-
|'''btoffer_id'''
+
|'''bcorder_id'''
|Blockchain ID of the selected Offer received in [[API_for_Mobile_Operators#New_Offer_is_published_on_Blockchain|"New Offer is published on Blockchain"]] callback
+
|int64 ID of the Order to be accepted
|-
 
|'''btrequest_id'''
 
|ID of the Request received in [[API_for_Mobile_Operators#One_of_own_Offers_is_selected|"One of own Offers is selected"]] callback
 
|-
 
|'''user_id'''
 
|[optional] [https://en.wikipedia.org/wiki/MSISDN 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 [[API_for_Mobile_Operators#Anchor_Start_Request|"Start a new Request"]] transaction
 
 
|-
 
|-
 +
|'''memo'''
 +
|description of the Order acceptance as json, with multiple tags. Language for description: English
 
|}
 
|}
  
Direct [[Blockchain_API#accept_limit_order|'''Blockchain "Accept Limit Order" API call''']] is described in [[Blockchain_API]] section.
+
After acceptance, the reserved sum is blocked on the Request Issuer account until "Report" transaction, "Cancel" transaction or the order expiration.
  
  
 
----
 
----
  
<div id="Anchor_Report_Request"></div>
 
 
=== 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 <nowiki>https://api.blockchaintele.com</nowiki>
 
 
<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:
 
{| class="wikitable" style="color:black; background-color:#FFFFFF; width:500px; cellpadding="10"
 
|'''object'''
 
|name of the API method
 
|-
 
|'''provider_id'''
 
|unique int64 Blockchain ID of the [[Terms_and_Conditions#Anchor_Definitions|Offer Assignee]]
 
|-
 
|'''btrequest_id'''
 
|ID of the Request received in [[API_for_Mobile_Operators#One_of_own_Offers_is_selected|"One of own Offers is selected"]] callback
 
|-
 
|'''btoffer_id'''
 
|Blockchain ID of the selected Offer received in [[API_for_Mobile_Operators#New_Offer_is_published_on_Blockchain|"New Offer is published on Blockchain"]] callback
 
|-
 
|'''user_id'''
 
|[optional] [https://en.wikipedia.org/wiki/MSISDN 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_API#sell_asset|'''Blockchain "Sell Asset" API call''']] is described in [[Blockchain_API]] section.
 
 
== Proactive commands for [[Terms_and_Conditions#Anchor_Definitions|Request Issuer]] ==
 
 
<div id="Anchor_Start_Request"></div>
 
=== Start a new Request ===
 
 
'''Web API:'''
 
  
PUT <nowiki>https://api.blockchaintele.com</nowiki>
+
<div id="Anchor_report_Order"></div>
 +
=== Report transaction: service is provided for the Order ===
  
  <object>StartRequest</object>
+
  "object": "accept_order"
  <params>
+
  "params": {"account_id": 20, "bcorder_id": 2450, "amount": 2, "served_sum": 2.5, "memo": "{\"accept_code\":\"Order_2450\"}"}
  <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:  
 
Response:  
Line 386: Line 300:
 
|name of the API method
 
|name of the API method
 
|-
 
|-
|'''provider_id'''
+
|'''account_id'''
|unique int64 Blockchain ID of the [[Terms_and_Conditions#Anchor_Definitions|Request Issuer]]
+
|unique int64 Blockchain ID of the Participant who creates the Requests
|-
 
|'''request_id'''
 
|Unique int-64 ID defined by the Request Issuer
 
 
|-
 
|-
|'''btoffer_id'''
+
|'''bcorder_id'''
|Blockchain ID of the selected Offer
+
|int64 ID of the Order to be served
 
|-
 
|-
|'''offer_id'''
 
|If Aggregated Offer is selected, its Unique ID should be specified in this tag
 
|- 
 
 
|'''amount'''
 
|'''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
+
|(optional) int64 amount of the provided assets, 1 by default
|-
 
|'''country_id'''
 
|[optional] which country was selected by end-user. The country is specified in [https://en.wikipedia.org/wiki/ISO_3166-1 ISO3166-1 alpha-2] standard
 
|-
 
|'''publickey'''
 
|Public PGP-key of the Request Issuer to encrypt service_data section in the [[API_for_Mobile_Operators#Anchor_Accept_Request|"Accept a received Request"]] API call
 
|-
 
|'''user_id'''
 
|[https://en.wikipedia.org/wiki/MSISDN 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 [[API_for_Mobile_Operators#Anchor_New_Offer|"Add a new Offer"]] API call
 
|-
 
|'''digital_id_hash'''
 
|Hash of the Digital Identity data in order to verify their correctness
 
|-
 
|}
 
 
 
Direct [[Blockchain_API#sell_asset|'''Blockchain "Sell Asset" API call''']] is described in [[Blockchain_API]] section.
 
 
 
 
 
----
 
 
 
<div id="Anchor_Confirm_Request"></div>
 
 
 
=== 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 <nowiki>https://api.blockchaintele.com</nowiki>
 
 
 
<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:
 
{| class="wikitable" style="color:black; background-color:#FFFFFF; width:500px; cellpadding="10"
 
|'''object'''
 
|name of the API method
 
|-
 
|'''provider_id'''
 
|unique int64 Blockchain ID of the [[Terms_and_Conditions#Anchor_Definitions|Request Issuer]]
 
|-
 
|'''btrequest_id'''
 
|Blockchain ID of the Request received in [[API_for_Mobile_Operators#A_Request_is_accepted_by_Offer_Assignee|"A Request is accepted by Offer Assignee"]] callback
 
 
|-
 
|-
|'''user_id'''
+
|'''served_sum'''
|[optional] [https://en.wikipedia.org/wiki/MSISDN MSISDN] of the subscriber
+
|cost of the provided service, in SDRt
 
|-
 
|-
 
|'''memo'''
 
|'''memo'''
|[optional] json with any tags to add comments to the transaction
+
|description of the Report Transaction as json, with multiple tags. Language for description: English
|-
 
 
|}
 
|}
  
 +
After acceptance, the reserved sum is blocked on the Order Issuer account until "Report" transaction, "Cancel" transaction or the order expiration.
  
----
 
 
<div id="Anchor_Rate_Request"></div>
 
 
=== 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 <nowiki>https://api.blockchaintele.com</nowiki>
+
<div id="Anchor_Cancel_Order"></div>
 +
=== Cancel an own Order ===
  
  <object>RateRequest</object>
+
  "object": "accept_order"
  <params>
+
  "params": {"account_id": 20, "ptorder_id": 1250, "memo": "{\"accept_code\":\"Order_2450\"}"}
  <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:  
 
Response:  
Line 496: Line 335:
 
|name of the API method
 
|name of the API method
 
|-
 
|-
|'''provider_id'''
+
|'''account_id'''
|unique int64 Blockchain ID of the [[Terms_and_Conditions#Anchor_Definitions|Request Issuer]]
+
|unique int64 Blockchain ID of the Participant who creates the Requests
|-
 
|'''btrequest_id'''
 
|Blockchain ID of the Request received in [[API_for_Mobile_Operators#A_Request_is_accepted_by_Offer_Assignee|"A Request is accepted by Offer Assignee"]] callback
 
|-
 
|'''user_id'''
 
|[optional] [https://en.wikipedia.org/wiki/MSISDN 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
 
|-
 
|}
 
 
 
 
 
----
 
 
 
<div id="Anchor_Complete_Request"></div>
 
=== 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 <nowiki>https://api.blockchaintele.com</nowiki>
 
 
 
<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:
 
{| class="wikitable" style="color:black; background-color:#FFFFFF; width:500px; cellpadding="10"
 
|'''object'''
 
|name of the API method
 
|-
 
|'''error_code'''
 
|Reason why the Request is completed
 
|-
 
|'''provider_id'''
 
|unique int64 Blockchain ID of the [[Terms_and_Conditions#Anchor_Definitions|Request Issuer]]
 
|-
 
|'''btrequest_id'''
 
|Blockchain ID of the Request received in [[API_for_Mobile_Operators#A_Request_is_accepted_by_Offer_Assignee|"A Request is accepted by Offer Assignee"]] callback
 
 
|-
 
|-
|'''user_id'''
+
|'''ptorder_id'''
|[optional] [https://en.wikipedia.org/wiki/MSISDN MSISDN] of the subscriber
+
|int64 ID of the Order to be cancelled. The ID is assigned be the Order Issuer
 
|-
 
|-
 
|'''memo'''
 
|'''memo'''
|[optional] json with any tags to add comments to the transaction
+
|description of the Order cancellation as json, with multiple tags. Language for description: English
|-
 
 
|}
 
|}
  
Direct [[Blockchain_API#cancel_order|'''Blockchain "Cancel Order" API call''']] is described in [[Blockchain_API]] section.
+
  Any order could be cancelled by the Order Issuer.
 
 
== Callbacks on events for [[Terms_and_Conditions#Anchor_Definitions|Offer Assignee]] ==
 
 
 
<div id="Anchor_Offer_Selected"></div>
 
=== One of own Offers is selected ===
 
 
 
When a [[API_for_Mobile_Operators#Anchor_Start_Request|"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:
 
{| class="wikitable" style="color:black; background-color:#FFFFFF; width:500px; cellpadding="10"
 
|'''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 [[API_for_Mobile_Operators#Anchor_Accept_Request|"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 [[API_for_Mobile_Operators#Anchor_New_Offer|"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 [[API_for_Mobile_Operators#Start_a_new_Request|"Start a new Request"]] API call
 
|-
 
|'''digital_id_hash'''
 
|Hash of the Digital Identity data in order to verify their correctness
 
|-
 
|}
 
 
 
Direct [[Blockchain_API#get_limit_orders|'''Blockchain "Get Limit Orders" API call''']] is described in [[Blockchain_API]] section.
 
 
 
 
 
----
 
 
 
<div id="Anchor_Request_Completed"></div>
 
 
 
=== A Request is completed ===
 
 
 
When a [[API_for_Mobile_Operators#Anchor_Complete_Request|"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:
 
{| class="wikitable" style="color:black; background-color:#FFFFFF; width:500px; cellpadding="10"
 
|'''error_code'''
 
|Reason why the Request is completed
 
|-
 
|'''btrequest_id'''
 
|Unique int-64 Request ID assigned by Blockchain Nodes
 
|-
 
|'''user_id'''
 
|[optional] [https://en.wikipedia.org/wiki/MSISDN MSISDN] of the subscriber
 
|-
 
|'''memo'''
 
|[optional] json with any tags to add comments to the transaction
 
|-
 
|}
 
 
 
== Callbacks on events for [[Terms_and_Conditions#Anchor_Definitions|Request Issuer]] ==
 
 
 
<div id="Anchor_Offer_Added"></div>
 
=== New Offer is published on Blockchain ===
 
 
 
When a [[API_for_Mobile_Operators#Anchor_New_Offer|"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:
 
{| class="wikitable" style="color:black; background-color:#FFFFFF; width:500px; cellpadding="10"
 
|'''btoffer_id'''
 
|Unique int-64 Offer ID assigned by Blockchain Nodes
 
|-
 
|'''offer_id'''
 
|int64 Offer ID assigned by the [[Terms_and_Conditions#Anchor_Definitions|Offer Assignee]]
 
|-
 
|'''provider_id'''
 
|Unique Blockchain ID of the [[Terms_and_Conditions#Anchor_Definitions|Offer Assignee]]
 
|-
 
|other <xml> tags
 
|the same as for [[API_for_Mobile_Operators#Anchor_New_Offer|"Add a new Offer"]]
 
|-
 
|}
 
 
 
Direct [[Blockchain_API#list_assets|'''Blockchain "List Assets" API call''']] is described in [[Blockchain_API]] section.
 
 
 
 
 
----
 
 
 
<div id="Anchor_Offer_Canceled"></div>
 
 
 
=== One of existing Offers is canceled ===
 
 
 
When a [[API_for_Mobile_Operators#Anchor_Cancel_Offer|"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
 
 
 
{| class="wikitable" style="color:black; background-color:#FFFFFF; width:500px; cellpadding="10"
 
|'''btoffer_id'''
 
|Unique int-64 Offer ID assigned by Blockchain Nodes
 
|}
 
 
 
Direct [[Blockchain_API#list_assets|'''Blockchain "List Assets" API call''']] is described in [[Blockchain_API]] section.
 
 
 
 
 
----
 
 
 
<div id="Anchor_Request_Started"></div>
 
=== A subscriber has selected one of third-party Offers ===
 
 
 
When a subscriber selects an Offer via build-in Bot Messenger or [[Bubbletone_app_customization|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:
 
{| class="wikitable" style="color:black; background-color:#FFFFFF; width:500px; cellpadding="10"
 
|'''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 [https://en.wikipedia.org/wiki/ISO_3166-1 ISO3166-1 alpha-2] standard
 
|-
 
|'''user_id'''
 
|[https://en.wikipedia.org/wiki/MSISDN 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.
 
 
 
 
 
----
 
 
 
<div id="Anchor_Request_Accepted"></div>
 
 
 
=== A Request is updated by Offer Assignee ===
 
 
 
When the [[Terms_and_Conditions#Anchor_Definitions|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:
 
{| class="wikitable" style="color:black; background-color:#FFFFFF; width:500px; cellpadding="10"
 
|'''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 [[API_for_Mobile_Operators#Anchor_Start_Request|"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_API#get_account_history|'''Blockchain "Get Account History" API call''']] is described in [[Blockchain_API]] section.
 
 
 
 
 
----
 
 
 
=== A Request is completed ===
 
 
 
When a [[API_for_Mobile_Operators#Anchor_Complete_Request|"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:
 
{| class="wikitable" style="color:black; background-color:#FFFFFF; width:500px; cellpadding="10"
 
|'''error_code'''
 
|Reason why the Request is completed
 
|-
 
|'''btrequest_id'''
 
|unique int64 Request ID assigned by the Blockchain Nodes
 
|-
 
|'''user_id'''
 
|[optional] [https://en.wikipedia.org/wiki/MSISDN MSISDN] of the subscriber
 
|-
 
|'''memo'''
 
|[optional] json with any tags to add comments to the transaction
 
|-
 
|}
 
 
 
== Call Flow for main cases ==
 
 
 
=== Easy start for [[Terms_and_Conditions#Anchor_Definitions|Offer Assignee]] ===
 
 
 
It takes just 10 minutes to publish own Offers onto Blockchain and upload mobile profiles with pre-activated packages of mobile services:
 
 
 
{{#ev:youtube|https://youtu.be/4djHDVjXtZk}}
 
 
 
 
 
----
 
 
 
=== Easy start for [[Terms_and_Conditions#Anchor_Definitions|Request Issuer]] ===
 
 
 
Usage of build-in Bot Messenger or [[Bubbletone_app_customization|Bubbletone mobile app]] simplifies all integration process dramatically. The Request Issuer should make following steps:
 
 
 
1. [[Web_Account|Web-account]]: customize Offers (localize description and setup retail prices in local currency) for its subscribers
 
2. [[Web_Account|Web-account]]: customize Bot Messenger under section "Settings / Localization"
 
3. [[Web_Account|Web-account]]: input settings of own [[Terms_and_Conditions#Anchor_Abbreviations|SMPP]] server to provide downloading of encrypted SMS with mobile profiles
 
4. [[Web_Account|Web-account]]: upload MSISDN's of subscribers and [[Terms_and_Conditions#Anchor_Abbreviations|OTA]] keys of SIM-cards for built-in [[Terms_and_Conditions#Anchor_Abbreviations|OTA]] platform
 
5. Support an easy http-GET Credit Control request, with response 200 (OK) / 402 (Payment is required). Details are described at [[API_for_Mobile_Operators#Anchor_Request_Started|"A subscriber has selected one of third-party Offers"]]
 
6. Distribute Multi-Account SIM-cards among subscribers.
 
 
 
[[File:WikiLiteIntegration.png|800px]]
 
 
 
 
 
----
 
 
 
<div id="Anchor_Provisioning_Control"></div>
 
=== Integration with own Provisioning Control ===
 
 
 
That's the most optimal case for any Offer Assignee:
 
 
 
[[File:Integration_with_Provisioning_Control.png|546px]]
 
 
 
1. New Offers are published via [[Web_Account|Web-account]]
 
2. When a [[API_for_Mobile_Operators#Anchor_Start_Request|"Start a new Request"]] transaction is created and validated onto Blockchain, the Offer Assignee receives the [[API_for_Mobile_Operators#Anchor_Offer_Selected|"One of own Offers is selected"]] API call
 
3. If the Offer Assignee is ready to start servicing this Request, it makes [[API_for_Mobile_Operators#Anchor_Accept_Request|"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 [[API_for_Mobile_Operators#Anchor_Report_Request|"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.
 
 
 
 
 
----
 
<div id="Anchor_OwnUI_Integration"></div>
 
 
 
=== 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:
 
 
 
 
 
[[File:Integration_with_own_UI.png|758px]]
 
 
 
1. New Offers and Canceled Offers are updated via [[API_for_Mobile_Operators#Anchor_Offer_Added|"New Offer is published on Blockchain"]] and [[API_for_Mobile_Operators#Anchor_Offer_Canceled|"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 [[API_for_Mobile_Operators#Anchor_Start_Request|"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 [[API_for_Mobile_Operators#Anchor_Request_Accepted|"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.
 
 
 
  
  

Revision as of 20:38, 31 July 2018

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, "ptasset_id": 850, "bcservice_id": 2760, "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": 350, "memo": "{\"Name\":\"Asset_350\"}", "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 Request for Bids

"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.




Create a new Bid on Request

"object": "create_bid"
"params": {"account_id": 20, "ptbid_id": 720, "bcrequest_id": 7500, "memo": "{\"Name\":\"Bid_720\"}", "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
ptbid_id int64 ID of the Bid assigned by the Participant. It should be unique among all its bids
bcrequest_id int64 ID of the Request, the Bid is created to
memo description of the Bid as json, with multiple tags. Language for description: English
timeout_sec expiration period of the Bid, in seconds
Short-term bid on the Request from another service-provider.




Create a new Order on Bid or Asset

"object": "create_order"
"params": {"account_id": 20, "ptorder_id": 1250, "bcasset_id": 850, "bcbid_id": 9850, "amount": 5, "reserved_sum": 12.5, "memo": "{\"Name\":\"Order_1250\"}", "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
ptorder_id int64 ID of the Order assigned by the Participant. It should be unique among all its orders
bcbid_id (optional) int64 ID of the Bid, the Order is created on
bcasset_id (optional) int64 ID of the Bid, the Order is created on
amount (optional) int64 amount of the assets, 1 by default
reserved_sum how much SDRt should be reserved for the order
memo description of the Order as json, with multiple tags. Language for description: English
timeout_sec expiration period of the Order, in seconds
Order on a Bid or an Asset (one of them should be specified) for another service-provider.




Accept a received Order

"object": "accept_order"
"params": {"account_id": 20, "bcorder_id": 2450, "memo": "{\"accept_code\":\"Order_2450\"}"}

Response:

200 OK

Requirements:

object name of the API method
account_id unique int64 Blockchain ID of the Participant who creates the Requests
bcorder_id int64 ID of the Order to be accepted
memo description of the Order acceptance as json, with multiple tags. Language for description: English
After acceptance, the reserved sum is blocked on the Request Issuer account until "Report" transaction, "Cancel" transaction or the order expiration.




Report transaction: service is provided for the Order

"object": "accept_order"
"params": {"account_id": 20, "bcorder_id": 2450, "amount": 2, "served_sum": 2.5, "memo": "{\"accept_code\":\"Order_2450\"}"}

Response:

200 OK

Requirements:

object name of the API method
account_id unique int64 Blockchain ID of the Participant who creates the Requests
bcorder_id int64 ID of the Order to be served
amount (optional) int64 amount of the provided assets, 1 by default
served_sum cost of the provided service, in SDRt
memo description of the Report Transaction as json, with multiple tags. Language for description: English
After acceptance, the reserved sum is blocked on the Order Issuer account until "Report" transaction, "Cancel" transaction or the order expiration.



Cancel an own Order

"object": "accept_order"
"params": {"account_id": 20, "ptorder_id": 1250, "memo": "{\"accept_code\":\"Order_2450\"}"}

Response:

200 OK

Requirements:

object name of the API method
account_id unique int64 Blockchain ID of the Participant who creates the Requests
ptorder_id int64 ID of the Order to be cancelled. The ID is assigned be the Order Issuer
memo description of the Order cancellation as json, with multiple tags. Language for description: English
Any order could be cancelled by the Order Issuer.


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.