Tutorial: Purchase P-Series Cloud Edition Using API

This tutorial introduces the request parameters and provides a request example to show you how to purchase a P-Series Cloud Edition using API.

Before you begin: Understand the request parameters

Before purchasing P-Series Cloud Edition using API, we recommend that you read the table below to understand the request parameters and collect the corresponding values.


Item	Parameter	Description
Operation Type	`operationType`	The operation type. In this scenario, the value is fixed at `purchase_plan`.
Product ID	`productId`	Specify the product to which you want to subscribe. The Product ID for P-Series Cloud Edition is `13`.
Billing Contact ID	`billingId`	Specify the contact who can receive the invoice after you purchase P-Series Cloud Edition. You will need to query the Billing Contact ID as described in the following steps.
Plan ID & Service ID	`serviceId`	Specify the specific plan and service to which you want to subscribe. The Plan IDs for P-Series Cloud Edition are shown below: Enterprise Plan: `3048571730026938368` Ultimate Plan: `3048572026291630080` The Service IDs for P-Series Cloud Edition are shown below: Extension Expansion: `3048573516041273344` Recording Minutes: `3048573759449317376` High Availability: `3048573935752720384`
Plan Type & Service Type	`serviceType`	When subscribing to plan, the value should be `plan`. When subscribing to service, the value should be `service`.
Connection Plan ID	`connectionPlanId`	Specify the specific plan to which you want to subscribe. Note: This parameter is required only when you subscribe to both plan and service. The valid value is exactly the same as the Plan ID for P-Series Cloud Edition: Enterprise Plan: `3048571730026938368` Ultimate Plan: `3048572026291630080`
Quantity	`quantity`	Specify the number of extensions to which you want to subscribe. Valid values: 5- 500
Purchase Type	`purchaseType`	The purchase type. In this scenario, the value is fixed at `purchase`.
Billing Model	`billingModel`	The billing model of P-Series Cloud Edition. The value is fixed at `recurring`.
Billing Cycle	`billingCycle`	The billing cycle of P-Series Cloud Edition. The value is fixed at `annually` or `monthly`.
Multi Cycle	`multiCycle`	The interval of recurring billing. The value is fixed at `0`.
PBX Name	`pbxName`	Specify a name to help you identify the PBX on Yeastar Central Management.
Region ID	`regionId`	Specify the region where the PBX will be created. You will need to query the Region ID as described in the following steps.
PBX Subdomain ID	`pbxSubDomainId`	Specify the domain suffix that will make up the PBX URL. You will need to query the PBX Subdomain ID as described in the following steps.
PBX URL	`pbxUrl`	Specify the PBX URL. The URL is the domain name of the PBX, which is made up of a customized prefix and a specific domain suffix.

Step 1. Query available region using an API

Make a request to the Query Region List API endpoint.
```
GET {base_url}/product/openapi/instance/v1/region_list
```
Note down the returned value of id, pbxSubDomain, and pbxSubDomainId for the desired region.

Step 2. Check the existence of PBX URL

A PBX URL is made up of a customized prefix and a specific domain suffix. Before you place an order, make sure that the desired PBX URL is not occupied.

Make a request to the Check the Existence of PBX URL for P-Series Cloud Edition API endpoint.
```
GET {base_url}/product/openapi/instance/v1/paug_pbx_url_existed?
```
Check the returned value of result.

If the returned value of result is false, it indicates that the PBX URL does not exist and is available for use.

Step 3. Get Billing Contact ID using an API

Make a request to the Query Billing Contact List API endpoint.

GET {base_url}/user/openapi/user/v1/client/billing_contact_list

Note down the returned value of billingContactId for the desired billing contact.

Step 4. Purchase P-Series Cloud Edition using an API

Make a request to the Create an Order API endpoint with the collected values.

POST {base_url}/order/openapi/order/v1/save

In this tutorial, the values we collect are shown below:


