Overview

The OneRail Delivery API engine represents the fundamentals of sending orders with the platform without the added complexity of the full core API engine. In addition to accepting orders dynamically from your organization’s chosen application, it is also capable of producing webhook requests which can automatically provide alerts for deliveries to connected applications.

Integrating your organization’s operation via API allows for immediate processing and updates without the need for manual intervention/monitoring.

Authentication

Client authentication with the OneRail API Engine can be classified by distinct two methods: user-based and org-based. The process of establishing authentication between your app and the OR API will depend on the desired auth method. The following subsections outline the steps to implement each of the available authentication methods:

User-Based Authentication

In this method, individual user credentials configured for your account are presented to the platform by your client application. Upon successful authentication, your client application would then act on the behalf of the user’s credentials that were used to authenticate. 

To perform authentication with this method, your client app will need to perform a POST request to the “user/authenticate” endpoint. This endpoint requires the desired user’s username and their associated password.

For full details regarding this endpoint, refer to the following Swagger reference:

Org-Based Authentication

Organization-based authentication utilizes a pair of values (App ID and API Key) that are attached to the header of requests intended for the OneRail API Engine. The App ID and API Key are created for each shipper on an individual basis by our product team and then distributed for production use. When using this method, any of your organization’s applications connecting to the API will connect with a set of authentication credentials that represents each individual shipper.

To obtain the App ID and API Key for a shipper, you must first contact the OneRail customer success team. They will produce a response obtained from product resources, containing the App ID and API Key values/credentials generated specifically for your shipper's organization. Each shipper defined for your account will need a set of API credentials that identifies orders associated with a particular shipper. Ensure that requests sent to the Delivery API by your application are utilizing the correct credentials when sending a shipper's order.

These credentials can now be used to authenticate any request intended for your organization’s OneRail account. To implement these credentials, their values will need to be added to the header of any request intended for the OneRail API Engine. The following code blocks shows the headers and their associated values:

X-ONERAIL-APP-ID: App ID provided by your implementation manager
X-ONERAIL-API-KEY: API Key provided by your implementation manager

Deliveries vs Orders

Before planning any implementations of the Delivery API, a determination should be made between whether primarily order functions or delivery functions. A delivery represents a single delivery order on the OneRail platform, while a order represents multiple deliveries on the OneRail platform.

Delivery Functions

Following authentication, your application can now send functional requests to the OneRail API Engine on behalf of your organization or user (depending on the method of authentication being utilized). For this guide, we will be implementing the capabilities of the Delivery API.

We will now show how to use some of the most essential requests/endpoints, but the Delivery API can perform a variety of tasks related to interacting with delivery orders.

Creating a Delivery

The /delivery/create endpoint’s purpose is to make new deliveries for your organization’s OneRail account. This endpoint accepts POST requests from clients with a request body (JSON) containing the important metadata for the delivery.

For further details regarding this endpoint, refer to the following Swagger reference:

Creating an Order

The /order/create endpoint’s purpose is to make new orders for your organization’s OneRail account.  Orders differ from deliveries where a single order can contain multiple deliveries. This endpoint accepts POST requests from clients with a request body (JSON) containing the details for each individual delivery, as well as information describing the larger order as a whole.

For full details on this endpoint, refer to the following Swagger reference:

Order Partial Update

The function of this endpoint provides a partial update to the details of a specifically requested order. This functionality can also add or replace items and containers to an existing order (if that update is needed).

This endpoint will append items and containers to an existing order when requests are made with the PATCH request method. This endpoint will replace items and containers for an existing order when requests are made with the PUT request method.

For further details regarding this endpoint, refer to the following Swagger reference:

Add a Delivery to an Existing Order

The functionality of this endpoint creates a new individual delivery (or multiple deliveries) for an existing order.

For further details regarding this endpoint, refer to the following Swagger reference:

Canceling a Delivery Order

A delivery orders sent to ORD can be canceled prior to an order being dispatched.  This can be designated by your organization or the organization sending the order (depending on your configuration).

Note: This function is only applicable for shipper cancellations.

To cancel an order, a POST request can be sent to the “/delivery/{id}/cancel” endpoint. The “{id}” within the URL should be replaced with the ID of the delivery that is being canceled.

For full details on this endpoint, refer to the following Swagger reference:

Get Delivery Rates

Prior to sending a request to create a particular delivery, the rate for sending this delivery at the current time can be gathered without having to send/process the delivery in question. The "Get Rates" endpoint will receive rates for all qualified carriers applicable to the delivery.

To get rates for a particular delivery, a GET request is sent to the /delivery/get-rates endpoint that  contains important metadata for the delivery. The response from endpoint will describe the price to send the delivery.

For full details regarding this endpoint, refer to the following Swagger reference: