Difference between revisions of "Low-Level API JSON"

From BlockChainTeleCom wiki
Jump to: navigation, search
Line 358: Line 358:
 
|-
 
|-
 
|'''bcservice_id'''
 
|'''bcservice_id'''
|unique int64 ID of the Service which is used for other proactive commands and events
+
|unique int64 ID of the Service. The ID is used for other proactive commands and events
 
|-
 
|-
 
|'''memo'''
 
|'''memo'''
Line 385: Line 385:
 
|-
 
|-
 
|'''bcservice_id'''
 
|'''bcservice_id'''
|unique int64 ID of the Service which is used for other proactive commands and events
+
|unique int64 ID of the Service. The ID is used for other proactive commands and events
 
|-
 
|-
 
|'''memo'''
 
|'''memo'''
Line 412: Line 412:
 
|-
 
|-
 
|'''bcservice_id'''
 
|'''bcservice_id'''
|unique int64 ID of the Service which is used for other proactive commands and events
+
|unique int64 ID of the Service. The ID is used for other proactive commands and events
 
|-
 
|-
 
|'''bcasset_id'''
 
|'''bcasset_id'''
|unique int64 ID of the Asset which is used for other proactive commands and events
+
|unique int64 ID of the Asset. The ID is used for other proactive commands and events
 
|-
 
|-
 
|'''memo'''
 
|'''memo'''
Line 442: Line 442:
 
|-
 
|-
 
|'''bcservice_id'''
 
|'''bcservice_id'''
|unique int64 ID of the Service which is used for other proactive commands and events
+
|unique int64 ID of the Service. The ID is used for other proactive commands and events
 
|-
 
|-
 
|'''bcasset_id'''
 
|'''bcasset_id'''
|unique int64 ID of the Asset which is used for other proactive commands and events
+
|unique int64 ID of the Asset. The ID is used for other proactive commands and events
 
|-
 
|-
 
|'''memo'''
 
|'''memo'''
Line 472: Line 472:
 
|-
 
|-
 
|'''bcrequest_id'''
 
|'''bcrequest_id'''
|unique int64 ID of the Request which is used for other proactive commands and events
+
|unique int64 ID of the Request. The ID is used for other proactive commands and events
 
|-
 
|-
 
|'''ptasset_id'''
 
|'''ptasset_id'''
Line 490: Line 490:
  
  
=== One of third-party Request is updated ===
+
=== One of third-party Requests is updated ===
  
 
  "object": "request_updated"
 
  "object": "request_updated"
Line 504: Line 504:
 
|-
 
|-
 
|'''bcrequest_id'''
 
|'''bcrequest_id'''
|unique int64 ID of the Request which is used for other proactive commands and events
+
|unique int64 ID of the Request. The ID is used for other proactive commands and events
 
|-
 
|-
 
|'''event'''
 
|'''event'''
Line 517: Line 517:
  
 
--
 
--
 
 
 
  
  
 
<div id="Anchor_New_Bid"></div>
 
<div id="Anchor_New_Bid"></div>
=== Create a new Bid on Request ===
+
=== New Bid on Participant's Request is created ===
  
  "object": "create_bid"
+
  "object": "bid_created"
  "params": {"account_id": 20, "ptbid_id": 720, "bcrequest_id": 7500, "memo": "{\"Name\":\"Bid_720\"}", "timeout_sec": 600}
+
  "params": {"partner_id": 20, "ptrequest_id": 650, "bcbid_id": 9850, "memo": "{\"Name\":\"New_Bid\"}", "expiration_timestamp": "2020-01-01 07:30:00+00"}
  
 
Response:  
 
Response:  
Line 539: Line 536:
 
|int64 Blockchain ID of the [[Terms_and_Conditions#Anchor_Definitions|Participant]] who has created the Bid
 
|int64 Blockchain ID of the [[Terms_and_Conditions#Anchor_Definitions|Participant]] who has created the Bid
 
|-
 
|-
|'''ptbid_id'''
+
|'''ptrequest_id'''
|int64 ID of the Bid assigned by the Participant. It should be unique among all its bids
+
|int64 ID of the Participant's Request
 
|-
 
|-
|'''bcrequest_id'''
+
|'''bcbid_id'''
|int64 ID of the Request, the Bid is created to
+
|unique int64 ID of the created Bid. The ID is used for other proactive commands and events
 
|-
 
|-
 
|'''memo'''
 
|'''memo'''
 
|description of the Bid as json, with multiple tags. Language for description: English
 
|description of the Bid as json, with multiple tags. Language for description: English
 
|-
 
|-
|'''timeout_sec'''
+
|'''expiration_timestamp'''
|expiration period of the Bid, in seconds
+
|timestamp with time zone when the Bid is expired
 
|}
 
|}
  
Line 556: Line 553:
  
 
----
 
----
 +
 +
 +
=== One of third-party Bids is updated ===
 +
 +
"object": "bid_updated"
 +
"params": {"bcbid_id": 7500, "event": "expired", "memo": "{\"Name\":\"Updated_Bid\"}"}
 +
 +
Response:
 +
200 OK
 +
 +
Requirements:
 +
{| class="wikitable" style="color:black; background-color:#FFFFFF; width:500px; cellpadding="10"
 +
|'''object'''
 +
|name of the API event
 +
|-
 +
|'''bcbid_id'''
 +
|unique int64 ID of the Bid which is used for other proactive commands and events
 +
|-
 +
|'''event'''
 +
|Reason for the Bid update: "cancelled", "expired"
 +
|-
 +
|'''memo'''
 +
|description of the Bid update as json, with multiple tags. Language for description: English
 +
|}
 +
 +
Any updates on the Bid created by another service-provider.
 +
 +
  
  

Revision as of 07:52, 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. The ID 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. The ID 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. The ID is used for other proactive commands and events
bcasset_id unique int64 ID of the Asset. The ID 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. The ID is used for other proactive commands and events
bcasset_id unique int64 ID of the Asset. The ID 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. The ID 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 Requests 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. The ID 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.


--


New Bid on Participant's Request is created

"object": "bid_created"
"params": {"partner_id": 20, "ptrequest_id": 650, "bcbid_id": 9850, "memo": "{\"Name\":\"New_Bid\"}", "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 Bid
ptrequest_id int64 ID of the Participant's Request
bcbid_id unique int64 ID of the created Bid. The ID is used for other proactive commands and events
memo description of the Bid as json, with multiple tags. Language for description: English
expiration_timestamp timestamp with time zone when the Bid is expired
Short-term bid on the Request from another service-provider.




One of third-party Bids is updated

"object": "bid_updated"
"params": {"bcbid_id": 7500, "event": "expired", "memo": "{\"Name\":\"Updated_Bid\"}"}

Response:

200 OK

Requirements:

object name of the API event
bcbid_id unique int64 ID of the Bid which is used for other proactive commands and events
event Reason for the Bid update: "cancelled", "expired"
memo description of the Bid update as json, with multiple tags. Language for description: English
Any updates on the Bid created by 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.