Developer-portal

Introduction

The One Easy Stop API enables the creation and printing of Air Waybills (AWBs) through a RESTful API. This service is exclusively available to customers with valid access credentials. Authorized users can access the API using their assigned username and password.

Basic api

The basic api endpoint is

                    
                    
                      https://staging-api.oneeasystop.com:3000/api

Authorization

The One Easy Stop API enables the creation and printing of Air Waybills (AWBs) through a RESTful API. This service is exclusively available to customers with valid access credentials. Authorized users can access the API using their assigned username and password.

How to implement:

Make a call to the OAuth endpoint with your client ID and client secret. The OAuth server will respond with your bearer token [access_token] and you will then input this into the Authorization HTTP header value of Bearer of your following API calls to Ship API, Track API, etc.

Note:

The client ID can only represent the linked UPS ID and associated UPS shipper accounts when transacting via API. If you are needing to represent many users, please review the Authcode grant type.

Authorization endpoint

 
          
          https://staging-api.oneeasystop.com:3000/api/login

Headers

Header Name	Value	Description
Content-Type	application/json	Specifies the format of the request body.
Accept	application/json	Specifies the format of the response body.

Body

Body Name	Type	Description
user:document	String	User document value
user:password	String	User password

Example of Body

 
          
          {
            "user": {
              "document": "abcd",
              "Password": "password"
            }
          }

Response

Key	Type	Description
data:token	String	The value contained in the key “token” must be used in all requests made during its validity. This token must be inserted in the Request Header, as part of the value of the Authorization key.

Example of return of “Authorization (Login)” method :

 
          
          {

            "data": {
              "token": "eyJhbGciOiJIUzI1NiJ9.eyJpZCI6MjcxLCJyb2xlIjozLCJleHAiOjE3MzI3MDQ0MjZ9.yj6qlx1rSw7YKDokt1yGHKXh5ZAZC8m2i6BbORNJbqM"
            }
          
          }

Method: POST

                        
                        
                          {
                            "user": {
                              "document": "abcd",
                              "Password": "password"
                            }
                          }

                        
                        
                        {

                          "data": {
                            "token": "eyJhbGciOiJIUzI1NiJ9.eyJpZCI6MjcxLCJyb2xlIjozLCJleHAiOjE3MzI3MDQ0MjZ9.yj6qlx1rSw7YKDokt1yGHKXh5ZAZC8m2i6BbORNJbqM"
                          }
                        
                        }

Quotes

This method returns the rates of the shipment

Quotes API Endpoint

 
          
          https://staging-api.oneeasystop.com:3000/api/shipper/quotation

Headers

Header Name	Value	Description
Content-Type	application/json	Specifies the format of the request body.
Authorization	Bearer <your_token_here >	Bearer token for authentication.

This method returns the rates of the shipment

Request Body

The request body contains the details of the quotation. It must be sent as a JSON object with the following structure:

Root Object:

quotation

Type: Object
Description: Contains the quotation details.

Properties:

Data:

Type: Object
Description: Contains shipment-related details.

Fields

Field Name	Type	Description
fromCountry	String	Name of the origin country
fromCountryCode	String	ISO code of the origin country
fromState	String	Name of the origin state
fromStateCode	String	Code of the origin state
fromCity	String	Name of the origin city
fromCityCode	String	Code of the origin city
from_zip	String	ZIP code of the origin location
toCountry	String	Name of the destination country
toCountryCode	String	ISO code of the destination country
toState	String	Name of the destination state
toStateCode	String	Code of the destination state
toCity	String	Name of the destination city
toCityCode	String	Code of the destination city
to_zip	String	ZIP code of the destination location
magnitude	Integer	Magnitude of the shipment (1 = international, 2 = national)
delivery_fast	Integer	Indicates whether fast delivery is required (0 = No, 1 = Yes)
cheaper	Boolean	Indicates whether the cheapest option is preferred
extra_charges	Integer	Any additional charges for the shipment
extra_description	String	Description of additional charges (if applicable)
date_of_quote	String	ISO 8601 date format for the quotation request
city	Boolean	Indicates whether the city field is used (true/false)

Values:

quotation

Type: Array
Description: Contains the details of individual shipment items.

