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/v2/.

For example the Customers resource is reachable at https://crossborder.omniship.eu/api/v2/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/v2/<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": [
    {
      "parcel_id": "WBDEM100073974019U",
      "package_barcode": "226003462045",
      "seller_name": "Wildberries LLC",
      "seller_ioss_nr": "IM2760006126",
      "seller_street": "Koledino village 6 building 1",
      "seller_city": "Podolsk",
      "seller_country_code": "RU",
      "transaction_type": "B2C",
      "buyer_name": "Marco Polo",
      "buyer_eori": null,
      "buyer_street": "Engelbertring 1",
      "buyer_zipcode": "59755",
      "buyer_city": "Berlin",
      "buyer_country_code": "DE",
      "quantity": "1",
      "weight": "2.29",
      "item_hs_code": "950300",
      "goods_description": "Book",
      "invoice_currency": "EUR",
      "invoice_amount": "7.23",
      "charges_currency": null,
      "other_charges": 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.
customs_declaration string Indicates if OmniShip should process the customs declaration for this shipment. Default is true.
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 parcel_id, package_barcode, seller_name, seller_ioss_nr, seller_street, seller_city, seller_country_code, transaction_type, buyer_name, buyer_street, buyer_city, buyer_country_code, item_hs_code, quantity, weight, item_hs_code, goods_description, invoice_currency, invoice_amount

Retrieve a Specific Waybill

curl "https://crossborder.omniship.eu/api/v2/waybills/85"
  -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": 85,
  "type": "air",
  "number": "784-65428955",
  "reference": null,
  "total_weight": 3410,
  "status": "part_out",
  "status_changed": "2022-02-21T00:29:07.000000Z",
  "status_changed_human": "11 hours ago",
  "inbound_complete": true,
  "total_parcels": 13,
  "parcels_inbound": 4,
  "parcels_inbound_percentage": "30.77%",
  "parcels_released": 13,
  "parcels_released_percentage": "100%",
  "parcels_outbound": 9,
  "parcels_outbound_percentage": "69.23%",
  "date_received": "2022-02-21T00:03:00.000000Z",
  "updated_at": "2022-02-21T00:29:07.000000Z",
  "customer": "Global Freight Services",
  "parcels": [
    {
      "id": 35322300,
      "bag_grade_id": 4454090,
      "bag_reference": "IHB4202093070",
      "parcel_barcode": "IHB4202093070",
      "country": "Spain",
      "country_code": "ES",
      "shipping_method": "CORREOSEXPRESS",
      "inbound": false,
      "inbound_completed": "2022-02-20 22:14:45",
      "outbound": true,
      "outbound_completed": "2022-02-20 22:24:23",
      "weight": 400,
      "customs_status": "released",
      "status_changed": "2022-02-21T00:25:42.000000Z",
      "status_changed_human": "11 hours ago",
      "container_barcode": "C2022-0000248",
      "items": 2
    },
    {
      "id": 35322301,
      "bag_grade_id": 4454091,
      "bag_reference": "IHB4202094040",
      "parcel_barcode": "IHB4202094040",
      "country": "Netherlands",
      "country_code": "NL",
      "shipping_method": "MONDIAL RELAY",
      "inbound": false,
      "inbound_completed": "2022-02-20 22:15:45",
      "outbound": true,
      "outbound_completed": "2022-02-20 22:25:23",
      "weight": 130,
      "customs_status": "released",
      "status_changed": "2022-02-21T00:25:49.000000Z",
      "status_changed_human": "11 hours ago",
      "container_barcode": "C2022-0000246",
      "items": 1
    },
    {
      "id": 35322302,
      "bag_grade_id": 4454092,
      "bag_reference": "IHB4202102130",
      "parcel_barcode": "IHB4202102130",
      "country": "Spain",
      "country_code": "ES",
      "shipping_method": "CORREOSEXPRESS",
      "inbound": false,
      "inbound_completed": "2022-02-20 22:15:49",
      "outbound": true,
      "outbound_completed": "2022-02-20 22:26:25",
      "weight": 90,
      "customs_status": "released",
      "status_changed": "2022-02-21T00:25:42.000000Z",
      "status_changed_human": "11 hours ago",
      "container_barcode": "C2022-0000248",
      "items": 1
    },
    {
      "id": 35322303,
      "bag_grade_id": 4454093,
      "bag_reference": "IHB4202102280",
      "parcel_barcode": "IHB4202102280",
      "country": "France",
      "country_code": "FR",
      "shipping_method": "Colisprive",
      "inbound": false,
      "inbound_completed": "2022-02-20 22:16:35",
      "outbound": true,
      "outbound_completed": "2022-02-20 22:27:15",
      "weight": 120,
      "customs_status": "released",
      "status_changed": "2022-02-21T00:25:52.000000Z",
      "status_changed_human": "11 hours ago",
      "container_barcode": "C2022-0000247",
      "items": 1
    },
    {
      "id": 35322304,
      "bag_grade_id": 4454094,
      "bag_reference": "IHB4202102550",
      "parcel_barcode": "IHB4202102550",
      "country": "France",
      "country_code": "FR",
      "shipping_method": "Colisprive",
      "inbound": false,
      "inbound_completed": "2022-02-20 22:16:21",
      "outbound": true,
      "outbound_completed": "2022-02-20 22:23:18",
      "weight": 540,
      "customs_status": "released",
      "status_changed": "2022-02-21T00:25:52.000000Z",
      "status_changed_human": "11 hours ago",
      "container_barcode": "C2022-0000247",
      "items": 2
    },
    {
      "id": 35322305,
      "bag_grade_id": 4454095,
      "bag_reference": "IHB4202102770",
      "parcel_barcode": "IHB4202102770",
      "country": "Estonia",
      "country_code": "EE",
      "shipping_method": "VENIPAK",
      "inbound": true,
      "inbound_completed": "2022-02-20 22:17:44",
      "outbound": false,
      "outbound_completed": null,
      "weight": 250,
      "customs_status": "released",
      "status_changed": "2022-02-21T00:11:28.000000Z",
      "status_changed_human": "12 hours ago",
      "container_barcode": "C2022-0000243",
      "items": 2
    },
    {
      "id": 35322306,
      "bag_grade_id": 4454096,
      "bag_reference": "IHB4202102950",
      "parcel_barcode": "IHB4202102950",
      "country": "Estonia",
      "country_code": "EE",
      "shipping_method": "VENIPAK",
      "inbound": true,
      "inbound_completed": "2022-02-20 22:17:22",
      "outbound": false,
      "outbound_completed": null,
      "weight": 160,
      "customs_status": "released",
      "status_changed": "2022-02-21T00:11:28.000000Z",
      "status_changed_human": "12 hours ago",
      "container_barcode": "C2022-0000243",
      "items": 2
    },
    {
      "id": 35322307,
      "bag_grade_id": 4454097,
      "bag_reference": "IHB4202103120",
      "parcel_barcode": "IHB4202103120",
      "country": "Latvia",
      "country_code": "LV",
      "shipping_method": "VENIPAK",
      "inbound": true,
      "inbound_completed": "2022-02-20 22:18:11",
      "outbound": false,
      "outbound_completed": null,
      "weight": 250,
      "customs_status": "released",
      "status_changed": "2022-02-21T00:11:28.000000Z",
      "status_changed_human": "12 hours ago",
      "container_barcode": "C2022-0000243",
      "items": 2
    },
    {
      "id": 35322308,
      "bag_grade_id": 4454098,
      "bag_reference": "IHB4202103380",
      "parcel_barcode": "IHB4202103380",
      "country": "Latvia",
      "country_code": "LV",
      "shipping_method": "VENIPAK",
      "inbound": true,
      "inbound_completed": "2022-02-20 22:18:52",
      "outbound": false,
      "outbound_completed": null,
      "weight": 430,
      "customs_status": "released",
      "status_changed": "2022-02-21T00:11:28.000000Z",
      "status_changed_human": "12 hours ago",
      "container_barcode": "C2022-0000243",
      "items": 2
    },
    {
      "id": 35322309,
      "bag_grade_id": 4454099,
      "bag_reference": "IHB4202103970",
      "parcel_barcode": "IHB4202103970",
      "country": "Croatia",
      "country_code": "HR",
      "shipping_method": "Meest Hungary",
      "inbound": false,
      "inbound_completed": "2022-02-20 22:19:13",
      "outbound": true,
      "outbound_completed": "2022-02-20 22:25:41",
      "weight": 290,
      "customs_status": "released",
      "status_changed": "2022-02-21T00:28:32.000000Z",
      "status_changed_human": "11 hours ago",
      "container_barcode": "C2022-0000244",
      "items": 2
    },
    {
      "id": 35322310,
      "bag_grade_id": 4454100,
      "bag_reference": "IHB4202104260",
      "parcel_barcode": "IHB4202104260",
      "country": "Croatia",
      "country_code": "HR",
      "shipping_method": "Meest Hungary",
      "inbound": false,
      "inbound_completed": "2022-02-20 22:17:23",
      "outbound": true,
      "outbound_completed": "2022-02-20 22:28:29",
      "weight": 250,
      "customs_status": "released",
      "status_changed": "2022-02-21T00:28:32.000000Z",
      "status_changed_human": "11 hours ago",
      "container_barcode": "C2022-0000244",
      "items": 2
    },
    {
      "id": 35322311,
      "bag_grade_id": 4454101,
      "bag_reference": "IHB4202106550",
      "parcel_barcode": "IHB4202106550",
      "country": "Germany",
      "country_code": "DE",
      "shipping_method": "HERMES",
      "inbound": false,
      "inbound_completed": "2022-02-20 22:15:32",
      "outbound": true,
      "outbound_completed": "2022-02-20 22:28:20",
      "weight": 300,
      "customs_status": "released",
      "status_changed": "2022-02-21T00:24:05.000000Z",
      "status_changed_human": "11 hours ago",
      "container_barcode": "C2022-0000245",
      "items": 1
    },
    {
      "id": 35322312,
      "bag_grade_id": 4454102,
      "bag_reference": "IHB4202106680",
      "parcel_barcode": "IHB4202106680",
      "country": "Germany",
      "country_code": "DE",
      "shipping_method": "HERMES",
      "inbound": false,
      "inbound_completed": "2022-02-20 22:17:03",
      "outbound": true,
      "outbound_completed": "2022-02-20 22:28:09",
      "weight": 200,
      "customs_status": "released",
      "status_changed": "2022-02-21T00:24:05.000000Z",
      "status_changed_human": "11 hours ago",
      "container_barcode": "C2022-0000245",
      "items": 2
    }
  ],
  "total_bags": 13,
  "container_count": 6,
  "airline": {
    "id": 1,
    "prefix": "074",
    "code": "CZ",
    "name": "China Southern",
    "ground_handler_code": "Dnata"
  }
}

