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

1. The operation returns a Pitney Bowes container ID and the container label.

2. 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.

3. 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 the parameters array, the shipper can make the changes and reissue the request with a new X-PB-TransactionId value to get a container label with the updated information.

4. 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: Newgistics (PB Standard)
containerType	String	The type of container used to transport the parcels. Possible values: Carton Pallet Gaylord LicensePlate
parcelTrackingNumbers	Array[String]	Required. The parcels included in the container, identified by their tracking numbers. The tracking numbers must be for the carrier listed in the carrier field.
documents	Array[Object]	Required. Defines the container label.
fileFormat	String	The file format for the printable label. Possible values: PDF: Returns the label as a Base64-encoded PDF that must be converted to the application/pdf MIME type. To convert, use a tool that converts Base64 to the application/pdf MIME type. ZPL: Returns the label as raw ZPL.
size	String	The label size. Possible values: DOC_4X4 DOC_6X4 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: DPI_203 (Default) DPI_300
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_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.
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.
CLIENT_ID	Required. The carrier-specific client or merchant ID. If testing in the Sandbox environment, set this to NGST.
SHIP_DATE	Required. The date the container will be shipped, specified in the following format: YYYY-MM-DD
ESTIMATED_ARRIVAL_DATE	The estimated date the container will arrive, specified in the following format: YYYY-MM-DD
CLIENT_CONTAINER_ID	The client’s container ID or container number.
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
TOTAL_CONTAINER_COUNT	The total number of containers in the shipment. If you use this parameter, you should also use the CURRENT_CONTAINER parameter.
SHIPMENT_REFERENCE_NUMBER	The Bill of Lading or other shipment reference number associated with the container.
PRINT_CUSTOM_MESSAGE_1	The handling instructions. This will appear on the label under “INSTRUCTIONS.”

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_GATEWAY_FACILITY_ID",
        "value": "1585"
    },{
        "name": "CARRIER_FACILITY_ID",
        "value": "1585"
    },{
        "name": "CLIENT_ID",
        "value": "NGST"
    },{
        "name": "SHIP_DATE",
        "value": "2020-09-03"
    },{
         "name": "ESTIMATED_ARRIVAL_DATE",
         "value": "2020-09-05"
    },{
        "name": "CLIENT_CONTAINER_ID",
        "value": "AB12345678"
    },{
        "name": "CURRENT_CONTAINER",
        "value": "4"
    },{
        "name": "TOTAL_CONTAINER_COUNT",
        "value": "7"
    },{
        "name": "SHIPMENT_REFERENCE_NUMBER",
        "value": "CD12345678"
    },{
        "name": "PRINT_CUSTOM_MESSAGE_1",
        "value": "Bounded Printed Matter, Handle Separately!"
    } ]
}'

Sample Response

{
    "data": {
        "pbContainerId": "5e9030d0ca7d01031c6967a0",
        "labelData": "^XA^FWR^FO20,20^GB770,1185,5^FS^LRY^FO650 ... "
    }
}

Sample Container Label

Error Codes

For a list of all PB Shipping APIs error codes, please see Error Codes.

 
 
 
 

• next
• previous |

© Copyright 2020, PB.