Last Mile Carrier Integration Guide
Purpose
The purpose of this document is to describe how project44 supports integrations with Last Mile common carriers. It provides implementation details for carriers who have been asked by their customers to work with project44's Last Mile platform and technology.
Audience
The audience of this document is the carrier’s Information Technology (IT) team. The carrier’s IT team is responsible for partnering with project44 to build the appropriate integration between the carrier’s systems and project44's systems.
Integration Points
project44 supports four integration points with Last Mile carriers:
- Track Shipment
- Rate Shipment
- Tender Shipment
- Schedule Appointment
Integration Methods
project44 tries to be flexible in its approach to integrating with carriers and tries to minimize the work required by carriers. project44 has invested heavily in its integration framework and tools, and it has a good track record of leveraging the existing infrastructure of carriers, thereby limiting the scope of carrier IT investment to support project44.
There are four methods of integrations (in order of preference):
- API
- Batch/Flat File
- Web
- EDI
Application Programming Interface (API)
API integration is project44's first choice for carrier integration. The underlying technology of API integrations is web technology (HTTP, XML and JSON) which is why “Web API” and “API” are often used interchangeably.
Modern APIs take one of two forms: a “pull” API or a “push” API. In a pull API scenario, the carrier creates either a SOAP or REST/JSON API endpoint and publishes it to third parties, like project44. In a push API scenario (which is usually implemented with HTTP webhooks), a third party like project44 exposes an endpoint, and the carrier pushes data to it via an HTTP request.
The choice of pull vs. push is dependent on the use case; certain use cases are better supported by one than the other.
Batch/Flat File
Batch/Flat File integration is another preferred method of carrier integration. This is a document-style integration where the file format is either XML or CSV. These documents are sent to project44 on a periodic basis (hourly, daily or somewhere in between) via FTP using either the SFTP or FTPS protocols.
Web
Web integration is a method where project44 programmatically drives the web site of carrier using a browser, leveraging a technology like cURL or Phantom.JS. project44 supports this method of integration, but does not prefer it.
Electronic Document Interchange (EDI)
EDI is an integration path of least preference for project44. EDI integrations tend to be slow to implement, error prone and expensive. project44 does not recommend this approach.
Supported Integrations
Track
Tracking integration is important for project44's Consumer Visibility product. There are two Consumer Visibility product use cases that are enabled by tracking integration: Discover In-Transit Shipments and Get Shipment Tracking Information. To support Consumer Visibility, a carrier must implement an integration for in-transit shipment discovery and an integration for getting shipment tracking information.
Discover In-Transit Shipments
One of the primary value propositions of project44's Consumer Visibility is that retailers can see all of their shipments that are in-transit across their carrier network in a single application. In order to provide this functionality, the Consumer Visibility product must have a mechanism to discover all shipments that are in-transit for a retailer at a carrier.
Get Shipment Tracking Information
Another primary value proposition of project44 Consumer Visibility is that retailers can proactively take action on shipments. In order to provide this functionality, the Consumer Visibility product must have a mechanism to get shipment tracking information on
Recommended Implementation: Shipment Discovery
The recommended implementation to discover in-transit shipments is a batch file in CSV format. The “primary key” of each record in the CSV file is the unique identifier for the shipment. Carriers have varying names for this number; the most common are tracking, PRO or HAWB number.
Scope
Carriers implement this file for all active shipments for a particular customer.
Filename
The file is named with the date and time of its creation and the CSV file extension. The format of the filename is customername_YYYYMMDDHHMMSS.csv. An example file name is BedBathBeyond_2017040109301.csv.
File Contents
The CSV file has many fields. Any fields that are not available for a shipment can be left blank.
Field Name |
Field Description |
Field Sample Value |
Tracking Number |
Unique Carrier Shipment Identifier -- Tracking, PRO or HAWB. |
A123456789 |
Shipper Name |
Name of shipper |
Ship's A Lot |
Shipper Zip Code |
Zip code of shipper |
07083 |
Shipper Reference Number |
Identifier to Sales Order or Purchase Order in shipper’s system |
987654321 |
Consignee Name |
Name of consignee |
John Doe |
Consignee Zip |
Zip code of consignee |
78701 |
Consignee Address |
Address of consignee, including zip code |
812 San Antonio #300 Austin, TX 78701 |
Consignee Phone Number |
Phone number of consignee |
512-555-1212 |
Consignee E-Mail Address |
E-mail address of consignee |
|
Service Level |
Service level of shipment |
White Glove |
Creation Date |
Date shipment was created |
2017-03-27 |
Pick Up Date |
Pick up date of shipment |
2017-03-28 |
Estimated Delivery Date |
Estimated delivery date of shipment |
2017-04-01 |
Pieces |
Number of pieces for a shipment |
2 |
Charge Weight |
Weight of shipment upon tender |
10 |
Total Charges |
Charge for shipment |
400.00 |
Charges Currency |
Current for charge. ISO 4127 currency codes are supported. |
USD |
Status Code |
Numeric code to indicate shipment status |
013 |
Status Description |
Text description of shipment status |
Out for Delivery |
Exception Code |
Numeric code to indicate shipment is in an exception state |
12A |
Exception Description |
Text description of exception if shipment is an exception state. |
Shipment has been sent to OS&D for processing. |
Appointment Required |
Whether an appointment is required for this shipment |
TRUE |
Appointment Scheduled |
Whether an appointment is scheduled for this shipment |
TRUE |
Appointment Date |
Date for a scheduled appointment |
2017-04-01 |
Update Frequency
project44 prefers that carriers update this file every 4 hours. project44 can accept even more frequent updates such as hourly if the carrier can support it. The minimum standard for updates is 24 hours.
Transfer Method
project44 hosts a secure FTP server to receive files from carriers. The FTP server supports FTPS and SFTP protocols.
Access Credentials
project44 sets up a specific account on its FTP server for each carrier. The userid for the account is the carrier name. Carriers should contact project44 Support to create an account.
Transfer Location
project44 creates a specific directory to receive files for each retailer-carrier relationship. The path specification for the directory is /upload//.
Recommended Implementation: Get Shipment Tracking Information
The recommended carrier implementation to get shipment tracking information is an HTTP REST/JSON API. The API should accept a tracking, PRO or HAWB number, and returns shipment status, including detailed shipment milestones.
Request
http://www.carrier.com/webservices/tracking?tracking_id=A123456789
Response
{
"success": true,
"result": {
"status": "delivered",
"status_desc": "Delivered",
"carrier_status": "DL",
"carrier_status_desc": "Delivered - Signature Service not requested. (014)",
"carrier_pro_number": "785960396460",
"city": "Somerset",
"state_or_province_code": "NJ",
"status_local_date_time": "2017-03-22T12:27:31",
"shipment_info": {
"delivery_date": "2017-03-22",
"origin_postal_code": "08832",
"destination_postal_code": "08873",
"weight": {
"value": 3.5,
"units": "LB"
}
},
"history_items": [
{
"status": "delivered",
"status_desc": "Delivered",
"carrier_status": "DL",
"carrier_status_desc": "Delivered - Signature Service not requested. (014)",
"city": "Somerset",
"state_or_province_code": "NJ",
"status_local_date_time": "2017-03-22T12:27:31",
"status_is_exception": false,
},
{
"status": "out_for_delivery",
"status_desc": "On FedEx vehicle for delivery",
"carrier_status": "OD",
"carrier_status_desc": "On FedEx vehicle for delivery",
"city": "Carteret",
"state_or_province_code": "NJ",
"status_local_date_time": "2017-03-22T07:03:00",
"status_is_exception": false,
},
{
"status": "in_transit",
"status_desc": "At local FedEx facility",
"carrier_status": "AR",
"carrier_status_desc": "At local FedEx facility",
"city": "Carteret",
"state_or_province_code": "NJ",
"status_local_date_time": "2017-03-22T05:02:00",
"status_is_exception": false,
},
{
"status": "in_transit",
"status_desc": "Departed FedEx location",
"carrier_status": "DP",
"carrier_status_desc": "Departed FedEx location",
"city": "Keasbey",
"state_or_province_code": "NJ",
"status_local_date_time": "2017-03-21T23:42:01",
"status_is_exception": false,
},
{
"status": "in_transit",
"status_desc": "Arrived at FedEx location",
"carrier_status": "AR",
"carrier_status_desc": "Arrived at FedEx location",
"city": "Keasbey",
"state_or_province_code": "NJ",
"status_local_date_time": "2017-03-21T18:39:00",
"status_is_exception": false,
},
{
"status": "picked_up",
"status_desc": "Picked up",
"carrier_status": "PU",
"carrier_status_desc": "Picked up",
"city": "Keasbey",
"state_or_province_code": "NJ",
"status_local_date_time": "2017-03-21T15:41:00",
"status_is_exception": false,
},
{
"status": "scheduled",
"status_desc": "In FedEx possession",
"carrier_status": "IP",
"carrier_status_desc": "In FedEx possession - Tendered at FedEx location (084)",
"city": "East Brunswick",
"state_or_province_code": "NJ",
"status_local_date_time": "2017-03-20T19:00:00",
"status_is_exception": false,
},
{
"status": "scheduled",
"status_desc": "Shipment information sent to FedEx",
"carrier_status": "OC",
"carrier_status_desc": "Shipment information sent to FedEx",
"status_local_date_time": "2017-03-20T11:31:00",
"status_is_exception": false,
}
],
"delivery_info": {
"first_attempt": {
"source_event": "delivered",
"precision": "date",
"local_date_time": "2017-03-22T12:27:31"
}
},
}
}
Integration Support
project44 supports Last Mile carriers in the development of integrations including specification development and review, design and code review, and integration testing.