Response - Success
If you are able to successfully parse the data from Peoplevox, contact the carrier system, and obtain labels and tracking numbers, then your endpoint should respond with a success message in the following format.
In this example, the endpoint responded with two types of tracking number, and three different documents:
{
"status": "success",
"message": null,
"data": {
"trackingNumbers": [
{
"trackingType": "outbound",
"trackingNumber": "TRCK123456789"
},
{
"trackingType": "returns",
"trackingNumber": "TRCK987654321"
}
],
"newPrintRequests": [
{
"printRequestId": 1,
"printTemplateUrl": "https://mycarrierintegrationhost.com/labels/1_label.pdf",
"status": "success"
},
{
"printRequestId": 2,
"printTemplateUrl": "https://mycarrierintegrationhost.com/customs/1_customs.pdf",
"status": "success"
},
{
"printRequestId": 3,
"printTemplateUrl": "https://mycarrierintegrationhost.com/returnslabels/1_returns.pdf",
"status": "success"
}
],
"serviceType": "EXT_RM48"
}
}The success message indicates that the Peoplevox platform should attempt to print the indicated labels and assign the tracking numbers.
The Peoplevox platform will extract each of the tracking numbers provided and format them according to a template defined by the user in Peoplevox; for example a user may wish to concatenate the “outbound” and “returns” tracking numbers into a single string.
The "serviceType" property indicates that the carrier integration selected a different service from the one that was provided on the request. This indication might occur because the request was for a service class rather than a specific service, or it may be an instruction for the carrier integration to run some business rules to determine the best service. It could simply be that the carrier integration determined that the selected service was not valid and suggested an alternative. serviceType is an optional property on the response. If provided, Peoplevox will try to find a matching service type (using the "outboundReference" on the service), and save that (or "Unknown service" if no matching service found) against the package. If this property is not included on the response, then the service on the package will not be updated.
In some cases, users in Peoplevox may request a document that is not required. A common example of this is where a user requests customs documentation for a domestic shipment. In these situations, the overall response should still be treated as a success, but you should use the “not required” status on the documents that are not needed.
This status lets Peoplevox know that there was no error during the request, but fewer documents will be printed than were requested:
{
"status": "success",
"message": null,
"data": {
"trackingNumbers": [
{
"trackingType": "outbound",
"trackingNumber": "TRCK123456789"
},
{
"trackingType": "returns",
"trackingNumber": "TRCK987654321"
}
],
"newPrintRequests": [
{
"printRequestId": 1,
"printTemplateUrl": "https://mycarrierintegrationhost.com/labels/1_label.pdf",
"status": "success"
},
{
"printRequestId": 2,
"printTemplateUrl": null,
"status": "not required"
},
{
"printRequestId": 3,
"printTemplateUrl": "https://mycarrierintegrationhost.com/returnslabels/1_returns.pdf",
"status": "success"
}
],
"serviceType": "EXT_RM48"
}
}Response - Partial Success
There are situations in which parts of the request may succeed while other parts fail. For example, a carrier may successfully generate one of the two requested documents, but fail to generate the other. In that case, a “partial” response is appropriate.
The structure of this response is the same as a full success, but your endpoint should return some indication of which aspects failed and why.
{
"status": "partial",
"message": "Unable to generate customs documentation: insufficient product data",
"data": {
"trackingNumbers": [
{
"trackingType": "outbound",
"trackingNumber": "TRCK123456789"
},
{
"trackingType": "returns",
"trackingNumber": "TRCK987654321"
}
],
"newPrintRequests": [
{
"printRequestId": 1,
"printTemplateUrl": "https://mycarrierintegrationhost.com/labels/1_label.pdf",
"status": "success"
},
{
"printRequestId": 2,
"printTemplateUrl": null,
"status": "fail"
},
{
"printRequestId": 3,
"printTemplateUrl": "https://mycarrierintegrationhost.com/returnslabels/1_returns.pdf",
"status": "success"
}
],
"serviceType": "EXT_RM48"
}
}Response - Failure
There are situations in which a request may completely fail. For example, the user may have requested documentation for a carrier that does not support the requested country. In these situations, a “fail” response is appropriate.
As with the partial success, the structure of the response is the same:
{
"status": "fail",
"message": "The requested carrier does not support shipments from the UK",
"data": {
"trackingNumbers": null,
"newPrintRequests": [
{
"printRequestId": 1,
"printTemplateUrl": null,
"status": "fail"
},
{
"printRequestId": 2,
"printTemplateUrl": null,
"status": "fail"
},
{
"printRequestId": 3,
"printTemplateUrl": null,
"status": "fail"
}
]
}
}