Difference between revisions of "Low-Level API JSON"

From BlockChainTeleCom wiki
Jump to: navigation, search
Line 10: Line 10:
 
== Proactive commands ==
 
== Proactive commands ==
  
<div id="Anchor_New_Service"></div>
 
 
=== Create a new Service ===
 
=== Create a new Service ===
  
Line 43: Line 42:
  
  
<div id="Anchor_Update_Service"></div>
 
 
=== Update one of existing Services ===
 
=== Update one of existing Services ===
  
Line 74: Line 72:
  
  
<div id="Anchor_New_Asset"></div>
 
 
=== Create a new Offer (Asset) ===
 
=== Create a new Offer (Asset) ===
  
 
  "object": "create_asset"
 
  "object": "create_asset"
  "params": {"account_id": 20, "ptasset_id": 850, "bcservice_id": 2760, "memo": "{\"Name\":\"Asset_850\"}", "whitelist_accounts":[25, 30]}
+
  "params": {"account_id": 20, "ptasset_id": 350, "ptservice_id": 196, "memo": "{\"Name\":\"Asset_350\"}", "whitelist_accounts":[25, 30]}
  
 
Response:  
 
Response:  
Line 108: Line 105:
  
  
<div id="Anchor_Update_Asset"></div>
 
 
=== Update one of existing Offers (Assets) ===
 
=== Update one of existing Offers (Assets) ===
  
Line 139: Line 135:
  
  
<div id="Anchor_New_Bid_Request"></div>
 
 
=== Create a new Request for Bids===
 
=== Create a new Request for Bids===
  
Line 175: Line 170:
  
  
<div id="Anchor_New_Bid"></div>
 
 
=== Create a new Bid on Request ===
 
=== Create a new Bid on Request ===
  
Line 211: Line 205:
  
  
<div id="Anchor_New_Order"></div>
 
 
=== Create a new Order on Bid or Asset ===
 
=== Create a new Order on Bid or Asset ===
  
Line 256: Line 249:
  
  
<div id="Anchor_Accept_Order"></div>
 
 
=== Accept a received Order ===
 
=== Accept a received Order ===
  
Line 272: Line 264:
 
|'''account_id'''
 
|'''account_id'''
 
|unique int64 Blockchain ID of the Participant who creates the Requests
 
|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: full or part of ordered service is provided ===
 +
 +
