PX CreateOrder
PX CreateOrder API product provides CenturyLink partners ability to prepare an order, select products and add-ons, request/reserve appointment date and time slot for service installation.
This describes the Partner API specifications for partners wishing to configure CenturyLink available products, services and purchase on behalf of their customers. The new PX system enables partners to seamlessly and securely transact with CenturyLink electronically on cloud based next generation CRM platforms. The products supported as part of the current version of Partner APIs include Local Service packages, Long Distance packages, Broadband internet access and product bundles containing two or more products. The APIs also offer the ability to configure modems, services (e.g. broadband installation services), and accessories (for example CenturyLink @Ease).
CreateOrder API includes:
· Prepare order service
· Request Appointments service
. Reserve Appointments service
Mass Market Partner APIs are available to new and existing partners who are selling local service packages, long-distance packages, broadband internet access, and product bundles to CenturyLink consumers and small business customers.
Mass Markets Partner APIs enable partners to seamlessly and securely qualify products and place orders with CenturyLink electronically on cloud-based next-generation CRM platforms. Digital information sharing between CenturyLink and our partners increases the speed and accuracy of products and services being delivered to the end customer.
1. Register a user.
2. Create sandbox and production apps under My Apps.
2. Obtain API keys. Upon approval, sandbox and production credentials will move to approved status. If you have questions about approvals use the Contact Us form.
3. Setup authorization. Using the navigation menu go to Code Samples for sample code for setting up authorization.
4. Make your first call. Using the navigation menu go to Documentation/Specification.
a. Click on the authorize button and add your credentials.
b. Select the POST/pxPrepare API.
c. Click on the “Try it out” button.
d. Fill in the parameters and customize the sample code.
e. Click the execute button to see the response.
When setting up your Apps in My Apps you can create a Sandbox app and a Production app. You will then have two different sets of Consumer Keys and Consumer Secrets.
Base URL Sandbox: https://api-test.lumen.com/
Base URL Prod: https://api.lumen.com/
The Sandbox (test) environment is available to developers to build initial code against. It is a snapshot of production type data so that you can try out requests and responses. The Sandbox is not meant to be used as a QA environment. It is also not meant to duplicate production, therefore data that exists in Production may not be present in the Sandbox environment. Sandbox does not represent the up-time expectations of Production. We recommend that you complete shakeout testing against Production, keeping in mind that all transactions will be live.
The below diagram depicts high level process flow for all partner APIs
Prepare API
Partner will send the following details in the Prepare API request; example of data to be provided is below (see detailed attributes and sample request-response)
- Partner authorization details like TransactionId, Salescode, PartnerId, PartnerOrderId
- Selected Product and Promotion (if applicable)
- Selected add-ons (i.e. Installation & Modem) and Promotion (if applicable)
- Partner payment token
- For prepaid required
- For postpaid when deposit is required
- For prepaid Customer preferred login username required
- Customer information
- Shipping Information (when required)
- Billing information (when applicable)
- Notification preferences
- Remarks
- Porting details
Px will process the request and sends a success confirmation. In case of error, Px will send the internal error message code and error message details.
Request Appointments API
Partner will send the following details in the Request Appointments API request
- Partner authorization details
Px will then send the list of appointments available for a 30-day window that include dates and available timeslots pertaining to those dates
Confirm Appointment API
Partner will send the following details in the Confirm Appointment API request
- Partner authorization details
- Appointment Date
- Appointment Timeslot
Px will then send the confirmation of the appointment scheduled for the selected dates
Lumen supports the OAuth 2.0 client credentials authorization grant flow for external access by client-side applications. Once your credentials are approved you can go to Using OAuth 2.0 for detailed steps on getting a bearer token using basic authorization base64 encoding. Use the navigation menu and select Code Samples for an example of authorization.
PxAuthenticationService.java
----------------------------
package com.ctl.px.api.client;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.stereotype.Service;
import org.apache.oltu.oauth2.client.OAuthClient;
import org.apache.oltu.oauth2.client.URLConnectionClient;
import org.apache.oltu.oauth2.client.request.OAuthClientRequest;
import org.apache.oltu.oauth2.client.response.OAuthJSONAccessTokenResponse;
import org.apache.oltu.oauth2.common.OAuth;
import org.apache.oltu.oauth2.common.message.types.GrantType;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
@Service
public class PxAuthenticationService {
Logger log = LoggerFactory.getLogger(PxAuthenticationService.class);
@Value("${px.sf.token.url}")
private String tokenURL;
@Value("${px.sf.token.basicAuth}")
private String basicAuth;
public String getAccessToken() {
String accessToken = null;
String methodName = new Object() {
}.getClass().getEnclosingMethod().getName();
try {
OAuthClient client = new OAuthClient(new URLConnectionClient());
OAuthClientRequest request = OAuthClientRequest.tokenLocation(tokenURL)
.setGrantType(GrantType.CLIENT_CREDENTIALS).buildBodyMessage();
request.addHeader(OAuth.HeaderType.AUTHORIZATION, "Basic " + basicAuth);
accessToken = client.accessToken(request, OAuthJSONAccessTokenResponse.class).getAccessToken();
} catch (Exception exn) {
exn.printStackTrace();
}
return accessToken;
}
}
PxPrepareRestClient.java
------------------------
package com.ctl.px.api.client;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.boot.web.client.RestTemplateBuilder;
import org.springframework.http.HttpEntity;
import org.springframework.http.HttpHeaders;
import org.springframework.http.MediaType;
import org.springframework.http.ResponseEntity;
import org.springframework.http.converter.json.MappingJackson2HttpMessageConverter;
import org.springframework.stereotype.Component;
import org.springframework.web.client.RestTemplate;
import com.ctl.px.api.model.PrepareRequestObj;
@Component
public class PxPrepareRestClient {
@Autowired
private PxAuthenticationService authenticationService;
@Autowired
private RestTemplateBuilder restTemplateBuilder;
@Value("${px.prepare.url}")
private String prepareUrl;
Logger log = LoggerFactory.getLogger(PxPrepareRestClient.class);
public ResponseEntity<String> prepare(PrepareRequestObj prepareRequest) {
RestTemplate restTemplate;
restTemplate = restTemplateBuilder.build();
String accessToken = authenticationService.getAccessToken();
log.debug("Using access token: " + accessToken);
HttpHeaders headers = new HttpHeaders();
headers.add("Authorization", "Bearer " + accessToken);
headers.setContentType(MediaType.APPLICATION_JSON);
restTemplate.getMessageConverters().add(new MappingJackson2HttpMessageConverter());
ResponseEntity<String> response = null;
try {
HttpEntity<PrepareRequestObj> request = new HttpEntity<>(prepareRequest, headers);
response = restTemplate.postForEntity(prepareUrl, request, String.class);
} catch (Exception e) {
log.debug("Exception occurred while making rest call to " + prepareUrl + ", Exception was: "
+ e.getStackTrace());
}
return response;
}
}
PxRequestAppointmentClient.java
-------------------------------
package com.ctl.px.api.client;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.boot.web.client.RestTemplateBuilder;
import org.springframework.http.HttpEntity;
import org.springframework.http.HttpHeaders;
import org.springframework.http.MediaType;
import org.springframework.http.ResponseEntity;
import org.springframework.http.converter.json.MappingJackson2HttpMessageConverter;
import org.springframework.stereotype.Component;
import org.springframework.web.client.RestTemplate;
import com.ctl.px.api.model.RequestAppointmentObj;
@Component
public class PxRequestAppointmentClient {
@Autowired
private PxAuthenticationService authenticationService;
@Autowired
private RestTemplateBuilder restTemplateBuilder;
@Value("${px.requestAppointment.url}")
private String requestAppointmentUrl;
Logger log = LoggerFactory.getLogger(PxRequestAppointmentClient.class);
public ResponseEntity<String> requestAppointment(RequestAppointmentObj appointmentRequest) {
RestTemplate restTemplate;
restTemplate = restTemplateBuilder.build();
String accessToken = authenticationService.getAccessToken();
log.debug("Using access token: " + accessToken);
HttpHeaders headers = new HttpHeaders();
headers.add("Authorization", "Bearer " + accessToken);
headers.setContentType(MediaType.APPLICATION_JSON);
restTemplate.getMessageConverters().add(new MappingJackson2HttpMessageConverter());
ResponseEntity<String> response = null;
try {
HttpEntity<RequestAppointmentObj> request = new HttpEntity<>(appointmentRequest, headers);
response = restTemplate.postForEntity(requestAppointmentUrl, request, String.class);
} catch (Exception e) {
log.debug("Exception occurred while making rest call to " + requestAppointmentUrl + ", Exception was: "
+ e.getStackTrace());
}
return response;
}
}
PxConfirmAppointmentClient.java
-------------------------------
package com.ctl.px.api.client;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.boot.web.client.RestTemplateBuilder;
import org.springframework.http.HttpEntity;
import org.springframework.http.HttpHeaders;
import org.springframework.http.MediaType;
import org.springframework.http.ResponseEntity;
import org.springframework.http.converter.json.MappingJackson2HttpMessageConverter;
import org.springframework.stereotype.Component;
import org.springframework.web.client.RestTemplate;
import com.ctl.px.api.model.SelectAppointmentRequestObj;
@Component
public class PxConfirmAppointmentClient {
@Autowired
private PxAuthenticationService authenticationService;
@Autowired
private RestTemplateBuilder restTemplateBuilder;
@Value("${px.confirmAppointment.url}")
private String confirmAppointmentUrl;
Logger log = LoggerFactory.getLogger(PxConfirmAppointmentClient.class);
public ResponseEntity<String> confirmAppointment(SelectAppointmentRequestObj confirmAppointmentRequest) {
RestTemplate restTemplate;
restTemplate = restTemplateBuilder.build();
String accessToken = authenticationService.getAccessToken();
log.debug("Using access token: " + accessToken);
HttpHeaders headers = new HttpHeaders();
headers.add("Authorization", "Bearer " + accessToken);
headers.setContentType(MediaType.APPLICATION_JSON);
restTemplate.getMessageConverters().add(new MappingJackson2HttpMessageConverter());
ResponseEntity<String> response = null;
try {
HttpEntity<SelectAppointmentRequestObj> request = new HttpEntity<>(confirmAppointmentRequest, headers);
response = restTemplate.postForEntity(confirmAppointmentUrl, request, String.class);
} catch (Exception e) {
log.debug("Exception occurred while making rest call to " + confirmAppointmentUrl + ", Exception was: "
+ e.getStackTrace());
}
return response;
}
}
API Name | Reason | API Status Code | Internal Message Code | User Message |
Prepare | Sales Code | 401 | 2000 | Missing or Invalid <B>; TxID <> |
Prepare | Transaction Id | 410 | 2070 | Missing or Invalid <B>; TxID <> |
Prepare | Partner ID | 401 | 2030 | Missing or Invalid <B>; TxID <> |
Prepare | addressDetailId | 401 | 2025 | Missing or Invalid <B>; TxID <> |
Prepare | Promocode not availble in Config response | 410 | 2100 | Invalid <B>; TxID <> |
Prepare | Product code not availble in Config response | 410 | 2110 | Invalid <B>; TxID <> |
Prepare | Promocode does not apply to selected Product Code | 410 | 2180 | PromoCode <> not applicable ot selected ProductCode <>; TxID <> |
Prepare | Product code not submitted in Prepare request (required) | 410 | 2120 | Missing <B>; TxID <> |
Prepare | Modem Product Codes missing | 410 | 1100 | Modem product code missing; TxID <> |
Prepare | Tech Install Product Codes missing | 410 | 1110 | Tech Install product code missing; TxID <> |
Prepare | Device Quantity not accurate (non Modem) | 410 | 1120 | DeviceQuantity <> invalid; TxID <> |
Prepare | If payment required but PaymentToken not provided | 410 | 1130 | Because payment is required, token must be provided. Please correct and resend. TxID <> |
Prepare | Partner Order ID used with another Order (exceptions are use of same combination on reconfig or new config to alter payment method and/or ‘correct and resubmit’ requests). |
410 | 2130 | SalesCode <> and PartnerOrderId <> combination must be unique; TxID <> |
Prepare | Partner Order ID is not provided (but is required)? | 410 | 2225 | Missing Partner Order Id <>; TxID <> |
Prepare | Cannot submit 2nd (or subsequent) order for same address within 30 days; unless previous order was cancelled | 410 | 3300 | CenturyLink received an order for service at this address within the last [30] days on order number <>. Please call <B> to make changes to this order; TxID <> |
Prepare | Prepaid and no preffered username provided | 410 | 1140 | Prepaid service requires Preferred Username to be provided; TxID <> |
Prepare | Shipping Street Address not complete or missing | 410 | 1150 | Missing or Invalid <B>; TxID <> |
Prepare | Shipping Address does not have a city | 410 | 1160 | Missing or Invalid <B>; TxID <> |
Prepare | Shipping Address does not have a state or a valid state ID | 410 | 1170 | Missing or Invalid <B>; TxID <> |
Prepare | Shipping Address does not have a zip code or a valid zip code | 410 | 1180 | Missing or Invalid <B>; TxID <> |
Prepare | Billing Street Address not complete or missing | 410 | 1150 | Missing or Invalid <B>; TxID <> |
Prepare | Billing Address does not have a city | 410 | 1160 | Missing or Invalid <B>; TxID <> |
Prepare | Billing Address does not have a state or a valid state ID | 410 | 1170 | Missing or Invalid <B>; TxID <> |
Prepare | Billing Address does not have a zip code or a valid zip code | 410 | 1180 | Missing or Invalid <B>; TxID <> |
Prepare | Email Validation Prepaid (future use via Neverbounce) | 410 | 1225 | Prepaid order requires valid email <>; please correct and resubmit TxID <> |
Prepare | Email is missing for prepaid | 410 | 1190 | Email required for pre-paid products; TxID <> |
Prepare | Email is missing for eBill | 410 | 1195 | Email required for paperless billing; TxID <> |
Prepare | "Paperless Bill Option", "Billing & Order Email Notification", and/or "Billing & Order SMS Notification" is missing or invalid | 410 | 1185 | Missing or Invalid <B>; TxID <> |
Prepare | Cannot send device quantity when submitting self install for Prepare (DeviceQuantity only applies for Tech Install) | 410 | 1198 | Invalid Device Quantity <B> without Tech Install; TxID <> |
Prepare | If remarkTypes is either Order or Action ensure we get remarkValue OR if a remarkValue is populated, then the remarkType must be there also | 410 | 1200 | If Order Remark is included then Order Value is requried or if Order Value is included then Order Remark is required; TxID <> |
Prepare | A prepare connot be submitted >120 minutes after succesful config | 410 | 2210 | A prepare order cannot be executed more than 120 minutes after the corresponding config; TxID <> |
Prepare | Username is already in-use | 410 | 1220 | Username <> is in use, please correct and resubmit; TxID <> |
Prepare | Partner Order ID and transaction combination must be unique to a config request and must remain constant thru order submit. Cannot submit a new Partner Order ID with an already used transaction ID on a new config request. Cannot alter partner order ID and transaction ID through the order flow through submit request. |
410 | 2131 | Transaction Id <B> and PartnerOrderId <> combination must remain constant through Submit; TxID <> |
Request Appointment | Sales code | 401 | 2000 | Missing or Invalid <B>; TxID <> |
Request Appointment | Partner ID | 401 | 2030 | Missing or Invalid <B>; TxID <> |
Request Appointment | addressDetailId | 401 | 2025 | Missing or Invalid <B>; TxID <> |
Request Appointment | Partner Order ID is not provided (but is required)? | 2225 | Missing Partner Order Id <>; TxID <> | |
Request Appointment | Partner Order ID and transaction combination must be unique to a config request and must remain constant thru order submit. Cannot submit a new Partner Order ID with an already used transaction ID on a new config request. Cannot alter partner order ID and transaction ID through the order flow through submit request. |
410 | 2131 | Transaction Id <B> and PartnerOrderId <> combination must remain constant through Submit; TxID <> |
Confirm Appointment | Sales code | 401 | 2000 | Missing or Invalid <B>; TxID <> |
Confirm Appointment | Partner ID | 401 | 2030 | Missing or Invalid <B>; TxID <> |
Confirm Appointment | addressDetailId | 401 | 2025 | Missing or Invalid <B>; TxID <> |
Confirm Appointment | Partner Order ID is not provided (but is required)? | 2225 | Missing Partner Order Id <>; TxID <> | |
Comfirm Appointment | Appointment date missing or invalid | 410 | 1096 | Missing or Invalid <B>; date must be in format mm/dd/yyyy TxID <> |
Comfirm Appointment | After time is missing or invalid | 410 | 1097 | Missing or Invalid <B>; TxID <> |
Comfirm Appointment | Before time is missing or invalid | 410 | 1097 | Missing or Invalid <B>; TxID <> |
Comfirm Appointment | Complete time is missing or invalid | 410 | 1097 | Missing or Invalid <B>; TxID <> |
Confirm Appointment | Partner Order ID and transaction combination must be unique to a config request and must remain constant thru order submit. Cannot submit a new Partner Order ID with an already used transaction ID on a new config request. Cannot alter partner order ID and transaction ID through the order flow through submit request. |
410 | 2131 | Transaction Id <B> and PartnerOrderId <> combination must remain constant through Submit; TxID <> |
Partners who would like to have API access please contact PXAPIAccessandSupport@lumen.com.
For API-specific support please complete the support form select the Help -> Contact Us menu option.