Item	Parameter	Value
Operation Type	`operationType`	purchase_plan
Product ID	`productId`	13
Billing Contact ID	`billingId`	3197218168379846218
Plan ID & Plan Type	`serviceId` & `serviceType`	`serviceId`: `3048571730026938368` (ID for Enterprise Plan) `serviceType`: `plan`
Service ID & Service Type	`serviceId` & `serviceType`	`serviceId`: `3048573935752720384` (ID for High Availability service) `serviceType`: `service`
Connection Plan ID	`connectionPlanId`	3048571730026938368 (ID for Enterprise Plan)
Quantity	`quantity`	100
Purchase Type	`purchaseType`	purchase
Billing Model	`billingModel`	recurring
Billing Cycle	`billingCycle`	annually
Multi Cycle	`multiCycle`	0
PBX Name	`pbxName`	test
Region ID	`regionId`	41
PBX Sub-domain ID	`pbxSubDomainId`	20
PBX URL	`pbxUrl`	docs.ptest6.yeastarcloud.com

The sample request to purchase a P-Series Cloud Edition with Enterprise Plan and High Availability service for 1 year is shown below:

POST /order/openapi/order/v1/save HTTP/1.1
Host: openapi.partner.yeastar.com
Content-Type: application/json
User-Agent: OpenAPI
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOlsicmVzMSJdLCJYLU1TLVVTRVIiOiJ7XCJleHByXCI6XCIwXCIsXCJ0eXBlXCI6XCJwYXJ0bmVyXCIsXCJ1Y0lkXCI6XCIzMDc2OTE1NDU0NDY4NzY3NzQ0XCIsXCJ1c2VyQ29kZVwiOlwiUGFydG5lclwiLFwidXNlcklkXCI6XCIzMDc2OTE1NDU0NDg5NzM5MjY0XCIsXCJ1c2VybmFtZVwiOlwicGFydG5lcmV4YW1wbGVAb3V0bG9vay5jb21cIn0iLCJ1c2VyX25hbWUiOiJwYXJ0bmVyZXhhbXBsZUBvdXRsb29rLmNvbSIsInNjb3BlIjpbImFsbCJdLCJleHAiOjE3Mzk3MTc5MjYsInRva2VuX3R5cGUiOiJvcGVuYXBpIiwianRpIjoidmlzMkh0QkxaUStNQmxPbS9UdThWR1pyNFljPSIsImF1dGhvcml0aWVzIjpbIjc5Il0sImNsaWVudF9pZCI6IjE0NDI5NjM2ODBiMjM0YjA0YmRjZDVjMTZmODcyOWQ2In0.RPRoTJRkXCB4krDSwGRpUFyCfUVv2LHjIiBICA1pCiY

{
    "operationType": "purchase_plan",
    "productId": 13,
    "billingId": 3197218168379846218,
    "serviceList": [
    {
      "serviceId": 3048571730026938368,
      "serviceType": "plan",
      "quantity": 100,
      "purchaseType": "purchase",
      "billingModel": "recurring",
      "billingCycle": "annually",
      "multiCycle": 0
    },
    {
      "connectionPlanId":3048571730026938368,
      "serviceId": 3048573935752720384,
      "serviceType": "service",
      "purchaseType": "purchase",
      "billingModel": "recurring",
      "billingCycle": "annually",
      "multiCycle": 0
    }
  ],
    
    "orderPceSpecialRequest": {
        "pbxName": "test",
        "regionId": 41,
        "pbxSubDomainId": 20,
        "pbxUrl": "docs.ptest6.yeastarcloud.com"
    }
}

Result

The sample response is shown below:

{
    "code": "success",
    "detailMessage": "",
    "requestId": "7c7a9d75e0c791c32d4fe4f4561eef14",
    "result": {
        "instanceId": "1275655",
        "orderNo": "HB3203705539121029120",
        "orderStatus": "succeed",
        "productNo": "3658B431119665QJ",
        "transactionNo": "XN3203705540022804481"
    },
    "status": 200
}