This endpoint retrieves a specific Waybill.

HTTP Request

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

URL Parameters

Parameter Description
ID The ID of the Waybill

Shipping Methods

Example:

{
  "id": 19,
  "name": "DHLAMS",
  "address": {
    "id": 9597,
    "name": null,
    "company": "DHL Amsterdam",
    "line_1": "Kappstadweg 25",
    "line_2": null,
    "postal_code": "1047 HG",
    "city": "AMSTERDAM",
    "state": null,
    "country": "NL",
    "addressable_id": null,
    "addressable_type": null,
    "type_id": null,
    "original_id": null,
    "created_by": 66,
    "created_at": "2022-02-21T14:19:37.000000Z",
    "updated_at": "2022-02-21T14:19:37.000000Z"
  },
  "customer": "Global Freight Services"
}

A Shipping Method represents the destination that can be assigned to parcels by using the name attribute in the pre-alert upload.

Attribute Type Description
id integer Unique ID of a Shipping Method. This is used as an identifier.
name string Unique code to identify a Shipping Method.
address Object Address associated with the shipping method.

List all Shipping Methods

curl "https://crossborder.omniship.eu/api/v2/shipping_methods"
  -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

{
  "data": [
    {
      "id": 7,
      "name": "MONDIAL RELAY",
      "address": {
        "id": 9515,
        "name": null,
        "company": "MONDIAL RELAY",
        "line_1": "AVENUE ANTOINE PINAY",
        "line_2": "SORTING CENTRE 5",
        "postal_code": "59510",
        "city": "HEM",
        "state": null,
        "country": "FR",
        "addressable_id": null,
        "addressable_type": null,
        "type_id": null,
        "original_id": null,
        "created_by": 1,
        "created_at": "2022-02-10T01:08:09.000000Z",
        "updated_at": "2022-02-10T01:08:09.000000Z"
      },
      "customer": "Global Freight Services"
    },
    {
      "id": 8,
      "name": "Colisprive",
      "address": {
        "id": 9516,
        "name": null,
        "company": "Colisprive",
        "line_1": "RUE GEOERGES LEFEBVRE",
        "line_2": "HUB COLIS PRIVE",
        "postal_code": "62117",
        "city": "BREBIERES",
        "state": null,
        "country": "FR",
        "addressable_id": null,
        "addressable_type": null,
        "type_id": null,
        "original_id": null,
        "created_by": 1,
        "created_at": "2022-02-10T01:09:12.000000Z",
        "updated_at": "2022-02-10T01:09:12.000000Z"
      },
      "customer": "Global Freight Services"
    },
    {
      "id": 19,
      "name": "DHLAMS",
      "address": {
        "id": 9597,
        "name": null,
        "company": "DHL Amsterdam",
        "line_1": "Kappstadweg 25",
        "line_2": null,
        "postal_code": "1047 HG",
        "city": "AMSTERDAM",
        "state": null,
        "country": "NL",
        "addressable_id": null,
        "addressable_type": null,
        "type_id": null,
        "original_id": null,
        "created_by": 66,
        "created_at": "2022-02-21T14:19:37.000000Z",
        "updated_at": "2022-02-21T14:19:37.000000Z"
      },
      "customer": "Global Freight Services"
    },
    {"..."},
    {"..."}
    ]
}

This endpoint retrieves all Shipping Methods.

HTTP Request

GET https://crossborder.omniship.eu/api/v2/shipping_methods

Create a Shipping Method

curl "https://crossborder.omniship.eu/api/v2/shipping_methods"
  -X POST
  -H "Authorization: FkihCtzyXWvutSRUaaEupN8hvABcDefgHI6lJKvv"
  -H "Content-Type: application/json"
  -d '{
        "name": "DHLAMS",
        "address": {
          "company": "DHL Amsterdam",
          "line_1": "Kappstadweg 25",
          "postal_code": "1047 HG",
          "city": "AMSTERDAM",
          "country": "NL"
          }
      }'

The above command returns JSON structured like this:

HTTP/1.1 201 Created
Content-Type:application/json;charset=UTF-8

{
  "id": 19,
  "name": "DHLAMS",
  "address": {
    "id": 9596,
    "name": null,
    "company": "DHL Amsterdam",
    "line_1": "Kappstadweg 25",
    "line_2": null,
    "postal_code": "1047 HG",
    "city": "AMSTERDAM",
    "state": null,
    "country": "NL",
    "addressable_id": null,
    "addressable_type": null,
    "type_id": null,
    "original_id": null,
    "created_by": 66,
    "created_at": "2022-02-21T14:17:34.000000Z",
    "updated_at": "2022-02-21T14:17:34.000000Z"
  },
  "customer": "Global Freight Services"
}

