Orders repository API Endpoints Reference

Version: 1

Base URL: https://orders-repository.system.trans.eu/api/rest/v1

Resources

Orders

Create order

Scopes

orders-repository.orders.add

Endpoint

POST /orders

Request body data

Field	Type	Description	Required
custom_ids	Array (of CustomId)	optional external system ID	false
number	String	order number	false
status	String	optional external system status	false
terms	String	order terms	false
description	String		false
route	Array (of RouteEvent)		false
loads	Array (of Load)		false
shipper	Object (Contractor)		false
carrier	Object (Contractor)		false
payer	Object (Contractor)		false
payment	Object (Payment)		false
documents	Array (of Document)		false
vehicles	Array (of OrderVehicle)		false
drivers	Array (of Driver)		false

CustomId object structure

Field	Type	Description
id	String	External system ID
source	String	External system alias

RouteEvent object structure

Field	Type	Description
place	Object (Place)
timespans	Object (TimeSpans)
type	Enum	Event type. Possible values: `loading`, `unloading`
notes	Array (of String)
loads	Array (of String)	Can be used to hold references to specific loads by Load.custom_id

Place object structure

Field	Type	Description
address	Object (Address)	Address details
coordinates	Object (Coordinates)

TimeSpans object structure

Field	Type	Description
begin	String	any datetime
end	String	any datetime

Address object structure

Field	Type	Description
locality	String	City name
postal_code	String	Postal code
country	String	Country code in format ISO 3166-1 alpha-2
street	String	Street name
number	String	Street number

Coordinates object structure

Field	Type	Description
latitude	float	[-90;90][precision: 6 digits]
longitude	float	[-180;180][precision: 6 digits]

Load object structure

Field	Type	Description
custom_id	String
name	String
description	String
type_of_load	String
weight	Object (Weight)
height	Object (Height)
width	Object (Width)
length	Object (Length)
volume	Object (Volume)
amount	positive Integer
requirements	Object (Requirements)
shipper	Object (Contractor)
carrier	Object (Contractor)
payer	Object (Contractor)

Weight object structure

Field	Type	Description
value	positive float	[precision: 3 digits]
unit_code	String	ISO 2955 c/i value ie. `TNE`

Height object structure

Field	Type	Description
value	positive float	[precision: 3 digits]
unit_code	String	ISO 2955 c/i value ie. `M`

Width object structure

Field	Type	Description
value	positive float	[precision: 3 digits]
unit_code	String	ISO 2955 c/i value ie. `M`

Length object structure

Field	Type	Description
value	positive float	[precision: 3 digits]
unit_code	String	ISO 2955 c/i value ie. `M`

Volume object structure

Field	Type	Description
value	positive float	[precision: 3 digits]
unit_code	String	ISO 2955 c/i value ie. `M3`

Requirements object structure

Field	Type	Description
required_ways_of_loading	Array (of Enum)	Enum values: `top`, `side`, `back`. Says which side load should be put into the vehicle
required_truck_bodies	Array (of String)	which type of vehicle/trailer body should be used to carry the load
required_adr_classes	Array (of Enum)	Enum values: hazard classes ie. `4.1`
is_truck_crane_required	Boolean
is_lift_required	Boolean
is_for_clearance	Boolean	whether load should be "ready to declare" - to excise on country border
is_tir_cable_required	Boolean	whether load should be secured by ropes
is_ftl	Boolean	whether shipper requires vehicles exclusively for purpose of carrying the loads
is_tracking_system_required	Boolean	whether shipper requires GPS tracking of carrier's vehicles
shipping_remarks	String	place for shippers additional remarks & requirements

Contractor object structure

Field	Type	Description
trans_company_id	positive Integer
custom_id	String
name	String
vat_id	String
email	String	valid e-mail
telephone	String	digits, and `+-()` characters and whitespaces
fax	String	digits, and `+-()` characters and whitespaces
address	Object (Address)
contact_persons	Array ( of Person)

Person object structure