Field Name	Type	Description
tmpId	Integer	Temporary identifier for the shipment item
long	Integer	Length of the item (in appropriate units)
height	Integer	Height of the item (in appropriate units)
wide	Integer	Width of the item (in appropriate units)
weight	Integer	Weight of the item (in appropriate units)
service	Integer	Service type for the shipment (1 = package, 2 = document)
currency_id	Integer	Currency ID for the value of the shipment
value	Double	Declared value of the shipment item
delivery_payment_type	Integer	Payment type for delivery
volumetric	Double	Volumetric weight of the shipment item

Method: POST

                        
                        
                          {
                            "quotation": {
                              "data": {
                                "fromCountry": "Colombia",
                                "fromCountryCode": "CO",
                                "fromState": "Valle del Cauca",
                                "fromStateCode": "Valle del Cauca",
                                "fromCity": "Ansermanuevo",
                                "fromCityCode": "Ansermanuevo",
                                "toCountry": "United Kingdom",
                                "toState": "England",
                                "toStateCode": "England",
                                "toCity": "London",
                                "toCityCode": "London",
                                "magnitude": 1,
                                "delivery_fast": 0,
                                "cheaper": true,
                                "extra_charges": 0,
                                "extra_charges_currency": 1,
                                "extra_description": "",
                                "to_zip": "SW1A 2DD",
                                "from_zip": "762010",
                                "date_of_quote": "2024-11-29T18:07:23.374Z",
                                "toCountryCode": "GB",
                                "city": true
                              },
                              "values": [
                                {
                                  "tmpId": 1,
                                  "long": 10,
                                  "height": 10,
                                  "wide": 10,
                                  "weight": 10,
                                  "service": 1,
                                  "currency_id": 2,
                                  "value": 1,
                                  "delivery_payment_type": 1,
                                  "volumetric": 0.5
                                }
                              ]
                            }
                          }

                        
                        
                          {
                            "data": [
                              {
                                "id": 23588343,
                                "data": {
                                  "from": "united states",
                                  "to": "colombia",
                                  "magnitude": "International"
                                },
                                "total": 0,
                                "provider": {
                                  "name": "LIBERTY",
                                  "image": "https://oes-prod-gen-documents.s3.amazonaws.com/uploads/b6974030-7ac9-4b4f-bee6-7357042f85aa.jpg"
                                },
                                "quotation_id": 206,
                                "quantity": "10",
                                "freight": 0,
                                "fee": 0,
                                "declared_value": 10,
                                "pickup_time": null,
                                "delivery_time": 5,
                                "agent_freight": null,
                                "agent_fee": null,
                                "agent_value": null,
                                "utility": null,
                                "high": 10,
                                "wide": 10,
                                "long": 10,
                                "extra_charges": 0,
                                "currency": {
                                  "id": 1,
                                  "name": "USD",
                                  "symbol": "USD",
                                  "created_at": "2019-12-03T21:40:27.532-05:00",
                                  "updated_at": "2019-12-03T21:40:27.532-05:00"
                                },
                                "tax": 0,
                                "description": "BY AIR",
                                "type_code": "A"
                              }
                            ]
                          }

Response codes

200 Ok, Details of the generated quotation. (Response structure may vary.)

400 Bad Request: Invalid request body or missing required fields.

401 Unauthorized: Invalid or missing bearer token.

500 Internal Server Error: An issue occurred on the server.

Response Explanation:

Root Object: data

Type: Array
Description: Contains details of the quotation and shipping options.

Response Fields:

Field Name	Type	Description
id	Number	Unique identifier for the quotation entry
data	Object	Shipment-related information
data.from	String	Origin country
data.to	String	Destination country
data.magnitude	String	Type of shipment, e.g., "International" or "Domestic"
total	Number	Total cost of the shipment (including all charges)
provider	Object	Information about the shipping provider
provider.name	String	Name of the shipping provider
provider.image	String	URL of the provider's logo
quotation_id	Number	Quotation identifier
quantity	String	Quantity of items
freight	Number	Freight cost
fee	Number	Additional fees
declared_value	Number	Declared value of the shipment
pickup_time	String	Estimated pickup time (if available)
delivery_time	Number	Estimated delivery time in days
agent_freight	Number	Freight cost provided by the agent (if applicable)
agent_fee	Number	Additional agent fees (if applicable)
agent_value	Number	Declared value from the agent's side
utility	Number	Utility charges (if applicable)
high	Number	Height of the shipment
wide	Number	Width of the shipment
long	Number	Length of the shipment
extra_charges	Number	Any additional charges for the shipment
currency	Object	Information about the currency used for the transaction
tax	Number	Tax amount
description	String	Additional description, e.g., "BY AIR"
type_code	String	Code indicating the shipment type, e.g., "A" for air shipment

