Difference between revisions of "Low-Level API JSON"

From BlockChainTeleCom wiki
Jump to: navigation, search
Line 482: Line 482:
 
|}
 
|}
  
  Short-term request on one or several assets from one or several service-providers in order to receive bids from them.
+
  Short-term Request on Participant's asset.
  
  
Line 547: Line 547:
 
|}
 
|}
  
  Short-term bid on the Request from another service-provider.
+
  Short-term bid on the Participant's Request is created by another service-provider.
  
  
Line 659: Line 659:
  
  
=== One of third-party Orders is cancelled of expired ===
+
=== One of third-party Orders is cancelled or expired ===
  
 
  "object": "order_cancelled"
 
  "object": "order_cancelled"

Revision as of 08:34, 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 and Orders 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 and Orders 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 and Orders 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 and Orders 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 Request
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 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 method
account_id unique int64 Blockchain ID of the Participant who creates 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 Asset, the Order is created on
amount (optional) int64 amount of the Asset, 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 accepts 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 Order Issuer account until "Report" transaction, "Cancel" transaction or the Order expiration is happened.




Report transaction: full or part of ordered service is provided

"object": "report_order"
"params": {"account_id": 20, "bcorder_id": 2450, "amount": 2, "served_sum": 2.5, "memo": "{\"report_details\":\"Report Data\"}"}

Response:

200 OK

Requirements:

object name of the API method
account_id unique int64 Blockchain ID of the Participant who publishes the Report
bcorder_id int64 ID of the Order to be served
amount (optional) int64 amount of the provided Asset, 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




Cancel an own Order

"object": "accept_order"
"params": {"account_id": 20, "ptorder_id": 1250, "memo": "{\"cancel_reason\":\"Cancelled by user\"}"}

Response:

200 OK

Requirements:

object name of the API method
account_id unique int64 Blockchain ID of the Participant who cancels the Order
ptorder_id int64 ID of the Order to be cancelled. The ID is assigned by 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 Participant's asset.




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 Participant's Request is created by 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. The ID 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.




New Order on Participant's Asset / Bid is created

"object": "order_created"
"params": {"partner_id": 20, "bcorder_id": 2450, "ptasset_id": 350, "ptbid_id": 720, "order_sum": 12.5, "memo": "{\"Name\":\"New_Order\"}", "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 Order
bcorder_id unique int64 ID of the Order. The ID is used for other proactive commands and events
ptasset_id int64 ID of the Asset assigned by the Participant
ptbid_id int64 ID of the Bid assigned by the Participant
order_sum cost of the order in SDRt
memo description of the Order as json, with multiple tags. Language for description: English
expiration_timestamp timestamp with time zone when the Order is expired
"ptasset_id" or "ptbid_id" is specified.




One of Paticipant's Orders is updated

"object": "order_updated"
"params": {"partner_id": 20, "ptorder_id": 7500, "event": "reported", "served_sum": 5.5, "memo": "{\"Name\":\"Updated_Order\"}"}

Response:

200 OK

Requirements:

object name of the API event
partner_id int64 Blockchain ID of the Participant who has updated the Order
ptorder_id int64 ID of the Order assigned by the Participant
event Reason for the Bid update: "accepted", "reported", "rejected"
served_sum How much SDRt the Order is served with
memo description of the Order update as json, with multiple tags. Language for description: English
Any updates made by another service-provider on the Participant's Order.




One of third-party Orders is cancelled or expired

"object": "order_cancelled"
"params": {"bcorder_id": 2450, "event": "expired", "memo": "{\"Name\":\"Cancelled_Order\"}"}

Response:

200 OK

Requirements:

object name of the API event
bcorder_id unique int64 ID of the Order. The ID is used for other proactive commands and events
event Reason for the Order update: "cancelled", "expired"
memo description of the Order cancellation as json, with multiple tags. Language for description: English
Cancellation of the Order created by another service-provider.




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.