If the carrier system you want to use does not support an API capable of receiving the label requests from PVX, you can instead have PVX download the same data to a local file on the workstation performing the despatch.
This download supports two file formats:
XML (legacy, not actively maintained)
JSON (latest stable data schema)
The JSON file will contain the despatchPackage entity from the request schema documented here.
Key Differences
Users and partners who currently consume the XML file format will notice that the JSON file contains significantly more data. Specifically, the new format exposes the full set of properties from the package, sales order, and item type records.
The JSON format is package-oriented, rather than order-oriented. Each file represents a single package, and the items on the file are the items in that specific package. The file naming convention has been updated to reflect this, and now uses the following format:
{DespatchNumber}_{PackageNumber}.PVX2
For example, for the second package of despatch DES123 would be named:
DES123_2.PVX2
The "Download" button on the Despatch tab of the web app will download all PVX2 files for the selected despatch.
The JSON file also contains detailed information about any kitted items that are in the package. Both the kit parent and the components are listed, so that each integration can consume whichever level of detail is relevant for them.
Moving from XML to JSON
Most of the work involved in moving from XML to JSON will be in how integrations consume that file and extract the data from it.
All the data that was available on XML is also available on the JSON format (though it may be in a slightly different place relative to other properties), so any data that was previously being passed through to carriers will still be present.
The mechanism for triggering the download of the file has not changed between XML and JSON. Both file types are generated at the end of the web app despatch process after confirming the despatch of a given package. Where the XML file would have contained a growing list of packages for each despatch against an order, the JSON files will be more independent and each file will only contain package data for that specific package (though each JSON file will still include the same order data). The result is that each JSON file should have sufficient information to request a label from a carrier without needing to cross-reference against any other files or make any calls back to the PVX API for additional context.
Typically, integrations that consumed this XML file also submitted tracking data to PVX through a SaveData API request. That mechanism has not changed, and integrators can continue to use this approach regardless of the file format they consume.
Maintaining JSON-based Integrations
The JSON file format is distinguished from the XML format by a different file extension (.pvx2 from the previous .pvx).
Any changes or additions that would break compatibility will be released in a new format with a new file extension. Examples of these changes would be:
Removing existing fields or sections
Renaming elements within the file
Moving elements between hierarchy levels, such as moving a property from the despatchPackage to the despatch
Smaller additions that do not break backward compatibility may be automatically included in the file without an update to the extension. Examples of non-breaking changes include:
Additions of new properties to existing objects, such as a new field on the sales order record
Additions of new content options for existing fields, such as a new service type option
Moving elements around within the same hierarchy level, such as swapping the position of two elements on the despatchPackage
Note that the sequence of elements within a hierarchy level is not guaranteed to remain consistent. Integrators should not be reliant on any particular ordering of elements when consuming the file.
Any structural changes will be documented here.
Example (Based on the 2.0 JSON Schema):
This is an example of the DES123_1.pvx2 file:
{
"despatchPackage": {
"packageType": {
"name": null,
"barcode": null
},
"carrier": {
"name": "Royal Mail",
"reference": "RM"
},
"serviceType": {
"name": "Royal Mail Next Day",
"code": "RM24",
"outboundReference": "EXT_RM24"
},
"items": [
{
"container": {
"barcode": null,
"reference": null
},
"itemType": {
"itemCode": "Widget001",
"name": "A Widget",
"barcode": "WIDGET001",
"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": "3.00",
"weightMeasure": "kg",
"height": "3.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": "",
"hsCode": "6101",
"countryOfOrigin": "GBR",
"dryIce": false,
"medicalDryIce": false,
"alcohol": false,
"hazardous": false
},
"salePrice": "20.00",
"salesOrderItemAttribute1": null,
"salesOrderItemAttribute2": null,
"salesOrderItemAttribute3": null,
"salesOrderItemLine": "1",
"quantity": 1,
"components": null
}
],
"despatchPackageId": 1,
"despatch": {
"carrier": {
"name": "Royal Mail",
"reference": "RM"
},
"serviceType": {
"name": "Royal Mail Next Day",
"code": "RM24",
"outboundReference": "EXT_RM24"
},
"salesOrder": {
"customer": {
"name": "Matt Thomson",
"reference": "123456789",
"firstName": "Matt",
"lastName": "Thomson",
"phone": null,
"mobile": null,
"email": matt.thomson@peoplevox.com,
"creditLimit": "",
"paymentTerm": null
},
"shippingAddress": {
"line1": "119",
"line2": "Marylebone Road",
"townCity": "London",
"region": null,
"postCode": "NW1 5PU",
"countryName": "United Kingdom",
"countryCode": "UK"
},
"invoiceAddress": {
"line1": "119",
"line2": "Marylebone Road",
"townCity": "London",
"region": null,
"postCode": "NW1 5PU",
"countryName": "United Kingdom",
"countryCode": "UK"
},
"salesOrderNumber": "SO123",
"customerPurchaseOrderReferenceNumber": null,
"requestedDeliveryDate": "01/04/2022 00:00:00",
"shippingCost": "0.00",
"email": "matt.thomson@peoplevox.com",
"contactName": "Matt Thomson",
"paymentMethod": "Cash",
"totalSale": "20.00",
"discount": "0.00",
"taxPaid": "0.00",
"createdDate": "",
"channelName": "My website",
"attribute1": null,
"attribute2": null,
"attribute3": null,
"attribute4": null,
"attribute5": null,
"site": "PrimarySite",
"currency": "GBP",
"termsOfTrade": "DDP",
"customsRegistrationNumber": "EoriNumbersOrSimilar",
"iossNumber": "YourIossNumber"
},
"despatchNumber": "DES123",
"loadReference": null
},
"weight": "3.00",
"weightMeasure": "kg",
"height": "3.00",
"heightMeasure": "cm",
"width": "1.00",
"widthMeasure": "cm",
"depth": "1.00",
"depthMeasure": "cm",
"packageNumber": 1
}
}