Creating Shipment

This method to create the shipment

API Endpoint

 
          
          http://staging-api.oneeasystop.com:3000/api/shipper/generate?locale=en

Headers

Header Name	Value	Description
Content-Type	application/json	Specifies the format of the request body.
Authorization	Bearer <your_token_here >	Bearer token for authentication.

Request Body

The request body contains the order details and related information. It must be sent as a JSON object with the following structure:

Root Object:

order

Type: Object
Description: Contains the order details.

Properties:

Order Fields

Field Name	Type	Description
id	Number	Unique identifier for the quotation id
description	String	Description of the parcel or order
extra_description	String	Additional description of the parcel
extra_charges	Number	Additional charges for the order
extra_charges_currency	Number	Currency ID for the extra charges
option	Number	Selected option ID for the order
objects	Array	List of objects in the order

Objects Array:

Each item in the objects array must have the following fields:

Field Name	Type	Description
quantity	Number	Quantity of the item
weight	Number	Weight of the item
unit_value	Number	Unit value of the item
value	Number	Total value of the item

Sender Details

Field Name	Type	Description
document_type_id	Number	ID representing the type of document
name	String	First name of the sender
lastname	String	Last name of the sender
document	String	Document number of the sender
email	String	Email address of the sender
phone	String	Phone number of the sender
zip	String	ZIP code of the sender's location
address	String	Address of the sender

Receiver Details:

Field Name	Type	Description
document_type_id	Number	ID representing the type of document
name	String	First name of the receiver
lastname	String	Last name of the receiver
document	String	Document number of the receiver
email	String	Email address of the receiver
phone	String	Phone number of the receiver
zip	String	ZIP code of the receiver's location
address	String	Address of the receiver

Method: POST

                        
                        
                          {
                            "order": {
                              "id": 25437,
                              "description": "parcel",
                              "extra_description": "",
                              "extra_charges": 0,
                              "extra_charges_currency": 2,
                              "option": 20111816,
                              "objects": [
                                {
                                  "quantity": 0,
                                  "weight": 0,
                                  "unit_value": 0,
                                  "value": 0
                                }
                              ],
                              "sender": {
                                "document_type_id": 2,
                                "name": "jaime",
                                "lastname": "blum",
                                "document": "12345678",
                                "email": "jaime.blum@24hlogistics.com",
                                "phone": "+57 7 654321098",
                                "zip": "110061",
                                "address": "bogota"
                              },
                              "receiver": {
                                "document_type_id": 9,
                                "name": "sai",
                                "lastname": "kumar",
                                "document": "12345678",
                                "email": "sai.kumar@24hlogistics.com",
                                "phone": "+44 76 5432 1098",
                                "zip": "se17 3pz",
                                "address": "london"
                              },
                              "payment_method": 1
                            }
                          }

                        
                        
                          {
                            "order": {
                              "id": 82,
                              "total": 446.25,
                              "origin_name": "UNITED KINGDOM / England / London",
                              "destination_name": "COLOMBIA / Cundinamarca / BOGOTÁ, D.C.",
                              "magnitude_id": 1,
                              "code": "24112813",
                              "observations": null,
                              "tracking": null,
                              "status": 1,
                              "payment_method": 1,
                              "transaction": null,
                              "provider_guide": null,
                              "transaction_codes": "12345678",
                              "quotation_details": {
                                "id": 599315,
                                "provider_id": 12,
                                "magnitude_id": 1,
                                "service_id": 1,
                                "origin_city_id": 228,
                                "destination_city_id": 228,
                                "destination_country_id": 2,
                                "created_at": "2020-04-30T15:07:05.213-05:00",
                                "updated_at": "2020-04-30T15:07:05.213-05:00",
                                "city_id": null,
                                "to": null,
                                "origin_country_id": 1
                              },
                              "from_external_api": true,
                              "api_tracking": null,
                              "api_reference": "GB1238855409",
                              "provider_label": "https://oes-prod-gen-documents.s3.us-east-2.amazonaws.com/2ynjpUWvbcu36ZDDsoRWzzLZ",
                              "city_id": 1720,
                              "destination_id": 349,
                              "country_from": "United Kingdom",
                              "sender_coordinates": [
                                51.5072178,
                                -0.1275862
                              ],
                              "receiver_coordinates": [
                                4.710988599999999,
                                -74.072092
                              ],
                              "delivery_payment_type": null,
                              "country_to": "Colombia",
                              "currency": 1,
                              "invoice": "https://oes-prod-gen-documents.s3.us-east-2.amazonaws.com/fTEZvnhW8mW7Jaccb6gRdex6",
                              "provider": {
                                "id": 12,
                                "name": "24 H LOGISTICS",
                                "code": "INT005",
                                "image": {
                                  "url": "https://oes-prod-gen-documents.s3.amazonaws.com/uploads/712cce88-9bb5-47c9-9ab9-adfba929cb27.png",
                                  "thumb": {
                                    "url": "https://oes-prod-gen-documents.s3.amazonaws.com/uploads/thumb_712cce88-9bb5-47c9-9ab9-adfba929cb27.png"
                                  }
                                }
                              },
                              "website_sender": {
                                "id": 27,
                                "name": "Dandu",
                                "lastname": "Sai Kumar",
                                "document_type_id": 2,
                                "document": "10",
                                "email": "sai.kumar@tribulustech.com",
                                "address": "bogota",
                                "phone": "+57 7 654321098",
                                "zip": "111061",
                                "created_at": "2024-10-30T08:04:09.645-05:00",
                                "updated_at": "2024-11-27T02:21:17.587-05:00"
                              },
                              "website_receiver": {
                                "id": 18,
                                "name": "OSCAR",
                                "lastname": "AGUIRRE",
                                "document_type_id": 9,
                                "website_sender_id": 27,
                                "document": "7708816342",
                                "email": "sai.kumar@tribulustech.com",
                                "address": "5  DEWEY LANE ",
                                "phone": "+44 7708 816342",
                                "zip": "SW1A 2DD",
                                "created_at": "2024-10-30T08:04:09.666-05:00",
                                "updated_at": "2024-11-05T06:15:24.153-05:00"
                              },
                              "website_packages": [
                                {
                                  "id": 14,
                                  "weight": 10,
                                  "height": 10,
                                  "wide": 10,
                                  "long": 10,
                                  "value": 10,
                                  "description": "parcel",
                                  "status": null,
                                  "currency_id": 1,
                                  "website_order_id": 82,
                                  "created_at": "2024-11-27T08:42:32.089-05:00",
                                  "updated_at": "2024-11-27T08:42:32.089-05:00"
                                }
                              ]
                            }
                          }