Field	Type	Description
trans_id	String	TransID
custom_id	String
family_name	String
given_name	String
email	String	valid e-mail
telephone	String	digits, and `+-()` characters and whitespaces
fax	String	digits, and `+-()` characters and whitespaces

Payment object structure

Field	Type	Description
price	Object (Price)
interval_of_days	Object (Price)
status	String

Price object structure

Field	Type	Description
value	positive Integer	value passed as integer in the smallest unit of currency
offset	positive Integer	positive int (power of 10), i.e. how much cents are in 1 euro (it's 100 for most of currencies)
currency	String	string (ISO 4217)

OrderVehicle object structure

Field	Type	Description
vehicle	Object (Vehicle)
trailer	Object (Trailer)

Document object structure

Field	Type	Description
custom_id	String	ID of document in user's external system
uri	String
type	String
description	String

Vehicle object structure

Field	Type	Description
custom_id	String	ID of vehicle in user's external system
registration_plate_number	String
body_type	String
bearing_capacity	Object (Volume)

Trailer object structure

Field	Type	Description
custom_id	String	ID of trailer in user's external system
registration_plate_number	String
body_type	String
bearing_capacity	Object (Volume)

Driver object structure

Field	Type	Description
trans_id	String	TransID
custom_id	String
family_name	String
given_name	String
id_card_number	String	driver's ID card number
email	String	valid e-mail
telephone	String	digits, and `+-()` characters and whitespaces

Responses

Http status	Description
201	Order was created
403	Forbidden
422	Unprocessable entity - this error occures when user send request with invalid data

Example

POST /api/rest/v1/orders
Host: orders-repository.system.trans.eu
Accept: application/hal+json
Authorization: Bearer {access_token}

{
  "custom_ids": [
    {
      "id": "12345",
      "source": "TransOrders"
    }
  ],
  "number": "DE/3455/4444",
  "status": "pending",
  "terms": "Some long order terms...",
  "description": "Some text from owner or anyone else..",
  "route" : [
    {
      "place": {
        "address": {
          "locality": "Wroclaw",
          "postal_code": "50-539",
          "country": "PL",
          "street": "Krynicka",
          "number": "2A/20"
        },
        "coordinates": {
          "latitude": 51.082743,
          "longitude": 17.047332
        }
      },
      "timespans": [
        {
          "begin": "2016-05-11T08:00:00+00:00",
          "end": "2016-05-11T11:00:00+00:00"
        }
      ],
      "type": "loading",
      "loads": ["1", "2"],
      "notes": [
        "Panie Janie prosze o kontakt."
      ]
    },
    {
      "place": {
        "address": {
          "locality": "Wroclaw",
          "postal_code": "50-539",
          "country": "PL",
          "street": "Krynicka",
          "number": "2A/20"
        },
        "coordinates": {
          "latitude": 51.082743,
          "longitude": 17.047332
        }
      },
      "timespans": [
        {
          "begin": "2016-05-12T12:00:00+00:00",
          "end": "2016-05-12T16:00:00+00:00"
        }
      ],
      "loads": ["1", "2"],
      "type": "unloading"
    }
  ],
  "loads" : [
    {
      "custom_id": "1",
      "name": "Some load",
      "description": "Some random load desc",
      "type_of_load": "box",
      "weight" : {
        "value" : 23,
        "unit_code" : "TNE"
      },
      "height": {
        "value": 1.0,
        "unit_code": "M"
      },
      "width": {
        "value": 1.5,
        "unit_code": "M"
      },
      "length": {
        "value": 1.2,
        "unit_code": "M"
      },
      "volume": {
        "value": 1.8,
        "unit_code": "M3"
      },
      "amount": 5,
      "requirements": {
        "required_ways_of_loading": ["side", "back"],
        "required_truck_bodies": ["freezer"],
        "required_adr_classes": ["2", 4.1"],
        "is_truck_crane_required": true,
        "is_lift_required": false,
        "is_for_clearance": true,
        "is_tir_cable_required": false,
        "is_ftl": true,
        "is_tracking_system_required": true,
        "shipping_remarks": "just one small thing"
      }
    }
  ],
  "shipper": {
    "name": "Trans.eu",
    "vat_id": "000111122222",
    "telephone": "(22)332-21-13",
    "fax": "(22) 332 21 14",
    "address": {
      "locality": "London",
      "postal_code": "L333",
      "country": "GB",
      "street": "Some Avenue",
      "number": "5"
    }
    "contact_persons": [
      {
        "family_name": "Test",
        "given_name": "Test",
        "email": "test@rst.com.pl",
        "telephone": "1001000100",
        "fax": "(22) 332 21 14"
      }
    ]
  },
  "carrier": {
    "trans_company_id": 2134,
    "custom_id": "ABC001",
    "name": "Carrier Trans.eu",
    "vat_id": "00011114444",
    "email": "carrier@trans.eu",
    "address": {
      "locality": "Wroclaw",
      "postal_code": "50-539",
      "country": "PL",
      "street": "Krynicka",
      "number": "2A/20"
    }
    "contact_persons": [
      {
        "trans_id": "2134-2",
        "custom_id": "ABC001",
        "family_name": "Test",
        "given_name": "Test",
        "email": "test@rst.com.pl",
        "telephone": "1001000100"
      }
    ]
  },
  "payer": {
    "name": "Trans.eu",
    "vat_id": "000111122222",
    "address": {
      "locality": "London",
      "postal_code": "L333",
      "country": "GB",
      "street": "Some Avenue",
      "number": "5"
    }
    "contact_persons": [
      {
        "family_name": "Test",
        "given_name": "Test",
        "email": "test@rst.com.pl",
        "telephone": "1001000100"
      }
    ]
  },
  "payment": {
    "price": {
      "value": 34,
      "offset": 100,
      "currency": "PLN"
    },
    "interval_of_days": 10,
    "status": "paid"
  },
  "documents": [
    {
      "custom_id": "XXX",
      "uri": "http://uri-to-document.com/Some-example.doc",
      "type": "cmr",
      "description": "Description of Some-example.doc."
    }
  ],
  "vehicles": [
    {
      "vehicle": {
        "custom_id": "1234",
        "registration_plate_number": "ABCDEF",
        "body_type": "freezer",
        "bearing_capacity": {
          "value": 12,
          "unit": "TNE"
        }
      },
      "trailer": {
        "custom_id": "2345",
        "registration_plate_number": "123456",
        "body_type": "freezer",
        "bearing_capacity": {
          "value": 12.0,
          "unit": "TNE"
        }
      }
    }
  ],
  "drivers": [
    {
      "trans_id": "2134-2",
      "family_name": "Test",
      "given_name": "Test",
      "id_card_number": "ABC001002",
      "email": "test@rst.com.pl",
      "telephone": "1001000100"
    }
  ],
  "_embedded": {
    "metadata": {
      "revision": "d459813b-7708-4a83-8dcd-672581dc5d3d",
      "modified": "2017-04-03T11:41:49+00:00"
    }
  }
}

Get order

Scopes

orders-repository.orders.read

Endpoint

GET /orders

Query parameters

Query parameter	Type	Required	Value
page	integer	no	result page number

Responses

Http status	Description
200	OK
403	Forbidden
409	Page not found

Example

GET /api/rest/v1/orders
Host: orders-repository.system.trans.eu
Accept: application/hal+json
Authorization: Bearer {access_token}

HTTP/1.1 200 OK
Content-Type: application/hal+json
{
  "_links": {
    "self": {
      "href": "http://orders-repository.system.trans.eu/api/rest/v1/orders?page=1"
    },
    "first": {
      "href": "http://orders-repository.system.trans.eu/api/rest/v1/orders"
    },
    "last": {
      "href": "http://orders-repository.system.trans.eu/api/rest/v1/orders?page=1"
    }
  },
  "_embedded": {
    "orders": [
        ...
    ]
   },
  "page_count": 1,
  "page_size": 25,
  "total_items": 1,
  "page": 1
}

Endpoint

GET /orders/{ID}

Responses

Http status	Description
200	OK
403	Forbidden
404	Order not found
422	Invalid request

Example

GET /api/rest/v1/orders/123e4567-e89b-12d3-a456-426655440000
Host: orders-repository.system.trans.eu
Accept: application/hal+json
Authorization: Bearer {access_token}

{
  "id": "123e4567-e89b-12d3-a456-426655440000",
  "custom_ids": [
    {
      "id": "123456",
      "source": "TransOrders"
    },
    {
      "id": "AB45",
      "source": "SomeExternalSystem"
    }
  ],
  "number": "DE/3455/4444",
  "status": "pending",
  "terms": "Some long order terms...",
  "description": "Some text from owner or anyone else..",
  "route" : [
    {
      "place": {
        "address": {
          "locality": "Wroclaw",
          "postal_code": "50-539",
          "country": "PL",
          "street": "Krynicka",
          "number": "2A/20"
        },
        "coordinates": {
          "latitude": 51.082743,
          "longitude": 17.047332
        }
      },
      "timespans": [
        {
          "begin": "2016-05-11T08:00:00+00:00",
          "end": "2016-05-11T11:00:00+00:00"
        }
      ],
      "type": "loading",
      "notes": [
        "Dear John please contact me when you arrive."
      ]
    },
    {
      "place": {
        "address": {
          "address": {
            "locality": "Wroclaw",
            "postal_code": "50-539",
            "country": "PL",
            "street": "Krynicka",
            "number": "2A/20"
          }
        },
        "coordinates": {
          "latitude": 51.082743,
          "longitude": 17.047332
        }
      },
      "timespans": [
        {
          "begin": "2016-05-12T12:00:00+00:00",
          "end": "2016-05-12T16:00:00+00:00"
        }
      ],
      "type": "unloading"
    }
  ],
  "loads" : [
    {
      "description": "Some random load",
      "type_of_load": "box",
      "weight" : {
        "value" : 23,
        "unit_code" : "TNE"
      },
      "height": {
        "value": 1.0,
        "unit_code": "M"
      },
      "width": {
        "value": 1.5,
        "unit_code": "M"
      },
      "length": {
        "value": 1.2,
        "unit_code": "M"
      },
      "volume": {
        "value": 1.8,
        "unit_code": "M3"
      },
      "amount": 5,
      "requirements": {
        "required_ways_of_loading": ["side", "back"],
        "required_truck_bodies": ["freezer"],
        "required_adr_classes": ["2", 4.1"],
        "is_truck_crane_required": true,
        "is_lift_required": false,
        "is_for_clearance": true,
        "is_tir_cable_required": false,
        "is_tracking_system_required": true,
        "is_ftl": true,
        "shipping_remarks": "just one small thing"
      }
    }
  ],
  "shipper": {
    "name": "Trans.eu",
    "vat_id": "000111122222",
    "telephone": "(22)332-21-13",
    "fax": "(22) 332 21 14",
    "address": {
      "locality": "London",
      "postal_code": "L333",
      "country": "GB",
      "street": "Some Avenue",
      "number": "5"
    }
    "contact_persons": [
      {
        "family_name": "Test",
        "given_name": "Test",
        "email": "test@trans.eu",
        "telephone": "1001000100",
        "fax": "(22) 332 21 14"
      }
    ]
  },
  "carrier": {
    "trans_company_id": 2134,
    "custom_id": "ABC001",
    "name": "Carrier Trans.eu",
    "vat_id": "00011114444",
    "email": "carrier@trans.eu",
    "address": {
      "locality": "Wroclaw",
      "postal_code": "50-539",
      "country": "PL",
      "street": "Krynicka",
      "number": "2A/20"
    }
    "contact_persons": [
      {
        "trans_id": "2134-2",
        "custom_id": "ABC001",
        "family_name": "Test",
        "given_name": "Test",
        "email": "test@trans.eu",
        "telephone": "1001000100"
      }
    ]
  },
  "payer": {
    "name": "Trans.eu",
    "vat_id": "000111122222",
    "address": {
      "locality": "London",
      "postal_code": "L333",
      "country": "GB",
      "street": "Some Avenue",
      "number": "5"
    }
    "contact_persons": [
      {
        "family_name": "Test",
        "given_name": "Test",
        "email": "test@trans.eu",
        "telephone": "1001000100"
      }
    ]
  },
  "payment": {
    "price": {
      "value": 34,
      "offset": 100,
      "currency": "PLN"
    },
    "interval_of_days": 10,
    "status": "paid"
  },
  "vehicles": [
    {
      "vehicle": {
        "custom_id": "1234",
        "registration_plate_number": "ABCDEF",
        "body_type": "freezer",
        "bearing_capacity": {
          "value": 12,
          "unit": "TNE"
        }
      },
      "trailer": {
        "custom_id": "2345",
        "registration_plate_number": "123456",
        "body_type": "freezer",
        "bearing_capacity": {
          "value": 12.0,
          "unit": "TNE"
        }
      }
    }
  ],
  "drivers": [
    {
      "trans_id": "2134-2",
      "family_name": "Test",
      "given_name": "Test",
      "id_card_number": "ABC001002",
      "email": "test@trans.eu",
      "telephone": "1001000100"
    }
  ],
  "_embedded": {
    "metadata": {
      "revision": "d459813b-7708-4a83-8dcd-672581dc5d3d",
      "modified": "2017-04-03T11:41:49+00:00"
    }
  },
  "_links": {
    "self": {
      "href": "http://orders.system.trans.eu/api/rest/v1/orders/123e4567-e89b-12d3-a456-426655440000"
    }
  }
}

Update order

When updating order, only updated fields should be sent in request. Fields not mentioned in request will remain intact. To unset previously set field send null value or empty array [] for array fields. Revision identifier of editing order must be sent by X-Order-Revision header and it must be up-to-date, otherwise 409 will be returned. To get last revision identifier just fetch order and check it metadata.

Scopes

orders-repository.orders.update

Endpoint

PATCH /orders/{ID}

Responses

Http status	Description
200	OK
403	Forbidden
404	Order not found
409	Conflict
422	Invalid request

Example

PATCH /api/rest/v1/orders/123e4567-e89b-12d3-a456-426655440000
Host: orders-repository.system.trans.eu
Accept: application/hal+json
X-Order-Revision: 123e4567-e89b-12d3-a456-426655440000
Authorization: Bearer {access_token}

{
  "number": "NEW_NUMBER/3455/4444"
}

Delete order

Scopes

orders-repository.orders.delete

Endpoint

DELETE /orders/{ID}

Responses

Http status	Description
204	Deleted
403	Forbidden
404	Order not found

Example

DELETE /api/rest/v1/orders/123e4567-e89b-12d3-a456-426655440000
Host: orders-repository.system.trans.eu
Accept: application/hal+json
Authorization: Bearer {access_token}

Permissions

Grant access to edit order for other companies

Endpoint

POST /orders/{ID}/permissions

Request body data

Field	Type	Required
companies	Array(of CompanyId)	true

CompanyId object structure

Field	Type	Required
id	integer	true

Responses

Http status	Description
201	Granted access
403	Forbidden
404	Order not found
422	Unprocessable entity

Example

POST /api/rest/v1/orders/123e4567-e89b-12d3-a456-426655440000/permissions
Host: orders-repository.system.trans.eu
Accept: application/hal+json
Authorization: Bearer {access_token}

{
  "companies": [
    {
      "id": 12
    },
    {
      "id": 56
    }
  ]
}

Revoke access to edit order for other companies

Endpoint

DELETE /orders/{ID}/permissions

Request body data

Field	Type	Required
companies	Array(of CompanyId)	true

Responses

Http status	Description
204	Revoked access
403	Forbidden
404	Access has not been granted

Example

DELETE /api/rest/v1/orders/123e4567-e89b-12d3-a456-426655440000/permissions
Host: orders-repository.system.trans.eu
Accept: application/hal+json
Authorization: Bearer {access_token}

{
  "companies": [
    {
      "id": 12
    },
    {
      "id": 56
    }
  ]
}

Menu

Resources

Orders

Create order

Get order

Update order

Delete order

Permissions

Grant access to edit order for other companies

Revoke access to edit order for other companies