NAV
shell

Introduction

Welcome to the OmniShip Cross Border API Documentation!

The OmniShip Cross Border API allows you to perform cross border operations on the OmniShip system.

OmniShip Cross Border API is built using REST principles which ensures predictable URLs that makes writing applications easy. This API follows HTTP rules, enabling a wide range of HTTP clients which can be used to interact with the API.

Every resource is exposed as a URL. The URL of each resource can be obtained by accessing the API Root Endpoint https://crossborder.omniship.eu/api/v1/.

For example the Customers resource is reachable at https://crossborder.omniship.eu/api/v1/customers.

Authentication

To authorize, use this code:

# With shell, you can just pass the correct header with each request
curl "https://crossborder.omniship.eu/api/v1/<resource>"
  -H "Authorization: FkihCtzyXWvutSRUaaEupN8hvABcDefgHI6lJKvv"
  -H "Content-Type: application/json"

Make sure to replace FkihCtzyXWvutSRUaaEupN8hvABcDefgHI6lJKvv with your API key.

OMNISHIP uses API keys to allow access to the API. Contact your OMNISHIP representative to receive a new OMNISHIP API key.

In order to authenticate properly, please put Authorization: Bearer <API Access Token> in the request header. OMNISHIP expects for the API key to be included in all API requests to the server in a header that looks like the following:

Authorization: FkihCtzyXWvutSRUaaEupN8hvABcDefgHI6lJKvv

Waybills

Example:

{
  "customer_code": "GFS",
  "waybill_type": "air",
  "waybill_number": "784-65428952",
  "reference": 71577,
  "weight_unit": "grams",
  "pre_alert_rows": [
    {
      "order_number": "GSHML800Y0007SD",
      "package_barcode": "01505272372693",
      "bag_grade": "Z42104029016",
      "shipping_method": "DE DPD",
      "weight": "551.00",
      "company_name": null,
      "consignee_name": null,
      "phone_number": null,
      "email_address": null,
      "street": null,
      "house_number": null,
      "house_number_extension": null,
      "additional_address_info": null,
      "city_or_town": "Stödtlen",
      "state_or_province": null,
      "zip_code": "73495",
      "country_code": "DE",
      "sku_code": null,
      "sku_description": null,
      "quantity": 0,
      "currency": null,
      "price": null,
      "shipping_costs": null,
      "hs_code": null,
      "website": null
    },
    {"..."},
    {"..."}
  ]
}

A waybill is a document that represents the contents of a shipment ready for transport. It details the exact quantity, price and delivery details of the individual packages. Perform the simple operations mentioned below to create and manage your Waybill pre alert.

Attribute Type Description
customer_code string Unique ID of a customer. This is used as an identifier.
waybill_type string The type of waybill. Valid values are ('air', 'road', 'train', 'sea', 'other').
waybill_number string Identifies the total shipment. If waybill type is 'air' a validation check is done on the format of the waybill_number given.
reference string Unique identifier of the shipment. Usually an id of the original system where the pre-alert was uploaded.
weight_unit string Unit of weight used in the pre-alert. Valid values are ('grams', 'kilograms')
pre_alert_rows array A pre alert contains multiple pre_alert rows. Each pre alert row contains order_number, package_barcode, bag_grade, shipping_method, weight, company_name, consignee_name, phone_number, email_address, street, house_number, house_number_extension, additional_address_info, city_or_town, state_or_province, zip_code, country_code, sku_code, sku_description, quantity, currency, price, shipping_costs, hs_code, website

Retrieve a Specific Waybill

curl "https://crossborder.omniship.eu/api/v1/waybills/3265"
  -H "Authorization: FkihCtzyXWvutSRUaaEupN8hvABcDefgHI6lJKvv"
  -H "Content-Type: application/json"

The above command returns JSON structured like this:

HTTP/1.1 200 OK
Content-Type:application/json;charset=UTF-8

{
  "id": 3265,
  "type": "air",
  "number": "784-65428963",
  "reference": 71585,
  "total_weight": 16951,
  "total_bags": 4,
  "status": "created",
  "status_changed": "2021-06-29T14:23:39.000000Z",
  "status_changed_human": "2 minutes ago",
  "inbound": 0,
  "outbound": 0,
  "job_state": "finished",
  "date_received": "2021-06-29T14:23:33.000000Z",
  "updated_at": "2021-06-29T14:23:39.000000Z",
  "customer": "Global Freight System",
  "bags": [
    {
      "id": 2758501,
      "container_id": null,
      "air_waybill_id": 3265,
      "reference": "Z42104029016",
      "total_weight": 9239,
      "status": null,
      "inbound": false,
      "outbound": false,
      "custom": false,
      "customCountry": null,
      "country": "DE",
      "country_name": "Germany",
      "owner": null,
      "updated_at": "2021-06-29T14:23:39.000000Z"
    },
    {
      "id": 2758502,
      "container_id": null,
      "air_waybill_id": 3265,
      "reference": "Z42104029015",
      "total_weight": 2082,
      "status": null,
      "inbound": false,
      "outbound": false,
      "custom": false,
      "customCountry": null,
      "country": "DE",
      "country_name": "Germany",
      "owner": null,
      "updated_at": "2021-06-29T14:23:39.000000Z"
    },
    {
      "id": 2758503,
      "container_id": null,
      "air_waybill_id": 3265,
      "reference": "Z42104027049",
      "total_weight": 5569,
      "status": null,
      "inbound": false,
      "outbound": false,
      "custom": false,
      "customCountry": null,
      "country": "DE",
      "country_name": "Germany",
      "owner": null,
      "updated_at": "2021-06-29T14:23:39.000000Z"
    },
    {
      "id": 2758504,
      "container_id": null,
      "air_waybill_id": 3265,
      "reference": "Z4210402730",
      "total_weight": 61,
      "status": null,
      "inbound": false,
      "outbound": false,
      "custom": false,
      "customCountry": null,
      "country": "DE",
      "country_name": "Germany",
      "owner": null,
      "updated_at": "2021-06-29T14:23:39.000000Z"
    }
  ],
  "in_container": 0,
  "total": 4,
  "container_count": 0,
  "airline": {
    "id": 196,
    "prefix": "784",
    "code": "CZ",
    "name": "China Southern Airlines "
  }
}

This endpoint retrieves a specific Waybill.

HTTP Request

GET https://crossborder.omniship.eu/api/v1/waybills/<ID>

URL Parameters

Parameter Description
ID The ID of the Waybill

Errors

The Cross Border API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API key is wrong.
403 Forbidden -- The resource requested is hidden for administrators only.
404 Not Found -- The specified resource could not be found.
405 Method Not Allowed -- You tried to access a kitten with an invalid method.
406 Not Acceptable -- You requested a format that isn't json.
410 Gone -- The resource requested has been removed from our servers.
422 Unprocessable Entity -- The server was unable to process the request because it contains invalid data.
429 Too Many Requests -- You're requesting too many resources.
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.
shell