Response codes

200 Ok, Details of the generated quotation. (Response structure may vary.)

400 Bad Request: Invalid request body or missing required fields.

401 Unauthorized: Invalid or missing bearer token.

500 Internal Server Error: An issue occurred on the server.

Response Explanation:

Root Object: order

Type: Object
Description: Contains information about the generated order.

Response Fields:

Field Name	Type	Description
id	Number	Unique identifier for the website order
total	Number	Total cost of the order
origin_name	String	Full name of the origin location (country, state, and city)
destination_name	String	Full name of the destination location (country, state, and city)
magnitude_id	Number	Identifier for the magnitude of the order (e.g., international, domestic)
code	String	Unique order code
observations	String	Any special observations for the order (if applicable)
tracking	String	Tracking details for the shipment (if available)
status	Number	Current status of the order
payment_method	Number	Payment method used for the order
transaction	Object	Details of the transaction (if applicable)
provider_guide	String	Provider's guide details (if available)
transaction_codes	String	Unique transaction code for the payment
quotation_details	Object	Details of the quotation linked to the order
from_external_api	Boolean	Indicates whether the order was generated from an external API
api_tracking	String	Tracking details retrieved from the API (if applicable)
api_reference	String	Reference code from the API
provider_label	String	URL for the provider's label (if available)
city_id	Number	Identifier for the city associated with the order
destination_id	Number	Identifier for the destination city
country_from	String	Name of the originating country
sender_coordinates	Array	Geographic coordinates (latitude, longitude) of the sender's location
receiver_coordinates	Array	Geographic coordinates (latitude, longitude) of the receiver's location
delivery_payment_type	String	Type of delivery payment (if applicable)
country_to	String	Name of the destination country
currency	Number	Currency ID for the order
invoice	String	URL for the invoice document

Nested Object: provider

Type: Object
Description: Information about the service provider handling the order.

Field Name	Type	Description
id	Number	Unique identifier for the provider
name	String	Name of the provider
code	String	Unique code associated with the provider
image	Object	Object containing URLs for the provider's logo and its thumbnail

Nested Object: sender

Type: Object
Description: Contains information about the sender.