This endpoint creates a new Shipping Method in OMNISHIP cross border.

HTTP Request

POST https://crossborder.omniship.eu/api/v2/shipping_methods

Arguments

Attribute Type Description
name string required Unique code to identify a Shipping Method.
address object required The Address object associated with the shipping Method.

Address Parameters

Attribute Type Description
name string optional Contact name associated with the address. Maximum 35 characters.
company string required Company name associated with the address. Maximum 70 characters.
line_1 string required Address Line 1 associated with the address.
line_2 string optional Address Line 2 associated with the address.
postal_code string optional Postal Code associated with the address.
city string required City associated with the address.
country string required Country code associated with the address. (needs to be ISO 3166 2-char code).

Retrieve a Specific Shipping Method

curl "https://crossborder.omniship.eu/api/v2/shipping_methods/19"
  -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": 19,
  "name": "DHLAMS",
  "address": {
    "id": 9597,
    "name": null,
    "company": "DHL Amsterdam",
    "line_1": "Kappstadweg 25",
    "line_2": null,
    "postal_code": "1047 HG",
    "city": "AMSTERDAM",
    "state": null,
    "country": "NL",
    "addressable_id": null,
    "addressable_type": null,
    "type_id": null,
    "original_id": null,
    "created_by": 66,
    "created_at": "2022-02-21T14:19:37.000000Z",
    "updated_at": "2022-02-21T14:19:37.000000Z"
  },
  "customer": "Global Freight Services"
}

