What does a carrier integration do?
A carrier integration with Peoplevox allows Peoplevox users to print carrier labels for their orders as they despatch them, and for Peoplevox to obtain the tracking numbers back from the carrier.
Your carrier integration will be responsible for accepting shipment data from Peoplevox, communicating with carrier APIs to generate labels, and then communicating the results back to Peoplevox.
Your response back to Peoplevox contains URLs to the requested documents (as PDF files), and one or more tracking numbers for the shipment.
Peoplevox will then pull down the documents from those URLs, and send them to the warehouse printers. Peoplevox will also save the tracking data, and fire off the relevant tracking number events to any subscribers.
How do I build a carrier integration?
Architecture
To build a carrier integration, you will need to create and host a simple API that Peoplevox can connect to. This API will listen for, and respond to, shipment notifications from Peoplevox. If you already have an existing API, then you will need to create and host a facade that meets the specifications below, and Peoplevox will use that facade as the endpoint.
You will then need to register your API with the Peoplevox account that will be using the integration, so that the WMS knows where to send shipment data.
When an operator in Peoplevox requests carrier documentation (which typically occurs as the final step of the Peoplevox despatch process), the platform will POST you a JSON payload that contains:
A description of the despatched package, including the destination address, dimensions, and details of the items in the package
A collection of requested documentation types, e.g. carrier label, returns label, customs documentation, etc.
Your endpoint accepts that POST, holds the connection open while it talks to your back-end to generate the requested documents, and then responds with tracking numbers and URLs to your documents.
That API is the touch-point between Peoplevox and your system. So long as you accept the shipment data, and return a response in the formats described in this document, then you are free to implement the logic between that request and response as you see fit.
This document describes your endpoint as a RESTful API because the communication process can be framed in the context of resource creation. The POST from the Peoplevox platform is a request for your endpoint to generate a Document Bundle resource (a full description of this is included later in the document).
The Document Bundle resource is essentially a log of the request and response. Your endpoint:
Receives the request from Peoplevox
Builds the response by working with whatever back-end services and carrier APIs you need to use
Constructs the Document Bundle resource that contains both the request and response
Responds to Peoplevox with the response portion of that resource
Your endpoint is only required to respond to POST requests, but it may optionally respond to GET requests as well. It must NOT permit updates to existing Document Bundles, regardless of the verb used. Framing the process like this ensures that effective and reliable logging is baked into every integration.