Convey Carrier Integration Guide
Purpose
The purpose of this document is to describe how Convey supports integrations with common carriers (“carriers”). It provides implementation details for carriers who have been asked by their customers to work with Convey’s 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 Convey to build the appropriate integration between the carrier’s systems and Convey’s systems.
What is Convey?
Convey is a software company headquartered in Austin, TX that was founded in 2014. Convey sells a SAAS-based platform that helps retailers improve the final mile delivery experience to the end customer.
Convey has two products: Engage and Initiate.
Convey Engage
Engage provides a real-time visibility into a retailer’s carrier network and gives the retailer tools and technology to enhance the customer delivery experience to the final mile. Engage enables retailers to proactively address customer issues and provides the end customer with a suite of self service tools to better control the delivery experience.
Convey Initiate
Initiate provides retailers with tools and technology to optimize the execution of shipments. Initiate enables retailers and their vendor partners to decision a carrier for a shipment and to tender the shipment to the appropriate carrier. Initiate also enables a retailer to present a series of personalized delivery options to the end customer in the e-commerce shopping cart.
Both products have several integration points with carriers. Convey has integrated to over 70 different carriers over its three-year lifespan.
Integration Points
Convey supports 4 integration points with carriers:
- Track Shipment
- Rate Shipment
- Tender Shipment
- Schedule Appointment
The scope of this document is limited to Track at this time. Future versions of this document will cover Rate, Tender and Schedule Appointment.
Integration Methods
Convey tries to be flexible in its approach to integrating with carriers and tries to minimize the work required by carriers. Convey 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 Convey.
There are four methods of integrations (in order of preference):
- API
- Batch/Flat File
- Web
- EDI
Application Programming Interfaces (“APIs”)
API integration is Convey’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 Convey. In a push API scenario (which is usually implemented with HTTP webhooks), a third party like Convey 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 Convey 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 Convey programmatically drives the web site of carrier using a browser, leveraging a technology like cURL or Phantom.JS. Convey supports this method of integration, but does not prefer it.
Electronic Document Interchange (“EDI”)
EDI is an integration path of last resort from Convey’s perspective. EDI integrations tend to be slow to implement, error prone and expensive. Convey does not recommend this approach.
Supported Integrations
Track
Tracking integration is important for Convey’s Engage product. There are two Engage product use cases that are enabled by tracking integration: Discover In-Transit Shipments and Get Shipment Tracking Information. To support Engage, it is required that a carrier 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 Convey Engage 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 Engage 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 Convey Engage is that retailers can proactively take action on shipments. In order to provide this functionality, the Engage 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 |
Bed Bath & Beyond |
|
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 |
Rob Taylor |
|
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 |
rob@getconvey.com |
|
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
Convey prefers that carriers update this file every 4 hours. Convey 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
Convey hosts a secure FTP server at ftp.getconvey.com to receive files from carriers. The FTP server supports FTPS and SFTP protocols.
Access Credentials
Convey sets up a specific account on its FTP server for each carrier. The userid for the account is the carrier name. Carriers should contact Convey Support at support@getconvey.com to create an account.
Transfer Location
Convey 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
Convey supports carriers in the development of integrations. Over the years, Convey has assisted carriers in many ways: specification development and review, design and code review and integration testing.
Coda
Convey has worked with many carriers to build successful integrations. We look forward to partnering with more carriers to advance the state of the art of the industry. If you have any questions or concerns about integration, you can reach us at carrier-integrations@getconvey.com.