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:

1. Track Shipment
2. Rate Shipment
3. Tender Shipment
4. 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):

1. API
2. Batch/Flat File
3. Web
4. 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.

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.