-
Notifications
You must be signed in to change notification settings - Fork 0
Documents API
The Documents API is not part of the Despatch Bay SOAP API but acts as a companion API to it
The Documents API supersedes the PDF Labels Webservice. It provides all the features of the old service whilst adding support for manifests. The Despatch Bay Documents API provides a means of programatically requesting label and manifest documents relating to shipments and collections in Despatch Bay.
The Documents API is composed of two endpoints.
https://api.despatchbay.com/documents/v1/labels
The labels endpoint allows a client to obtain one or more shipping labels relating either to one or more shipments or to a single collection. For more information about labels see Working with Labels.
https://api.despatchbay.com/documents/v1/manifest
The manifest endpoint allows a client to obtain a manifest document relating to a single Despatch Bay collection. For more information about manifests see Working with Manifests.
The labels endpoint supports the fetching of labels relating to either:
A document ID identifies either a shipment or a collection and can be used to obtain labels and/or manifest documents.
Document IDs are obtained from the Despatch Bay API's Shipping Service.
Document IDs are only generated once a shipment has been booked and paid for, eg. using the BookShipments call in the Despatch Bay API's Shipping Service.
Important: Your document IDs must be considered secret. You should never reveal your document IDs to an end user or send an end user directly to a Documents API endpoint. Rather the Documents API should be used internally by your application to obtain documents for use by you or your end user indirectly.
| Parameter | Accepted values | Required | Description |
|---|---|---|---|
format |
pdf, pdf_base64 or png_base64
|
N |
pdf (default) returns an application/pdf document pdf_base64 returns a base64 string encoding of an application/pdf document png_base64 returns a json array of base64 encoded pngs |
layout |
1A6, 1A4 or 2A4
|
N |
1A6 (default) produces an A6 label on an A6 page 1A4 produces a document with one A6 label image set within each A4 landscape page 2A4 produces a document with two A6 label images set within each A4 landscape page |
dpi |
any integer value between 72 and 300
|
N | Only applicable when the format is png_base64 . The default dpi value is 300
|
Tip: It is important to note that shipment can contain multiple parcels and that some international services may actually return more than one label per parcel. Therefore the number of pages returned should never be assumed.
To obtain the labels for a single shipment you must pass the Document ID of the shipment to the labels endpoint. This method of obtaining labels is most suited to a use case whereby labels are printed one at a time immediately or soon after booking. It is possible to pass an explicit format parameter, either pdf or base64 and you must pass a layout parameter to specify a particular page layout for your labels.
Example URL:
https://api.despatchbay.com/documents/v1/labels/{shipment_document_id}?format=pdf&layout=1A6
To obtain the labels for multiple shipment you can pass a comma-separated list of Document IDs to the labels endpoint. Please note however that this method is not recommended for large numbers of document ids as you may run into maximum URL length issues.
It is possible to pass an explicit format parameter, either pdf or base64 and you must pass a layout parameter to specify a particular page layout for your labels.
Example URL:
https://api.despatchbay.com/documents/v1/labels/{shipment_document_id},{shipment_document_id},{shipment_document_id}?format=pdf&layout=1A6
To obtain all the labels for a single collection you can pass the Document ID of a collection to the labels endpoint. This method of obtaining labels is most suited to a use case where labels are booked throughout the day and printed en masse before collection.
It is possible to pass an explicit format parameter, either pdf or base64 and you must pass a layout parameter to specify a particular page layout for your labels.
Example URL:
https://api.despatchbay.com/documents/v1/labels/{collection_document_id}?format=pdf&layout=1A6
The labels generated by Despatch Bay are approved courier shipping labels and should not be modified in any way. Care should be taken to ensure that labels are printed at 100% scale.
Each label image should be physically printed at A6 size (105 x 148mm).
Any deviation from the specified dimensions may cause scanning errors causing your shipments to be delayed or misrouted by our partner couriers.
It is acceptable to store generated labels for future use but care should be taken so that no label is inadvertently used more than once. Once a label has been printed and used it should be put beyond use.
Warning: Neither Despatch Bay nor our partner couriers will be held responsible for issues arising from duplicate labels entering the network. Duplicate labels may cause delayed, misrouted or lost items and upon detection by our partner couriers your account may be subject to penalties or closure.
A manifest document is an itemised list of parcels included in a single collection. For some couriers this document may act as a collection receipt whilst for others it is merely for your own reference. The manifests endpoint supports the fetching of manifest documents relating to a single collection.
| Parameter | Accepted values | Required | Description |
|---|---|---|---|
| format |
pdf or base64
|
Y |
pdf returns an application/pdf document base64 returns a base64 string encoding of an application/pdf document |
To obtain the manifest document for a single collection you can pass the Document ID of a collection to the manifests endpoint.
It is possible to pass a format parameter, either pdf or base64 to explicitly set the response format. If no format parameter is set then the default format of pdf will be used.
Example URL:
https://api.despatchbay.com/documents/v1/manifest/{collection_document_id}?format=pdf