IBC Shipping Label - REST Documentation

Introduction

This REST service allows your system to create a Fedex Express, SmartPost , Ground labels or UPS Ground Labels using standalone, web or script based program.

Your client must use POST, DELETE and PUT HTTP methods to successfully submit your label create, label delete and manifest close requests.

The service URL is:
https://api.pactrak.com/ibclabel/service

Attention: This is a secure service, you need to obtain a security token first and append your token entry as a parameter to the URL above.
This is a sample URL with an authority token:
https://api.pactrak.com/ibclabel/service/...../?token=NmIzY2Y1OWV8SmFoMnclWl5Od1p2S1NzVw==

Please visit the Authority Web service for information on how to receive an authority token.
https://api.pactrak.com/authority/documentation.html

Default values

Your service requests will use some or all of the following values:

STATION_CODE: select between MIA, NYC, LAX, ORD, JET or TST ( Use TST for your test submissions ).
SERVICE_CODE: For Fedex labels choose S for SmartPost, R for SmartPost returns service, G for Ground, GH for Ground Home Delivery, 2D for 2 Day Service, E for Standard Express or P for Priority Express.
For UPS labels use UPSG for Ground UPSN for NextDay, UPSNS NextDay Saver UPS2D 2Day Service, UPS3D 3Day Service, UPSM UPSSurePost < 1 lbs and UPSM1 UPSSurePost > 1 lbs. You can pass ?residential as a parameter to your URL to mark the delivery as residential.
UPS Label types (image_type) are ZPL, GIF, EPL, SPL, PNG, and GIF.
For DHL Labels use these service codes: DHM, DHE, DHG or DHP.
ManifestID: Your shipments should be grouped based on this ID. You are free to select the format. It is restricted to 8 chars max. For example: 1S160511 or 1G160511. Separating ground, express and smart post requests. *For UPSG you can use 'UPS' as an ID.
ServiceTrackNumber: This number is received with your label feed and it is your vendor related tracking number.

*Note: SmartPost returns service is not available to all stations.

Label Create Requests

To create a new label you will need:

Submit a HTTP POST request to the server.
The URL should have the following format:
https://api.pactrak.com/ibclabel/service/STATION_CODE/SERVICE_CODE/ManifestID
The request data feed JSON format.