This endpoint retrieves a specific Shipping Method.

HTTP Request

GET https://crossborder.omniship.eu/api/v2/shipping_methods/<ID>

URL Parameters

Parameter Description
ID The ID of the Shipping Method

Update a Shipping Method

curl "https://crossborder.omniship.eu/api/v2/shipping_methods/19"
  -X PATCH
  -H "Authorization: FkihCtzyXWvutSRUaaEupN8hvABcDefgHI6lJKvv"
  -H "Content-Type: application/json"
  -d '{
        "name": "Post Delivery Rotterdam",
        "address": {
          "postal_code": "1092 TE"
        }
      }'

The above command returns JSON structured like this:

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

{
  "id": 19,
  "name": "Post Delivery Rotterdam",
  "address": {
    "id": 9596,
    "name": null,
    "company": "DHL Amsterdam",
    "line_1": "Kappstadweg 25",
    "line_2": null,
    "postal_code": "1092 TE",
    "city": "AMSTERDAM",
    "state": null,
    "country": "NL",
    "addressable_id": null,
    "addressable_type": null,
    "type_id": null,
    "original_id": null,
    "created_by": 66,
    "created_at": "2022-02-21T14:17:34.000000Z",
    "updated_at": "2022-02-21T14:17:34.000000Z"
  },
  "customer": "Global Freight Services"
}

This endpoint updates a Shipping Method in OMNISHIP cross border. This is helpful if you want to change the name, or you want to change the address of a Shipping Method.

HTTP Request

PATCH https://crossborder.omniship.eu/api/v2/shipping_methods/<ID>

URL Parameters

Parameter Description
ID The ID of the Shipping Method to update

Arguments

Attribute Type Description
name string Unique code to identify a Shipping Method.
address Object Address associated with the shipping method.

Delete a Specific Shipping Method

curl "https://crossborder.omniship.eu/api/v2/shipping_methods/19"
  -H "Authorization: FkihCtzyXWvutSRUaaEupN8hvABcDefgHI6lJKvv"
  -H "Content-Type: application/json"

The above command returns JSON structured like this:

HTTP/1.1 204 NO CONTENT
Content-Type:application/json;charset=UTF-8

[]

This endpoint deletes a specific Shipping Method.

HTTP Request

DELETE https://crossborder.omniship.eu/api/v2/shipping_methods/<ID>

URL Parameters

Parameter Description
ID The ID of the Shipping Method

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