Field Name	Type	Description
id	Number	Unique identifier for the sender
name	String	First name of the sender
lastname	String	Last name of the sender
document_type_id	Number	Document type ID for the sender
document	String	Document number of the sender
email	String	Email address of the sender
address	String	Address of the sender
phone	String	Phone number of the sender
zip	String	ZIP code of the sender's location
created_at	String	Timestamp when the sender's details were created
updated_at	String	Timestamp when the sender's details were last updated

Nested Object: receiver

Type: Object
Description: Contains information about the receiver.

Field Name	Type	Description
id	Number	Unique identifier for the receiver
name	String	First name of the receiver
lastname	String	Last name of the receiver
document_type_id	Number	Document type ID for the receiver
document	String	Document number of the receiver
email	String	Email address of the receiver
address	String	Address of the receiver
phone	String	Phone number of the receiver
zip	String	ZIP code of the receiver's location
created_at	String	Timestamp when the receiver's details were created
updated_at	String	Timestamp when the receiver's details were last updated

Nested Array: packages

Type: Array
Description: List of packages associated with the order.

Package Fields :

Field Name	Type	Description
id	Number	Unique identifier for the package
weight	Number	Weight of the package
height	Number	Height of the package
wide	Number	Width of the package
long	Number	Length of the package
value	Number	Declared value of the package
description	String	Description of the package
currency_id	Number	Currency ID for the declared value
website_order_id	Number	Associated website order ID
created_at	String	Timestamp when the package details were created
updated_at	String	Timestamp when the package details were last updated

Pickup Shipment

This method to pickup the shipment

API Endpoint

 
          
          http://staging-api.oneeasystop.com:3000/api/pickup-shipment

Headers

Header Name	Value	Description
Content-Type	application/json	Specifies the format of the request body.
Authorization	Bearer <your_token_here >	Bearer token for authentication.

Request Body

The request body contains the order details and related information. It must be sent as a JSON object with the following structure:

Root Object:

order

Type: Object
Description: Contains information about the cancel order.

Field Name	Type	Description
id	Number	Unique identifier for the order
status	String	Status for changing, e.g., "cancel"
description	String	Description of the parcel or order

Method: POST

                        
                        
                          {
                            "order": {
                              "id": 82,
                              "status": "cancel",
                              "description": ""
                            }
                          }

Response codes

200 Ok, pickup request has been successfully processed.

400 Bad Request: Invalid request body or missing required fields.

401 Unauthorized: Invalid or missing bearer token.

500 Internal Server Error: An issue occurred on the server.

Cancel Pickup Shipment

This method to cancel the pickup shipment

API Endpoint

 
      
      http://staging-api.oneeasystop.com:3000/api/cancel-pickup-shipment

Headers

Header Name	Value	Description
Content-Type	application/json	Specifies the format of the request body.
Authorization	Bearer <your_token_here >	Bearer token for authentication.

Request Body

The request body contains the order details and related information. It must be sent as a JSON object with the following structure:

Root Object:

order

Type: Object
Description: Contains information about the cancel order.

Field Name	Type	Description
id	Number	Unique identifier for the order
status	String	Status for changing, e.g., "cancel"
description	String	Description of the parcel or order

Method: POST

                    
                     
                      {
                        "order": {
                          "id": 82,
                          "status": "cancel",
                          "description": ""
                        }
                      }

Response codes

200 Ok, The pickup cancellation has been successfully processed.

400 Bad Request: Invalid request body or missing required fields.

401 Unauthorized: Invalid or missing bearer token.

500 Internal Server Error: An issue occurred on the server.

Welcome To OES Developer portal.

Introduction

Basic api

Authorization

How to implement:

Note:

Authorization endpoint

Headers

Header Name

Value

Description

Body

Body Name

Type

Description

Example of Body

Response

Key

Type

Description

Example of return of “Authorization (Login)” method :

Method: POST

Quotes

Quotes API Endpoint

Headers

Header Name

Value

Description

Request Body

Root Object:

quotation

Properties:

Data:

Fields

Field Name

Type

Description

Values:

quotation

Field Name

Type

Description

Method: POST

Response codes

Response Explanation:

Root Object: data

Response Fields:

Field Name

Type

Description

Creating Shipment

API Endpoint

Headers

Header Name

Value

Description

Request Body

Root Object:

order

Properties:

Order Fields

Field Name

Type

Description

Objects Array:

Field Name

Type

Description

Sender Details

Field Name

Type

Description

Receiver Details:

Field Name

Type

Description

Method: POST

Response codes

Response Explanation:

Root Object: order