Introduction
This REST service allows our partners to report back to IBC the status updates and also to
add comments about the shipments tendered by IBC.
There are three types of updates that can be amended to existing IBC shipments:
- Proof of delivery (POD) - issued by the carrier when the package has arrived at the final destination. IBC collects the name, the date and time of the delivery.
- Dispositions - used to report issues or events about the delivery of the package. IBC collects the 2 digit disposition code, the event date and time. Please save the current disposition codes list from here: IBC Disposition code list.
- Shipment comments - used to report general information regarding the package delivery. IBC collects the comment text and the date for the comment.
The complete format documentation for the report entries is documented in this link: http://www.pactrak.com/pods-to-pactrak.html.
How to submit your data
Your client must use POST HTTP method to successfully submit your JSON structure.
The service URL is:
https://api.pactrak.com/shipment-update/record
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/shipment-update/record?token=NmIzY2Y1OWV8SmFoMnclWl5Od1p2S1NzVw==
Shipment Details
The service URL to receive shipment level details is:
https://api.pactrak.com/shipment-update/record/TRACK_NUMBER?token=NmIzY2Y1OW......
Replace TRACK_NUMBER with your specific shipment. You must also pass an authority token in order to receive the
detail information. Use this call to retrieve the specific shipment's serial key.
The above request will yield the following JSON response:
HTTP 200 OK
[ /** JSON array containing all records for the tracking number.
If multiple objects are available, you must select the key of the
specific shipment profile you wish to update.*/
{
"key": 20406080,
"name": "Consignee Name",
"company": "Consignee Company",
"address": "123 Consignee address",
"city": "MIAMI",
"state": "FL",
"zip": "33035",
"phone": "1-999-999-9999",
"description": "description!",
"destination": "USA",
"account": "0330",
"route": "MIA-FDX"
}
]
If no records are found a JSON response is returned with a message
HTTP 404 Not Found
{
"code": 404,
"message": "No tracking information found."
}
Shipment Updates
To test the content of your submission please use the following service URL:
https://api.pactrak.com/shipment-update/record?_test
Test entries do not require tokens.
The REST service currently accepts the following JSON structure to correctly report your information.
/** Main submission object is called status, it contains a tracking report array object. */
status={
/** Report array object - should contain 1 or many Tracking update objects */
"report" : [
/** Tracking update object - Should contain 1 tracking or vend_ref property and 1 pod, disposition or comments object. */
{
/** @type int - serial id. This number is required for each piece, you must retrieve it by querying the shipment details service.*/
"serial" : "20406080",
/** @type String - tracking number associated with shipment, up to 11 numbers. */
"tracking" : "4656423423",
/** @type String - vendor_ref property: your shipment identifier, up to 22 chars. */
"vendor_ref" : "1z32356423423442",
/** @type Object -
pod object - contains a date, time and name properties. */
"pod" : {
"date": "11/27/13",
"name":"Mike Martinez",
"time":"13:21"
},
/** @type Object -
disposition object - contains a date, time and disposition code properties. */
"disposition" : {
"date":"11/23/13",
"time":"10:15",
"code":"CO"
},
/** @type Object -
comments object - contains a text and date properties. */
"comments" : {
"date":"11/25/13",
"text":"Need a better address."
},
/** @type String - user_name - 8 character user identifier, if you are using Pactrak this should be associated with that account. */
"user_name" : "testuser",
/** OPTIONAL properties (including the comma that precedes this comment) */
/** @type String - date_format - You can use your own date format and specify the contents with this property.
Use the following key for the patterns allowed:
MM (month), dd (day) and yyyy (year). ie MM-dd-yyyy for 12-01-1975
*/
"date_format" : "MM/dd/yy",
/** @type String - time_format - Specify the time format of used within the report.
Use the following key for the patterns allowed:
H-Hour in day (0-23), k-Hour in day (1-24), K-Hour in am/pm (0-11)
h-Hour in am/pm (1-12), m-Minute in hour, a-Am/pm marker
Here are some sample entries:
"h:m a" for "4:22 PM" - "H:m" for "16:35"
*/
"time_format" : "H:m"
}
] /** end report array **/
}
The report array should contain at least 1 tracking update object, separate multiple entries with a comma (,).
Each tracking update object corresponds to a single shipment and should contain a tracking or vendor_ref property, a user_name entry and could contain one (of each if necessary) pod, disposition or comments object.
status={ "report" : [ { t* }, { t* }, { t* } ] }
t* = { "tracking" : "", "vendor_ref" : "", "user_name" : "", "pod" : { *** }, "disposition" : { *** } , "comments" : { *** } }
The format of the JSON response
After making a successful submission you should expect a return of one of the following JSON structures:
Successful JSON response
{
/**
* The HTTP response code
* @type Integer.
*/
"code": 200,
/**
* Response message relevant to the action requested.
* @type String.
*/
"message":"",
/**
* A link to the resource.
* @type String.
*/
"href":"https://api.pactrak.com/shipment-update/record",
/**
* The content type supported
* @type String.
*/
"content Type":"application/json;charset=UTF-8"
}
Failures
{
/**
* The HTTP response code
* @type Integer.
*/
"code":400,
/**
* Response message relevant to the action requested.
* @type String.
*/
"message":"The following email may not be valid: @gmail.com",
/**
* Response message intended for the development team.
* @type String.
*/
"developerMessage":"",
/**
* A link to the resource
* @type String.
*/
"href":"https://api.pactrak.com/shipment-update/record",
/**
* The content type supported
* @type String.
*/
"contentType":"application/json;charset=UTF-8"
}
How to test
The easiest way to test your POST request is to use cURL from the system's command line.
We recommend saving your JSON structure into a text file ( input-file.txt ) and then execute this command:
curl -siL -X POST -k --data "@input-file.txt" https://api.pactrak.com/shipment-update/record?_test
This is a sample JSON structure ready for testing.
status={
"report":[ { "serial":"20406080", "tracking":"465446665", "user_name":"usera", "disposition":{"date":"20130712","time":"4:22 PM","code":"OF"}, "time_format":"h:m a" } ]
}