"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:
 +
{| class="wikitable" style="color:black; background-color:#FFFFFF; width:500px; cellpadding="10"
 +
|'''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:
 +
{| class="wikitable" style="color:black; background-color:#FFFFFF; width:500px; cellpadding="10"
 +
|'''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.
 +
 +
 +
== Events from Blockchain ecosystem ==
 +
 +
=== New Service is created ===
 +
 +
"object": "service_created"
 +
"params": {"partner_id": 20, "bcservice_id": 2760, "memo": "{\"Name\":\"New_Service\"}"}
 +
 +
Response:
 +
200 OK
 +
 +
Requirements:
 +
{| class="wikitable" style="color:black; background-color:#FFFFFF; width:500px; cellpadding="10"
 +
|'''object'''
 +
|name of the API event
 +
|-
 +
|'''partner_id'''
 +
|int64 Blockchain ID of the [[Terms_and_Conditions#Anchor_Definitions|Offer Assignee]] who has created the Service
 +
|-
 +
|'''bcservice_id'''
 +
|unique int64 ID of the Service which is used for other proactive commands and events
 +
|-
 +
|'''memo'''
 +
|description of the Service as json, with multiple tags. Language for description: English
 +
|}
 +
 +
 +
----
 +
 +
 +
=== One of existing Services is updated ===
 +
 +
"object": "service_updated"
 +
"params": {"partner_id": 20, "bcservice_id": 196, "memo": "{\"Name\":\"Service_Updated\"}"}
 +
 +
Response:
 +
200 OK
 +
 +
Requirements:
 +
{| class="wikitable" style="color:black; background-color:#FFFFFF; width:500px; cellpadding="10"
 +
|'''object'''
 +
|name of the API event
 +
|-
 +
|'''partner_id'''
 +
|int64 Blockchain ID of the [[Terms_and_Conditions#Anchor_Definitions|Offer Assignee]] who has created the Service
 +
|-
 +
|'''bcservice_id'''
 +
|unique int64 ID of the Service which is used for other proactive commands and events
 +
|-
 +
|'''memo'''
 +
|description of the Service as json, with multiple tags. Language for description: English
 +
|}
 +
 +
 +
----
 +
 +
 +
=== New Offer (Asset) is created ===
 +
 +
"object": "asset_created"
 +
"params": {"partner_id": 20, "bcservice_id": 2760, "bcasset_id": 850, "memo": "{\"Name\":\"New_Asset\"}"}
 +
 +
Response:
 +
200 OK
 +
 +
Requirements:
 +
{| class="wikitable" style="color:black; background-color:#FFFFFF; width:500px; cellpadding="10"
 +
|'''object'''
 +
|name of the API event
 +
|-
 +
|'''partner_id'''
 +
|int64 Blockchain ID of the [[Terms_and_Conditions#Anchor_Definitions|Offer Assignee]] who has created the Asset
 +
|-
 +
|'''bcservice_id'''
 +
|unique int64 ID of the Service which is used for other proactive commands and events
 +
|-
 +
|'''bcasset_id'''
 +
|unique int64 ID of the Asset which is used for other proactive commands and events
 +
|-
 +
|'''memo'''
 +
|description of the Asset as json, with multiple tags. Language for description: English
 +
|}
 +
 +
 +
----
 +
 +
 +
=== One of existing Offers (Assets) is updated ===
 +
 +
"object": "asset_updated"
 +
"params": {"partner_id": 20, "bcservice_id": 2760, "bcasset_id": 850, "memo": "{\"Name\":\"New_Asset\"}"}
 +
 +
Response:
 +
200 OK
 +
 +
Requirements:
 +
{| class="wikitable" style="color:black; background-color:#FFFFFF; width:500px; cellpadding="10"
 +
|'''object'''
 +
|name of the API event
 +
|-
 +
|'''partner_id'''
 +
|int64 Blockchain ID of the [[Terms_and_Conditions#Anchor_Definitions|Offer Assignee]] who has created the Asset
 +
|-
 +
|'''bcservice_id'''
 +
|unique int64 ID of the Service which is used for other proactive commands and events
 +
|-
 +
|'''bcasset_id'''
 +
|unique int64 ID of the Asset which is used for other proactive commands and events
 +
|-
 +
|'''memo'''
 +
|description of the Asset as json, with multiple tags. Language for description: English
 +
|}
 +
 +
 +
----
 +
 +
 +
=== New Request on Participant's asset is created ===
 +
 +
"object": "request_created"
 +
"params": {"partner_id": 20, "bcrequest_id": 7500, "ptasset_id":350, "memo": "{\"Name\":\"New_Request\"}", "expiration_timestamp": "2020-01-01 07:30:00+00"}
 +
 +
Response:
 +
200 OK
 +
 +
Requirements:
 +
{| class="wikitable" style="color:black; background-color:#FFFFFF; width:500px; cellpadding="10"
 +
|'''object'''
 +
|name of the API event
 +
|-
 +
|'''partner_id'''
 +
|int64 Blockchain ID of the [[Terms_and_Conditions#Anchor_Definitions|Participant]] who has created the Request
 +
|-
 +
|'''bcrequest_id'''
 +
|unique int64 ID of the Request which is used for other proactive commands and events
 +
|-
 +
|'''ptasset_id'''
 +
|int64 ID of the Participant's Asset
 +
|-
 +
|'''memo'''
 +
|description of the Request as json, with multiple tags. Language for description: English
 +
|-
 +
|'''expiration_timestamp'''
 +
|timestamp with time zone when the Request is expired
 +
|}
 +
 +
Short-term request on one or several assets from one or several service-providers in order to receive bids from them.
 +
 +
 +
----
 +
 +
 +
=== One of third-party Request is updated ===
 +
 +
"object": "request_updated"
 +
"params": {"bcrequest_id": 7500, "event": "expired", "memo": "{\"Name\":\"Request_650\"}"}
 +
 +
Response:
 +
200 OK
 +
 +
Requirements:
 +
{| class="wikitable" style="color:black; background-color:#FFFFFF; width:500px; cellpadding="10"
 +
|'''object'''
 +
|name of the API event
 +
|-
 +
|'''bcrequest_id'''
 +
|unique int64 ID of the Request which is used for other proactive commands and events
 +
|-
 +
|'''event'''
 +
|Reason for the Request update: "cancelled", "expired"
 +
|-
 +
|'''memo'''
 +
|description of the Request update as json, with multiple tags. Language for description: English
 +
|}
 +
 +
Any updates on the Request created by another service-provider.
 +
 +
 +
--
 +
 +
 +
 +
 +
 +
<div id="Anchor_New_Bid"></div>
 +
=== 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:
 +
{| class="wikitable" style="color:black; background-color:#FFFFFF; width:500px; cellpadding="10"
 +
|'''object'''
 +
|name of the API event
 +
|-
 +
|'''partner_id'''
 +
|int64 Blockchain ID of the [[Terms_and_Conditions#Anchor_Definitions|Participant]] who has created the Bid
 +
|-
 +
|'''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.
 +
 +
 +
----
 +
 +
 +
<div id="Anchor_New_Order"></div>
 +
=== 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:
 +
{| class="wikitable" style="color:black; background-color:#FFFFFF; width:500px; cellpadding="10"
 +
|'''object'''
 +
|name of the API event
 +
|-
 +
|'''partner_id'''
 +
|int64 Blockchain ID of the [[Terms_and_Conditions#Anchor_Definitions|Participant]] who has created the Order
 +
|-
 +
|'''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.
 +
 +
 +
----
 +
 +
 +
<div id="Anchor_Accept_Order"></div>
 +
=== Accept a received Order ===
 +
 +
"object": "accept_order"
 +
"params": {"account_id": 20, "bcorder_id": 2450, "memo": "{\"accept_code\":\"Order_2450\"}"}
 +
 +
Response:
 +
200 OK
 +
 +
Requirements:
 +
{| class="wikitable" style="color:black; background-color:#FFFFFF; width:500px; cellpadding="10"
 +
|'''object'''
 +
|name of the API event
 +
|-
 +
|'''partner_id'''
 +
|int64 Blockchain ID of the [[Terms_and_Conditions#Anchor_Definitions|Participant]] who has created the Order
 
|-
 
|-
 
|'''bcorder_id'''
 
|'''bcorder_id'''
Line 287: Line 634:
  
 
<div id="Anchor_report_Order"></div>
 
<div id="Anchor_report_Order"></div>
=== Report transaction: service is provided for the Order ===
+
=== Report transaction: full or part of ordered service is provided ===
  
 
  "object": "accept_order"
 
  "object": "accept_order"
Line 356: Line 703:
  
 
Every time a new [[Terms_and_Conditions#Anchor_Definitions|Request]] is created, appropriate amount of SDRs is reserved (blocked) on the [[Terms_and_Conditions#Anchor_Definitions|Issuer's]] wallet. It provides payment guarantee for the service, so [[Terms_and_Conditions#Anchor_Definitions|Assignee]] is able to start servicing the subscriber directly. It's necessary to publish "Report" [[Terms_and_Conditions#Anchor_Definitions|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.
 
Every time a new [[Terms_and_Conditions#Anchor_Definitions|Request]] is created, appropriate amount of SDRs is reserved (blocked) on the [[Terms_and_Conditions#Anchor_Definitions|Issuer's]] wallet. It provides payment guarantee for the service, so [[Terms_and_Conditions#Anchor_Definitions|Assignee]] is able to start servicing the subscriber directly. It's necessary to publish "Report" [[Terms_and_Conditions#Anchor_Definitions|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 [[Terms_and_Conditions#Anchor_Definitions|Providers]] who publish "Report" [[Terms_and_Conditions#Anchor_Definitions|transaction]] without servicing the customers. But there is an effective way to detect them in short terms:
 
 
# [[Terms_and_Conditions#Anchor_Definitions|Issuer]] creates a new [[Terms_and_Conditions#Anchor_Definitions|Request]] with "faked" User ID. It means that such user is not able to start consuming the service
 
# If [[Terms_and_Conditions#Anchor_Definitions|Assignee]] publishes "Report" [[Terms_and_Conditions#Anchor_Definitions|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" [[Terms_and_Conditions#Anchor_Abbreviations|BT]] members.
 
 
So the only way to keep own reputation is to be honest with other [[Terms_and_Conditions#Anchor_Definitions|Participants]]. Such method helps building reliable and trusted community.
 

Revision as of 05:56, 1 August 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": 350, "ptservice_id": 196, "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
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: full or part of ordered service is provided

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


Events from Blockchain ecosystem

New Service is created

"object": "service_created"
"params": {"partner_id": 20, "bcservice_id": 2760, "memo": "{\"Name\":\"New_Service\"}"}

Response:

200 OK

Requirements:

object name of the API event
partner_id int64 Blockchain ID of the Offer Assignee who has created the Service
bcservice_id unique int64 ID of the Service which is used for other proactive commands and events
memo description of the Service as json, with multiple tags. Language for description: English




One of existing Services is updated

"object": "service_updated"
"params": {"partner_id": 20, "bcservice_id": 196, "memo": "{\"Name\":\"Service_Updated\"}"}

Response:

200 OK

Requirements:

object name of the API event
partner_id int64 Blockchain ID of the Offer Assignee who has created the Service
bcservice_id unique int64 ID of the Service which is used for other proactive commands and events
memo description of the Service as json, with multiple tags. Language for description: English




New Offer (Asset) is created

"object": "asset_created"
"params": {"partner_id": 20, "bcservice_id": 2760, "bcasset_id": 850, "memo": "{\"Name\":\"New_Asset\"}"}

Response:

200 OK

Requirements:

object name of the API event
partner_id int64 Blockchain ID of the Offer Assignee who has created the Asset
bcservice_id unique int64 ID of the Service which is used for other proactive commands and events
bcasset_id unique int64 ID of the Asset which is used for other proactive commands and events
memo description of the Asset as json, with multiple tags. Language for description: English




One of existing Offers (Assets) is updated

"object": "asset_updated"
"params": {"partner_id": 20, "bcservice_id": 2760, "bcasset_id": 850, "memo": "{\"Name\":\"New_Asset\"}"}

Response:

200 OK

Requirements:

object name of the API event
partner_id int64 Blockchain ID of the Offer Assignee who has created the Asset
bcservice_id unique int64 ID of the Service which is used for other proactive commands and events
bcasset_id unique int64 ID of the Asset which is used for other proactive commands and events
memo description of the Asset as json, with multiple tags. Language for description: English




New Request on Participant's asset is created

"object": "request_created"
"params": {"partner_id": 20, "bcrequest_id": 7500, "ptasset_id":350, "memo": "{\"Name\":\"New_Request\"}", "expiration_timestamp": "2020-01-01 07:30:00+00"}

Response:

200 OK

Requirements:

object name of the API event
partner_id int64 Blockchain ID of the Participant who has created the Request
bcrequest_id unique int64 ID of the Request which is used for other proactive commands and events
ptasset_id int64 ID of the Participant's Asset
memo description of the Request as json, with multiple tags. Language for description: English
expiration_timestamp timestamp with time zone when the Request is expired
Short-term request on one or several assets from one or several service-providers in order to receive bids from them.




One of third-party Request is updated

"object": "request_updated"
"params": {"bcrequest_id": 7500, "event": "expired", "memo": "{\"Name\":\"Request_650\"}"}

Response:

200 OK

Requirements:

object name of the API event
bcrequest_id unique int64 ID of the Request which is used for other proactive commands and events
event Reason for the Request update: "cancelled", "expired"
memo description of the Request update as json, with multiple tags. Language for description: English
Any updates on the Request created by another service-provider.


--



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 event
partner_id int64 Blockchain ID of the Participant who has created the Bid
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 event
partner_id int64 Blockchain ID of the Participant who has created the Order
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 event
partner_id int64 Blockchain ID of the Participant who has created the Order
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: full or part of ordered service is provided

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