/** Main Submission object called feed */
feed = {

/** The first object to define is the customer/recipient information. */
"customer": {

"name": "", /* required */
"company": "",
"phone": "", /* required */
"address1": "", /* required */
"address2": "",
"city": "", /* required */
"state": "", /* required */
"postalCode": "", /* required */
"countryCode": "" /* required - should be 'US' */

},
"request_id": "", /** Optional- On SmartPost returns service request you can place your RMA number here */
"item": { /** For Fedex or UPS multilot Shipments use: 'items' and pass an array of these types of objects. See sample JSON structures below. */

"weight": "", /* required */
"weight_unit": "", /* required (LB, KG, OZ)*/
"packaging": "", /* required ( BAG, BOX, ENVELOPE, OTHER )*/
"description": "", /* required */
"length": "", /* required if supplying dimensions */
"width": "", /* required if supplying dimensions */
"height": "", /* required if supplying dimensions */
"dim_unit": "", /* required if supplying dimensions (IN, CM)*/
"reference": "", /* optional reference will print as PO # in express and ground labels */
"insuranceAmount": "",
"futureDayShipmentDays": "" /* You can advance the ship date with this value, min 1 max 10 */

}

Fedex Label Return Types

The Fedex default label return type is a 4x6 ZPL label. You can modify the label type by appending the following parameters to your URL:

?image_type=IMAGE_TYPE&stock_type=STOCK_TYPE

The following tables define the accepted IMAGE_TYPE and STOCK_TYPE options.

For Standard Label Printers

image_type	stock_type
ZPLII	STOCK_4X6
EPL2	STOCK_4X6.75_LEADING_DOC_TAB
DPL	STOCK_4X6.75_TRAILING_DOC_TAB
	STOCK_4X8
	STOCK_4X9_LEADING_DOC_TAB
	STOCK_4X9_TRAILING_DOC_TAB

For Laser Printer Labels

image_type	stock_type
PDF	PAPER_4X6
PNG	PAPER_4X8
RTF	PAPER_4X9
TEXT	PAPER_7X4.75
	PAPER_8.5X11_TOP_HALF_LABEL
	PAPER_8.5X11_BOTTOM_HALF_LABEL
	PAPER_LETTER

Label Delete Requests

To delete a label you will need:

Submit a HTTP DELETE request to the server.
The URL should have the following format:
https://api.pactrak.com/ibclabel/service/STATION_CODE/SERVICE_CODE/ServiceTrackNumber

Manifest Closing

To close your labels on the ship date: (NOT NEEDED For UPSG service)

Submit a HTTP PUT request to the server.
This procedure is only needed for Fedex Ground and SmartPost.
The URL should have the following format:
https://api.pactrak.com/ibclabel/service/STATION_CODE/SERVICE_CODE/ManifestID

How to submit your data

You will need to obtain a security token before submitting your test or production requests.

The easiest way to test your POST request is to use cURL from the system's command line. Use the station code TST for TEST entries.

We recommend saving your JSON structure into a text file ( input-file.txt ). To create a label under Manifest 1G161122 you will execute:

curl -siL -X POST --data "@input-file.txt" https://api.pactrak.com/ibclabel/service/TST/G/1G161121?token=...

Sample JSON structures ready for testing.

{ "customer":{ "name":"John Smih", "company":"IBC Inc.", "phone":"305 591 8080", "address1":"8401 NW 17th St", "city":"Miami", "state":"FL", "postalCode":"33126", "countryCode":"US" }, "item":{ "weight":"1", "weight_unit":"LB", "packaging":"BOX", "description":"magazines" } }

The following code is a sample input request for a Fedex / UPS Multilot shipment, except Fedex Smartpost requests.

{ "customer":{ "name":"John Smith", "company":"IBC Inc.", "phone":"305 591 8080", "address1":"8401 NW 17th St", "city":"Miami", "state":"FL", "postalCode":"33126", "countryCode":"US" }, "items":[{ "weight":"1", "weight_unit":"LB", "packaging":"BOX", "description":"magazines" }, { "weight":"2", "weight_unit":"LB", "packaging":"BOX", "description":"magazines" }] }

Here is a sample curl delete request for Smartpost Fedex track number 76564231111: *To delete 2D shipments use code 'E'.

curl -siL -X DELETE https://api.pactrak.com/ibclabel/service/TST/S/76564231111?token=...

Here is a sample curl request to close ground manifest 1S161122:

curl -siL -X PUT https://api.pactrak.com/ibclabel/service/TST/G/1S161122?token=...

After making a successful submission you should expect a return of one of the following JSON structures:

Response JSON structure

{

/**
* The HTTP response code
* @type Integer.
*/
"code": , /** Successful response: 200, Error response: 40x */

/**
* Response message relevant to the action requested.
* @type String.
*/
"message":"",

/**
* Detailed Response message relevant to the action requested.
* @type String.
*/
"developerMessage":"",

/**
* A link to the resource.
* @type String.
*/
"href":"https://api.pactrak.com/ibclabel/service/",

/**
* The direct response from the label provider with the details of your label transaction. Note: may not appear on error responses. * @type JSON Object.
*/
"service_answer": { /** Note: not all items will be available on all responses. Most are for informational purposes only. On multi-lot requests this will be an Array Object.*/

"message": "", /** */
"label_feed": "", /** The data feed that is used to create your physical label. The data is base64 encoded.*/
"labelResponse": "", /** true when label data feed is available in the label_feed object */
"label_type": "ZPLII", /** Defaults to ZPLII */
"trackNumbers": [ "" ], /** This is an array object. The first item in the array is your Fedex track number. */
"service": "", /** FXSP or FDXG */
"notes": "",
"notices": "",
"provider": "",
"jobId": "", /** A unique Job Id created by the service provider. */
"barcode": "", /** The data that created the barcode printed on the label.. */
"barcode_type": "", /** USPS for SmartPost or FEDEX_1D for Gound */
"report": ""

},

/**
* The direct responses from the label provider with the details of your label transactions, when requesting multi-lot shipments. Note: may not appear on error responses. * @type JSON Array.
*/
"service_answers": [ {"service_answer"}....
]

}

On error responses the Developer message object will contain a validity report with details of the issues found with the input provided. It is formatted with end of line chars "\n" so that it will be readable in your browser's web console.

UPS Service Codes

Use these codes for UPS Labels

UPSG: UPS Ground Service

UPSN: UPS NextDay Service

UPSNS: UPS NextDay Service Saver

UPS2D: UPS 2 Day Service

UPS3D: UPS 3 Day Service

UPSM: UPS Sure Post Items less than 1 lbs, report weight in "OZ" ounces

UPSM1: UPS Sure Post Items greater than 1 lbs

For residential delivery add ?residential as a parameter to your request URL.

The service supports returning ZPL, GIF, SPL, EPL or PNG image of the label. Use the stock_type parameter in your URL request to change the type. If you don't use the parameter the ZPL code is returned.

DHL Service Codes

Use these codes for DHL Labels

DHM: SmartMail Parcel Expedited Max

DHE: SmartMail Parcel Expedited

DHG: SmartMail Parcel Ground

DHP: SmartMail Parcel Plus Ground

DHPE: DHL Plus Expedited

The service supports returning ZPL or a PNG image of the label. Use the stock_type parameter with the value: image for PNG, or zpl for ZPL response. If you don't use the parameter the ZPL code is returned.

Developer Resources

Restful services are capable of receiving requests form web based or standalone applications. We have tested our services to comply with REST standards, returning appropriate HTTP codes to help developers using commonly used frameworks as JQuery or Prototype.

Additionally, there are many examples from many different programming languages such as C#, Java, PHP and C++.

If you desire to test or need Java sample code, the following project is an example of how to call an HTTP Rest service using HTTP Post protocol, IBCPost.

Useful Links

ZPL printing
Zebra Windows help

Linux printing

Base64
Encode / Decode and samples

IBC Shipping Label REST Service