Your endpoint needs to accept a POST request from the Peoplevox platform, which will contain a JSON payload that describes a shipment and the documentation requested for it.
This will always be an HTTPS POST request, and will include an Authorization header that provides an API key in the form of a Bearer token.
The request will provide Accept and Content-Type headers of application/json. It may also include additional headers.
Due to the fact that the endpoint is a layer of abstraction between Peoplevox and the carrier platform itself, you have some flexibility in the way you transform requests from Peoplevox into the requests that you make to the carrier platform.
A common example of this principle is authentication. This document defines that the authentication process between Peoplevox and the endpoint uses an API key as a Bearer token, but that does not necessarily require the same authentication process to be implemented between the endpoint and your back-end services. For example, your endpoint might authenticate the request from Peoplevox using the Bearer token, and then provide a different authentication token to your carrier system.
Your integration is responsible for specifying the types of documentation that it supports, as well as the different types of tracking number. You specify these when you register your endpoint.
A typical integration would support between one and three of the following types of document:
Carrier label
Customs documentation
Returns label
And one or both of these types of tracking number:
Outbound
Returns
However, you are not constrained by these. Your integration defines the types of document it supports, and that determines what the Peoplevox user is able to request from your integration. Please refer to the section on “Registering your endpoint” for more information.
The DocumentBundle resource
The DocumentBundle resource represents the combination of a request and a response. It acts as a log of the data provided by Peoplevox, and the data returned by the endpoint. The basic structure is just a combination of these two entities:
{
"request" : { },
"response" : { }
}
For example, the DocumentBundle for a successful call with some test data would look something like this (the details of the request and response are described below):
{
"request" : {
"metadata" : {
"schemaVersion" : "1.0",
"platformVersion" : "1.0",
"documentBundleEndpointVersion" : "1.0"
},
"despatchPackage" : {
"despatchPackageId" : 1,
"despatch" : {
"despatchNumber" : "DES100",
"carrier" : {
"name" : "Royal Mail",
"reference" : "RM"
},
"serviceType" : {
"name" : "Royal Mail Next Day",
"code" : "RM24",
"outboundReference" : ""
},
"loadReference" : "",
"salesOrder" : {
"salesOrderNumber" : "SO100",
"customer" : {
"name" : "Matt Thomson",
"reference" : "123456789",
"firstName" : "Matt",
"lastName" : "Thomson",
"phone" : "",
"mobile" : "",
"email" : "matt.thomson@peoplevox.com",
"creditLimit" : "",
"paymentTerm" : ""
},
"customerPurchaseOrderReferenceNumber" : "",
"shippingAddress" : {
"line1" : "119",
"line2" : "Marylebone Road",
"townCity" : "London",
"region" : "",
"postCode" : "NW1 5PU",
"countryName" : "United Kingdom",
"countryCode" : "UK"
},
"invoiceAddress" : {
"line1" : "119",
"line2" : "Marylebone Road",
"townCity" : "London",
"region" : "",
"postCode" : "NW1 5PU",
"countryName" : "United Kingdom",
"countryCode" : "UK"
},
"requestedDeliveryDate" : "01/01/2018 00:00:00",
"shippingCost" : "0.00",
"email" : "matt.thomson@peoplevox.com",
"contactName" : "Matt Thomson",
"paymentMethod" : "Cash",
"totalSale" : "0.00",
"discount" : "0.00",
"taxPaid" : "0.00",
"createdDate" : "",
"channelName" : "My website",
"attribute1" : "",
"attribute2" : "",
"attribute3" : "",
"attribute4" : "",
"attribute5" : "",
"site" : "PrimarySite"
}
},
"weight" : "0.00",
"height" : "0.00",
"width" : "0.00",
"depth" : "0.00",
"packageType" : {
"name" : "",
"barcode" : ""
},
"packageNumber" : 1,
"carrier" : {
"name" : "Royal Mail",
"reference" : "RM"
},
"serviceType" : {
"name" : "Royal Mail Next Day",
"code" : "RM24",
"outboundReference" : ""
},
"despatchItems" : [
{
"itemType" : {
"itemCode" : "ItemA",
"name" : "Item A",
"barcode" : "ITEMA001",
"description" : "This is a lovely widget",
"itemGroup" : "Widgets",
"unitOfMeasure" : {
"name" : "Unit",
"symbol" : "EA"
},
"defaultSupplierPartNumber" : "MYWIDGETA",
"buyPrice" : "0.00",
"wholesalePrice" : "0.00",
"retailPrice" : "0.00",
"weight" : "1.00",
"weightMeasure" : "kg",
"height" : "1.00",
"width" : "1.00",
"depth" : "1.00",
"dimensionMeasure" : "cm",
"tags" : "",
"taxCode" : "",
"attribute1" : "",
"attribute2" : "",
"attribute3" : "",
"attribute4" : "",
"attribute5" : "",
"attribute6" : "",
"attribute7" : "",
"attribute8" : "",
"attribute9" : "",
"attribute10" : "",
"attribute11" : "",
"attribute12" : "",
"attribute13" : "",
"attribute14" : "",
"attribute15" : ""
},
"quantity" : 1,
"container" : {
"barcode" : "",
"reference" : ""
}
}
]
},
"oldPrintRequests" : [
{
"printRequestId" : 1,
"documentReference" : "Carrier label"
},
{
"printRequestId" : 2,
"documentReference" : "Customs documentation"
},
{
"printRequestId" : 3,
"documentReference" : "Returns label"
}
]
},
"response" : {
"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"
}
]
}
}
}