Batch Container Label API¶
Note
Draft content. This operation is coming soon. This page is a draft.
HTTP Request¶
POST /v1/container-manifest/Batch?carrier=PBI
Summary¶
This operation prints a batch of container labels for containerized CBDS parcels that use International Inbound shipping. The API returns the container labels in a single PDF file. Each page in the PDF is a different container label.
Before issuing this API call, you must print the parcel labels using the CBDS International Inbound API.
Note: This operation is specific to CBDS. To create a container label for a different carrier, see this operation.
Prerequisite¶
To use this API, a merchant must contact Pitney Bowes for enablement. The merchant should contact either ClientSupportTechServices@pb.com, or ShippingAPIBusinessDevelopment@pb.com, or the implementation manager.
Considerations¶
The operation prints container labels for parcel shipments created with the CBDS International Inbound API.
The operation returns a PDF with a separate page for each container label.
This operation returns a batch ID for the labels in the
batchContainerManifestId
field.If you need to reprint the container labels, use the Reprint Batch Container Labels API. When you reprint, you must pass the
batchContainerManifestId
in the reprint request.If the label fails and you need to retry it, reissue this Batch Container Label API but use a new Transaction ID (
X-PB-TransactionId
).
Request URLs¶
Sandbox: https://shipping-api-sandbox.pitneybowes.com/shippingservices/v1/container-manifest/Batch?carrier=PBI
Production: https://shipping-api.pitneybowes.com/shippingservices/v1/container-manifest/Batch?carrier=PBI
Query Parameter¶
Name |
Description |
---|---|
carrier |
Required. The carrier for the parcels in the container. Valid value:
|
Request Headers¶
Name |
Description |
---|---|
Authorization |
Required. OAuth token generated using the Generate an OAuth Token API. |
Content-Type |
Required. The media type of the request entity. Set this to |
X-PB-TransactionId |
Required. A unique identifier for the transaction, up to 25 characters. The following characters are allowed: letters, numbers, hyphens ( Important: Ensure this is a unique ID. |
Request / Response Elements¶
Name |
Data Type |
Description |
---|---|---|
containers |
Array[Container Object] |
Required. The containers to be shipped. The |
parameters |
Array[Object] |
Required. Specifies the Pitney Bowes hub that will receive the containers. |
parameters.name |
String |
Required. Enter the following: |
parameters.value |
String |
Required. The Pitney Bowes hub that will receive the containers. Possible values:
|
documents |
Array[Object] |
Defines properties for the returned container labels. This object is optional. The Batch Container Label API uses one set of properties for all container labels. If you leave this object out of the request, the API applies the default values. Note that if you choose to include the object, you must include all the object’s fields (except for the RESPONSE-only field) or the request will fail. |
documents.type |
String |
The type of document to be returned. Valid value: |
documents.size |
String |
The size of each container label. Valid value: |
documents.contentType |
String |
Indicates that the API returns the document as a Base64-encoded string that can be converted to a PDF. To convert, use a tool that converts Base64 to the application/pdf MIME type. Valid value: |
documents.fileFormat |
String |
Indicates the file format for the printable label. Valid value: |
documents.contents |
String |
RESPONSE ONLY. The Base64-encoded string that converts to a PDF. The PDF contains the container labels. Each label is a different page in the PDF. To convert, use a tool that converts Base64 to the application/pdf MIME type. |
references |
Array[Object] |
Defines reference fields. Each object in the array specifies a different reference and value. For available references, See References Array Reference Types. |
references.name |
String |
The reference. |
references.value |
String |
The reference’s value. |
batchContainerManifestId |
String |
RESPONSE ONLY. The unique shipment number generated by Pitney Bowes. This number appears as barcode and number on each container label returned in the PDF. If you need to reprint the container labels, you must pass the |
Container Object¶
Name |
Data Type |
Description |
---|---|---|
clientContainerId |
String |
Required. The client number for the container. Maximum length: 50 characters |
containerType |
String |
The type of container used to transport the parcels. Possible values:
|
submissionDate |
String |
The API includes all parcels that have been manifested but not shipped or containerized through the specified date. Specify the date in UTC/GMT and use the ISO 8601 extended format: YYYY-MM-DDThh:mm:ss.sssZ
The value must include both date and time and must end with
|
tareWeight |
Object |
The weight of the container when empty, before the parcels are added. |
tareWeight.Weight |
Big Decimal |
The weight of the empty container. If you enter a value for this field, you must also enter a value for |
tareWeight.unitOfMeasurement |
String |
The unit of measure for the tare weight. Valid values are:
|
dimension |
The container’s dimensions. |
|
totalParcelWeight |
Object |
The total scaled weight of all the parcels in the container, without the container weight (tare weight). |
totalParcelWeight.Weight |
Big Decimal |
The totals scaled weight of all the parcels. Do not include the container weight. |
totalParcelWeight.unitOfMeasurement |
String |
The unit of measure for the total weight. Valid values are:
|
parcelTrackingNumbers |
Array[Strings] |
Required. The tracking numbers of the parcels on this container, entered as Strings separated by commas. |
References Array Reference Types¶
The references
array in the Batch Container Label API takes the reference types described here. The references
array is optional in the request. Each reference type is optional in the array.
Name |
Description |
---|---|
|
Unique client shipment number. |
|
Unique client ground reference number (truck number). |
|
Unique client air reference number (airline number). |
Sample Request¶
curl -X POST ".../v1/container-manifest/batch?carrier=PBI" \
-H "Authorization: Bearer <oauth_token>" \
-H "Content-Type: application/json" \
-H "X-PB-TransactionId: 45672345" \
-d '
{
"containers": [ {
"clientContainerId": "CLIENT_CA_20220828_01",
"containerType": "BOX",
"tareWeight": {
"weight": 48.0,
"unitOfMeasurement": "LB"
},
"dimension": {
"length": 48.0,
"width": 36.0,
"height": 24.5,
"unitOfMeasurement": "IN"
},
"totalParcelWeight": {
"weight": 48.0,
"unitOfMeasurement": "LB"
},
"parcelTrackingNumbers": [
"UPBEE001699999999A16",
"UPBEE001699999999A12",
"UPBEE001699999999917",
"UPBEE001699999999918",
"UPBEE001699999999915"
]
},
...
],
"parameters": [ {
"name": "CARRIER_FACILITY_ID",
"value": "US_GLOBAL_ILA"
} ],
"documents": [ {
"type": "CONTAINER_LABEL",
"size": "DOC_4X6",
"fileFormat": "PDF",
"contentType": "BASE64"
} ],
"references": [ {
"name": "CLIENT_REFERENCE_NUMBER",
"value": "MerchantOrder-1195"
},{
"name": "CLIENT_GROUND_REFERENCE_NUMBER",
"value": "MerchantOrder-1195"
},{
"name": "CLIENT_AIR_REFERENCE_NUMBER",
"value": "MerchantOrder-1195"
} ]
}'
Sample Response¶
{
"containers": [ {
"clientContainerId": "CLIENT_CA_20220828_01",
"containerType": "BOX",
"tareWeight": {
"weight": 48.0,
"unitOfMeasurement": "LB"
},
"dimension": {
"length": 48.0,
"width": 36.0,
"height": 24.5,
"unitOfMeasurement": "IN"
},
"totalParcelWeight": {
"weight": 48.0,
"unitOfMeasurement": "LB"
},
"parcelTrackingNumbers": [
"UPBEE001699999999A16",
"UPBEE001699999999A12",
"UPBEE001699999999917",
"UPBEE001699999999918",
"UPBEE001699999999915"
]
},
...
],
"parameters": [ {
"name": "CARRIER_FACILITY_ID",
"value": "US_GLOBAL_ILA"
} ],
"documents": [ {
"type": "CONTAINER_LABEL",
"size": "DOC_4X6",
"fileFormat": "PDF",
"contentType": "BASE64",
"contents": "https://.../9de8b17ad4149f2ad1a5df38f054a9b.pdf"
} ],
"references": [ {
"name": "CLIENT_REFERENCE_NUMBER",
"value": "MerchantOrder-1195"
},{
"name": "CLIENT_GROUND_REFERENCE_NUMBER",
"value": "MerchantOrder-1195"
},{
"name": "CLIENT_AIR_REFERENCE_NUMBER",
"value": "MerchantOrder-1195"
} ],
"batchContainerManifestId": "<Id>"
}
Error Codes¶
The API uses the following error codes:
Error Code |
Error Message |
Solution |
---|---|---|
1009999 |
A system error occurred, try again later. If the error persists, please contact the service provider. |
|
1110001 |
Duplicate parceltrackingnumber in request. |
|
1110011 |
Invalid parcelTrackingNumber in request. |
|
1310002 |
Invalid or missing value |
|
1310005 |
Invalid parcelTrackingNumber-CarrierFacilityId in request. |
|
1310006 |
Voided parcelTrackingNumber in request. |
|
1310007 |
Document Generation Error. Please use Reprint API to generate the artifacts. |
For a list of all error codes returned by the Ecommerce APIs, please see Error Codes.