Create a Container Label¶
HTTP Request¶
POST /v1/container-manifest
Summary¶
This operation prints a Pitney Bowes container label for the shipment of containerized parcels from the client location to a Pitney Bowes facility. Upon arrival at the Pitney Bowes facility, the container label is scanned to confirm receipt.
Things to Consider¶
The operation returns a Pitney Bowes container ID and the container label.
The container label is returned either as raw ZPL or as a Base64-encoded PDF. If you return the label as a Base64-encoded PDF, you must convert the Base64 to the application/pdf MIME type.
If a shipper needs to make changes to a container label after printing it, the shipper can make the changes in the original request, enter a new value for the
X-PB-TransactionId
request header, and then reissue the request. The API will return a new label with a new container ID (pbContainerId
). The original label can be discarded.For example, if a shipper needs to change the tracking numbers in the
parcelTrackingNumbers
array or a parameter value in theparameters
array, the shipper can make the changes and reissue the request with a newX-PB-TransactionId
value to get a container label with the updated information.Shippers can also generate container labels through the Merchant Portal.
Request URIs¶
Sandbox URI: https://api-sandbox.pitneybowes.com/shippingservices/v1/container-manifest
Production URI: https://api.pitneybowes.com/shippingservices/v1/container-manifest
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 application/json . |
X-PB-TransactionId | Required. A unique identifier for the transaction, up to 25 characters. Important: You must ensure this is a unique id. |
Request Elements¶
Name | Data Type | Description |
---|---|---|
carrier | String | Required. The carrier. Possible value:
|
containerType | String | The type of container used to transport the parcels. Possible values:
|
parcelTrackingNumbers | Array[String] | Conditional. The parcels that are included in the container, identified
by their tracking numbers. The parcels must use the carrier listed in the
If you do not include the Note: If you include both the |
documents | Array[Object] | Required. Defines the container label. |
fileFormat | String | The file format for the printable label. Possible values:
|
size | String | The label size. Possible values:
Note: Clients are required to print 2 copies of labels and affix them on different sides of each container. This helps to increase scan speeds at Pitney Bowes facilities. |
resolution | String | The label’s dots per inch (DPI). By default, the resolution is 203 DPI. Possible values:
|
parameters | Array[Object] | Required. Defines reference fields and shipment options. Each object in the array specifies a different parameter and value. For available parameters, See Parameters. |
name | String | The parameter. |
value | String | The parameter’s value. |
Parameters¶
The parameters
array in the Create a Container Label request can take the
parameters described here.
Name | Description |
---|---|
CARRIER_FACILITY_ID | Required.The Pitney Bowes facility at which the container will be processed. Enter the numeric facility code. For a list of facilities, see PB Standard Facilities. |
CARRIER_GATEWAY_FACILITY_ID | Required.The Pitney Bowes facility at which the container will enter the PB network. Enter the numeric facility code. For a list of facilities, see PB Standard Facilities. |
CLIENT_CONTAINER_ID | The client’s container ID or container number. |
CLIENT_ID | Required. The carrier-specific client or merchant ID.
If testing in the Sandbox environment, set this to NGST . |
CURRENT_CONTAINER | The current container number. If you use this parameter, you should also use the TOTAL_CONTAINER_COUNT parameter. The label displays the parameters as follows: Container <CURRENT_CONTAINER> of <TOTAL_CONTAINER_COUNT> For example: Container 8 of 10 |
ESTIMATED_ARRIVAL_DATE | The estimated date the container will arrive, specified in the following
format: YYYY-MM-DD |
PACKAGE_COUNT | Conditional. The number of parcels in the container. This option is
required if you leave out the Note: If you include both the |
PRINT_CUSTOM_MESSAGE_1 | The handling instructions. This will appear on the label under “INSTRUCTIONS.” |
SHIP_DATE | Required. The date the container will be shipped, specified in the
following format: YYYY-MM-DD |
SHIPMENT_REFERENCE_NUMBER | The Bill of Lading or other shipment reference number associated with the container. |
TOTAL_CONTAINER_COUNT | The total number of containers in the shipment. If you use this parameter, you should also use the CURRENT_CONTAINER parameter. |
Response Elements¶
Name | Data Type | Description |
---|---|---|
data | Object | The label and label ID. |
pbContainerId | String | The unique Pitney Bowes identifier for the label. |
labelData | String | The label, returned either as raw ZPL or as a Base64-encoded string that must be be decoded as a PDF using a tool that converts Base64 to the application/pdf MIME type. |
Sample Request¶
curl -X POST .../v1/container-manifest \
-H "Authorization: Bearer <oauth_token>" \
-H "Content-Type: application/json" \
-H "X-PB-TransactionId: abc12345678" \
-d '
{
"carrier": "Newgistics",
"containerType": "Carton",
"parcelTrackingNumbers": [
"9201100000000000000000",
"9202200000000000000000",
"9203300000000000000000",
"9204400000000000000000",
...,
...
],
"documents": [ {
"fileFormat": "PDF",
"size": "DOC_4X4",
"resolution": "DPI_203"
} ],
"parameters": [ {
"name": "CARRIER_FACILITY_ID",
"value": "1585"
},{
"name": "CARRIER_GATEWAY_FACILITY_ID",
"value": "1585"
},{
"name": "CLIENT_CONTAINER_ID",
"value": "AB12345678"
},{
"name": "CLIENT_ID",
"value": "NGST"
},{
"name": "CURRENT_CONTAINER",
"value": "4"
},{
"name": "ESTIMATED_ARRIVAL_DATE",
"value": "2020-09-05"
},{
"name": "PACKAGE_COUNT",
"value": "88"
},{
"name": "PRINT_CUSTOM_MESSAGE_1",
"value": "Bounded Printed Matter, Handle Separately!"
},{
"name": "SHIP_DATE",
"value": "2020-09-03"
},{
"name": "SHIPMENT_REFERENCE_NUMBER",
"value": "CD12345678"
},{
"name": "TOTAL_CONTAINER_COUNT",
"value": "7"
} ]
}'
Sample Response¶
{
"data": {
"pbContainerId": "5e9030d0ca7d01031c6967a0",
"labelData": "^XA^FWR^FO20,20^GB770,1185,5^FS^LRY^FO650 ... "
}
}
Sample Container Label¶
