Tutorial: Purchase P-Series Cloud PBX (PCE Instance) Using API

This tutorial introduces the request parameters and provides a request example to show you how to purchase a P-Series Cloud PBX (PCE Instance) using API.

Before you begin: Understand the request parameters

Before purchasing P-Series Cloud PBX (PCE Instance) 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 PBX (PCE Instance) is `13`.
Partner ID	`partnerId`	Specify the subordinate user for whom you want to purchase P-Series Cloud PBX (PCE Instance). Note: This parameter is required only when you purchase for a subordinate user. You will need to query the information as described in the following steps.
Billing Contact ID	`billingId`	Specify the contact who can receive the invoice after you purchase P-Series Cloud PBX (PCE Instance). You will need to query the Billing Contact ID as described in the following steps.
Plan Type & Service Type	`serviceType`	When subscribing to plan, the value is fixed at `plan`. When subscribing to service, the value is fixed at `service`.
Plan ID & Service ID	`serviceId`	Specify the specific plan and service to which you want to subscribe. You will need to query the IDs as described in the following steps.
Connection Plan ID	`connectionPlanId`	Optional. Specify the specific plan to which you want to subscribe. Note: This parameter is required only when you subscribe to both plan and service, and it should be the same as Plan ID.
Quantity	`quantity`	Specify the number of items to which you want to subscribe. Note: For subscription plan, this parameter indicates the allowed range for the number of extensions. For subscription service, this parameter indicates the allowed range for the number of call recording minutes, AI service minutes, etc. You will need to query the valid values as described in the following steps.
Purchase Type	`purchaseType`	The purchase type. In this scenario, the value is fixed at `purchase`.
Billing Model	`billingModel`	The billing model. In this scenario, the value is fixed at `recurring`.
Billing Cycle	`billingCycle`	The billing cycle. In this scenario, the value is fixed at `annually` or `monthly`.
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.

(Optional) Step 1. Get subordinate user ID

Make a request to the Query Subordinate User List API endpoint.
```
GET {base_url}/user/openapi/user/v1/client/partner_list
```
Note down the returned value of partnerId for the desired subordinate user.

Step 2. Get plan ID and service ID

Make a request to the Query Available Subscription / Trial Plans and Services for a Product API endpoint with the Product ID 13.
```
GET {base_url}/pricing/openapi/purchase/v1/purchase_product_info?productId=13
```
Note down the returned value of planId and serviceId for the desired plan and service.

Step 3. Query available region

Make a request to the Query Region List API endpoint.
Note: If you purchase P-Series Cloud PBX (PCE Instance) for a subordinate user, remember to pass the parameter partnerId.
```
GET {base_url}/product/openapi/instance/v1/region_list
```
Note down the returned value of id, pbxSubDomain, and pbxSubDomainId for the desired region.

Step 4. 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 5. Get purchase limit

Make a request to the Query Information about the Plan Available for Subscription API endpoint with the Product ID 13 and pricingPlanId.
Note down the returned values of purchaseInput for both plan and service.

Step 6. Get billing contact ID

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 7. Purchase P-Series Cloud PBX (PCE Instance)

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
Partner ID	`partnerId`	3196166858895147008
Billing Contact ID	`billingId`	3197218168379846218
Plan Type & Plan ID	`serviceType` & `serviceId`	`serviceType`: `plan` `serviceId`: `3048571730026938368` (ID for Enterprise Plan)
Service Type & Service ID	`serviceType` & `serviceId`	`serviceType`: `service` `serviceId`: `3048573935752720384` (ID for High Availability 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
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 PBX (PCE Instance) 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": [
    {
      "serviceType": "plan",
      "serviceId": 3048571730026938368,
      "quantity": 100,
      "purchaseType": "purchase",
      "billingModel": "recurring",
      "billingCycle": "annually"
    },
    {
      "connectionPlanId":3048571730026938368,
      "serviceType": "service",
      "serviceId": 3048573935752720384,
      "purchaseType": "purchase",
      "billingModel": "recurring",
      "billingCycle": "annually"
    }
  ],
    "partnerId": "3196166858895147008",
    "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
}