IBC. Inc.

IBC Virtual Shipping - REST Service

Introduction

This REST service allows your system to create shipping labels using standalone, web or script based program.

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

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

Attention: This is a secure service, you need to obtain a security token first and use the "Authorization" header with the "Bearer" scheme on every request, for example:
    curl https://api.pactrak.com/ibclabel/virtual/..... -H "Content-Type: application/json" -H "Authorization: Bearer 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 URLs will need to use these variable parameters:

  1. STATION_CODE: select between MIA, NYC, LAX, DFW or ORD ( you can also use TST for tests ).
  2. SERVICE_CODE:
    • - For Pitney Bowes Labels use PBW for standard service labels.
    • - For Fedex labels use 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.
  3. ServiceTrackNumber: This number is received with your label feed and it is your vendor related tracking number.

URL parameters

Your service request URL can contain these optional parameters:

Label Create Requests

To create a new label you will need:

  • Submit a HTTP POST request to the server.
  • Set HTTP Header: "Content-Type: application/json"
  • Set HTTP Header: "Authorization: Bearer TOKEN_DATA......"
  • The URL should have the following format:
     https://api.pactrak.com/ibclabel/virtual/STATION_CODE/SERVICE_CODE
  • The request data feed JSON format.
  • 			
    { 	/** This object describes the recipient information. */
    	"customer": {
    		"name": "", /* required */
    		"company": "",
    		"phone": "", /* required */
    		"address1": "", /* required */
    		"address2": "",
    		"city": "", /* required */
    		"state": "", /* required */
    		"postalCode": "", /* required */
    		"countryCode": "" /* required - for PBW should be 'US' */
    	},
    	/** This object describes the shipper information */
    	"shipper":{
    		"ibc_reference": "####",  /* Use the shipper account number IBC assigned */
    		"name":"",   /* required */
    		"company":"",
    		"phone":"",  /* required */
    		"address1":"",  /* required */
    		"address2": "",
    		"city":"",  /* required */
    		"state":"", /* required */
    		"postalCode":"",   /* required */
    		"countryCode":""  /* required  */
      	},
    	/* This object describes the physial item being shipped */
    	"item": {
    		"weight": "",  /* required */
    		"weight_unit": "", /* required  (OZ, GM, LB) ounces, grams or pounds  */
    		"value": "",  /* required */
    		"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)*/
                                          
    	},
    	"request_id": "", /* optional */
    	"reference": "",  /* optional - any reference id for your transaction */
    	"profile_key": ##,  /* required (numeric) when _gw is supplied, IBC will provide you with this value */
    	"route": "" /* required when _gw is supplied, IBC will provide you with this value */
    }
    

Fedex Service Codes

Use these codes for Fedex Labels
  • S: SmartPost - requires close manifest
  • R: SmartPostReturn
  • G: Ground - requires close manifest
  • GH: Ground Home Delivery - requires close manifest
  • 2D: Fedex 2Day service
  • E: Fedex Express label
  • P: Fedex Priority label

See shipment label options for optional label configurations, default is ZPLII 4x6 Stock label

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.

Optional Label type and Size Options

The requests allow you to modify the return typle. You can modify the label type by appending the following parameters to your URL:

 ?label_type=LABEL_TYPE&label_size=LABEL_SIZE

The following table details the accepted LABEL_TYPE and LABEL_SIZE options for PBW requests:

Pitney Bowes Options
label_typelabel_size
ZPL24X6
PDF4X5
PNG4X4

defaults are ZPL2 4x6

Use only OZ or GM as weight_unit

Fedex Options
For Standard Label Printers
label_typelabel_size
ZPLIISTOCK_4X6
EPL2STOCK_4X6.75_LEADING_DOC_TAB
DPLSTOCK_4X6.75_TRAILING_DOC_TAB
 STOCK_4X8
 STOCK_4X9_LEADING_DOC_TAB
 STOCK_4X9_TRAILING_DOC_TAB
For Laser Printer Labels
label_typelabel_size
PDFPAPER_4X6
PNGPAPER_4X8
RTFPAPER_4X9
TEXTPAPER_7X4.75
 PAPER_8.5X11_TOP_HALF_LABEL
 PAPER_8.5X11_BOTTOM_HALF_LABEL
 PAPER_LETTER

Use only KG, LB as weight_unit

UPS Options
For Standard Label Printers
label_typelabel_size
ZPL4X6
EPL
GIF
SPL
PNG

Use only KG, LB as weight_unit

Label Delete Requests

To delete a label you will need:

  • Submit a HTTP DELETE request to the server.
  • Set HTTP Header: "Content-Type: application/json"
  • Set HTTP Header: "Authorization: Bearer TOKEN_DATA......"
  • The URL should have the following format:

     https://api.pactrak.com/ibclabel/virtual/STATION_CODE/SERVICE_CODE/ServiceTrackNumber 

See service code list, for UPS services just use UPS as the service code

Manifest Closing

To close your labels on the ship date:

  • Submit a HTTP PUT request to the server.
  • Set HTTP Header: "Content-Type: application/json"
  • Set HTTP Header: "Authorization: Bearer TOKEN_DATA......"
  • This procedure is only needed for Fedex Ground and SmartPost.
  • The URL should have the following format:

     https://api.pactrak.com/ibclabel/virtual/STATION_CODE/SERVICE_CODE/ManifestID 

We recommend you setup your day with a manifest id of your choice, produce your labels under that id and then send 1 close request per day for that manifest.

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

curl -siL -X POST -H "Content-Type: application/json" -H "Authorization: Bearer NmIzY2Y1OWV8SmFoMnclWl5Od1p2S1NzVw==" --data "@input-file.txt" https://api.pactrak.com/ibclabel/virtual/TST/PBW

Sample JSON structures ready for testing.

{ "customer":{ "name":"Jon Test", "company":"Test Inc", "phone":"305 591 8080", "address1":"1755 West Plantation Road", "city":"Miami", "state":"FL", "postalCode":"33122", "countryCode":"US" }, "shipper":{ "ibc_reference": "8040", "name":"Mike Bello", "company":"IBC", "phone":"305 591 8080", "address1":"8401 NW 17th St", "city":"Miami", "state":"FL", "postalCode":"33191", "countryCode":"US" }, "item":{ "weight":".35", "weight_unit":"OZ", "packaging":"BOX", "description":"magazines", "length": "10", "width": "20", "height": "10", "value": "1", "dim_unit": "IN" }, "request_id": "12222", "reference": "165432423", "profile_key": 2, "route": "PBW" }

How to cancel labels

For PBW labels use the secondary track number NGST.... to perform delete requests, not the primary track number. Here is a sample curl delete request for track number NGST7656423111 and service PBW:

curl -siL -X DELETE -H "Authorization: Bearer NmIzY2Y1OWV8SmFoMnclWl5Od1p2S1NzVw==" https://api.pactrak.com/ibclabel/vitual/MIA/PBW/NGST7656423111

Response JSON structure

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

		
{  /**
   * 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/virtual/", /** * 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. */ "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": "ZPL2", /** Defaults to ZPL2 */ "trackNumbers": [ "" ], /** This is an array object. The first item in the array is your main track number. PBW services returns also a secondary track number for references. */ "service": "", /** Service requested */ "notes": "", "notices": "", "provider": "", "jobId": "", /** A unique Job Id created by the service provider. */ "barcode": "", /** The data that created the barcode printed on the label.. */ }, "trackNumber": "" /** This is the internal number IBC will use for your shipment */ }

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.

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