Menu

Page content

TransAPI Business use cases

During reading use cases below, please be aware that some of them may contain only partial requests.

Due to fact, that complete requests and responses are very long in many cases they were trimmed down to what's really important in given use case.

For complete request and response information please take refer to Offers API specification

1. Adding a load offer based on an order in external system

Scenario

  • User of a system being integrated with Trans.eu platform (external system) receives a contract to transport a load, but doesn't have a contract with a transport company or doesn't have any vehicle available,
  • the user adds the load offer in Trans.eu based on existing offer in external system,
  • person or company interested in transport execution contacts owner of the offer.

HTTP Request

POST /api/rest/v1/loads HTTP/1.1
Content-Type: application/hal+json
Accept: application/hal+json
Authorization: Bearer {access_token}
Host: offers.system.trans.eu

{
  "load_weight": {
    "value": 9.65,
    "unit_code": "TNE"
  },
  "loading_place": {
    "address": {
      "country": "PL",
      "locality": "Warszawa",
      "postal_code": "00-125"
    }
  },
  "required_truck_body": {
    "id": "tent"
  },
  "loading_date": "2015-10-22T14:57:56+00:00",
  "unloading_date" : "2015-10-23T14:59:56+00:00",
  "unloading_place": {
    "address": {
      "country": "PL",
      "locality": "Wrocław",
      "postal_code": "53-307"
    }
  },
  "price": 4.11,
  "price_currency": "PLN"
}

Expected response body:

HTTP/1.1 201 Created
Content-Type: application/hal+json

{
  "id": 123456789,
  "creation_date": "2015-10-21T08:54:23+0000",
  "publication_date": null,
  "finish_date": "2015-10-23T14:59:56+0000",
  "loading_place": {
    "address": {
      "country": "PL",
      "postal_code": "00-125",
      "locality": "Warszawa"
    },
    "geo": {
      "latitude": null,
      "longitude": null
    }
  },
  "loading_date": "2015-10-22T14:57:56+0000",
  "unloading_place": {
    "address": {
      "country": "PL",
      "postal_code": "53-307",
      "locality": "Wrocław"
    },
    "geo": {
      "latitude": null,
      "longitude": null
    }
  },
  "unloading_date": "2015-10-23T14:59:56+0000",
  "price": 4.11,
  "price_currency": "PLN",
  "description": null,
  "type": "public",
  "load_length": {
    "unit_code": null,
    "value": null
  },
  "load_height": {
    "unit_code": null,
    "value": null
  },
  "load_volume": {
    "unit_code": null,
    "value": null
  },
  "load_weight": {
    "unit_code": "TNE",
    "value": 9.65
  },
  "pallets": null,
  "is_ltl": null,
  "is_lift_required": null,
  "is_truck_crane_required": null,
  "is_tir_cable_required": null,
  "is_tracking_system_required": null,
  "is_for_clearance": null,
  "required_ways_of_loading": null,
  "required_adr_classes": null,
  "_links": {
    "self": {
      "href": "https://offers.system.trans.eu/api/rest/v1/loads/GENERATED_ID"
    },
    "offerer": {
      "id": 1031652,
      "href": "https://companies.system.trans.eu/api/rest/v1/employees/1031652"
    },
    "company": {
      "id": 10,
      "href": "https://companies.system.trans.eu/api/rest/v1/companies/10"
    },
    "contact_persons": {
      "ids": [
        1031652
      ],
      "href": "https://companies.system.trans.eu/api/rest/v1/employees?filter={"id":[1031652]}"
    },
    "required_truck_body": {
      "id": "tent",
      "href": "https://offers.system.trans.eu/api/rest/v1/truck-bodies/tent"
    }
  }
}

2. Search offers with free vehicle to complete order in external system

  • User of a system being integrated with Trans.eu platform (external system) receives a contract to transport a load, but he doesn't have a contract with a transport company or doesn't have any vehicle available,
  • User performs search for vehicles in Trans.eu based on offer existing in external system,
  • user receives list of vehicles offers meeting his search criteria and can browse details of each offer.

Available filters

Endpoint: https://offers.system.trans.eu/api/rest/v1/vehicles?filter={json_filter}

  • Locality
{
   "loading_place":{
      "address":{
         "locality":"Warszawa"
      }
   },
   "unloading_place":{
      "address":{
         "locality":"Wrocław"
      },
      "required_truck_body":{
         "id":"tent"
      },
      "cargo_space_capacity":{
         "$gt":0.965
      }
   }
}
  • Circle area (latitude, longitude)
{
   "circle_area":{
      "start":{
         "latitude":"52,2296756",
         "longitude":"21,0122287",
         "distance":10000
      },
      "end":{
         "latitude":"51,108142",
         "longitude":"17,037338",
         "distance":10000
      }
   },
   "required_truck_body":{
      "id":"tent"
   },
   "cargo_space_capacity":{
      "$gt":0.965
   }
}

HTTP Request

GET /api/rest/v1/vehicles?filter={json_filter} HTTP/1.1
Content-Type: application/hal+json
Accept: application/hal+json
Authorization: Bearer {access_token}
Host: offers.system.trans.eu

Response body:

HTTP/1.1 201 Created
Content-Type: application/hal+json

{
  "_links": {
    "self": {
      "href": "https://offers.system.trans.eu/api/rest/v1/vehicles?filter={"circle_area":{"start":{"latitude":"52,2296756","longitude":"21,0122287","distance":10000},"end":{"latitude":"51,108142","longitude":"17,037338","distance":10000}},"required_truck_body":{"id":"tent"},"cargo_space_capacity":{"$gt":0.965}}&page=1"
    },
    "first": {
      "href": "https://offers.system.trans.eu/api/rest/v1/vehicles?filter={"circle_area":{"start":{"latitude":"52,2296756","longitude":"21,0122287","distance":10000},"end":{"latitude":"51,108142","longitude":"17,037338","distance":10000}},"required_truck_body":{"id":"tent"},"cargo_space_capacity":{"$gt":0.965}}"
    },
    "last": {
      "href": "https://offers.system.trans.eu/api/rest/v1/vehicles?filter={"circle_area":{"start":{"latitude":"52,2296756","longitude":"21,0122287","distance":10000},"end":{"latitude":"51,108142","longitude":"17,037338","distance":10000}},"required_truck_body":{"id":"tent"},"cargo_space_capacity":{"$gt":0.965}}&page=1"
    }
  },
  "_embedded": {
    "vehicles": [
      {
        "id": 396343484,
        "creation_date": "2015-10-05T08:24:58 0000",
        "publication_date": null,
        "finish_date": "2015-10-06T15:00:00 0000",
        "loading_place": {
          "address": {
            "country": "PL",
            "postal_code": "00-001",
            "locality": "Warszawa"
          },
          "geo": {
            "latitude": 52.2445,
            "longitude": 21.0291
          }
        },
        "loading_date": "2015-10-05T09:00:00 0000",
        "unloading_place": {
          "address": {
            "country": "PL",
            "postal_code": "50-001",
            "locality": "Wrocław"
          },
          "geo": {
            "latitude": 51.1194,
            "longitude": 17.028
          }
        },
        "unloading_date": "2015-10-06T15:00:00 0000",
        "price": 0,
        "price_currency": "EUR",
        "description": "16/17ep paleciak",
        "type": "public",
        "cargo_space_capacity": {
          "value": 6.5,
          "unit_code": "TNE"
        },
        "cargo_space_length": {
          "value": 7,
          "unit_code": "MTR"
        },
        "cargo_space_height": {
          "value": 2.4,
          "unit_code": "MTR"
        },
        "cargo_space_volume": {
          "value": null,
          "unit_code": null
        },
        "ltl_available": false,
        "has_adr": false,
        "has_lift": true,
        "has_truck_crane": false,
        "has_tir_cable": false,
        "has_tir_carnet": false,
        "has_pallet_bin": false,
        "has_tracking_system": false,
        "available_ways_of_loading": [
          "side",
          "back"
        ],
        "_embedded": {
          "start_distance": {
            "id": "0.911839,0.367027-0.911579806469,0.366732573997",
            "value": 2012.332764,
            "unit_code": "MTR",
            "_links": {
              "self": {
                "href": "https://offers.system.trans.eu/api/rest/v1/distances/0.911839,0.367027-0.911579806469,0.366732573997"
              }
            }
          },
          "end_distance": {
            "id": "0.892202,0.297195-0.892005352477,0.297357643875",
            "value": 1411.531616,
            "unit_code": "MTR",
            "_links": {
              "self": {
                "href": "https://offers.system.trans.eu/api/rest/v1/distances/0.892202,0.297195-0.892005352477,0.297357643875"
              }
            }
          }
        },
        "_links": {
          "self": {
            "href": "https://offers.system.trans.eu/api/rest/v1/vehicles/396343484"
          },
          "offerer": {
            "id": 1089919,
            "href": "https://companies.system.trans.eu/api/rest/v1/employees/1089919"
          },
          "company": {
            "id": 648761,
            "href": "https://companies.system.trans.eu/api/rest/v1/companies/648761"
          },
          "contact_persons": {
            "ids": [
              1089919
            ],
            "href": "https://companies.system.trans.eu/api/rest/v1/employees?filter={"id":[1089919]}"
          },
          "truck_body": {
            "id": "tent",
            "href": "https://offers.system.trans.eu/api/rest/v1/truck-bodies/tent"
          }
        }
      },
    ]
  },
  "page_count": 1,
  "page_size": 20,
  "total_items": 3
}

3. Find load offers for driver with empty vehicle on a way back based on order in external system

  • User of a system being integrated with Trans.eu platform (external system) knows that chosen vehicle will drive a route from Warsaw to Berlin,
  • User doesn't have a contract for load transit on the way back,
  • Based on the original order and the vehicle, user wants to search for a load offer with loading location near Berlin and unloading location near Warsaw.

Available filters

URL https://offers.system.trans.eu/api/rest/v1/loads?filter={json_filter}

  • Circle area (latitude, longitude):
{
    "circle_area":{
        "start":{
            "latitude":"52,5234051",
            "longitude":"13,4113999",
            "distance":25000
        },
        "end":{
            "latitude":"52,2296756",
            "longitude":"21,0122287",
            "distance":25000
        }
    }
}

HTTP Request

GET /api/rest/v1/loads?filter={json_filter} HTTP/1.1
Accept: application/hal+json
Content-Type: application/hal+json
Authorization: Bearer {access_token}
Host: offers.system.trans.eu

Expected response body:

{
  "_links": {
    "self": {
      "href": "https://offers.system.trans.eu/api/rest/v1/loads?filter={"circle_area":{"start":{"latitude":"52,5234051","longitude":"13,4113999","distance":25000},"end":{"latitude":"52,2296756","longitude":"21,0122287","distance":25000}}}&page=1"
    },
    "first": {
      "href": "https://offers.system.trans.eu/api/rest/v1/loads?filter={"circle_area":{"start":{"latitude":"52,5234051","longitude":"13,4113999","distance":25000},"end":{"latitude":"52,2296756","longitude":"21,0122287","distance":25000}}}"
    },
    "last": {
      "href": "https://offers.system.trans.eu/api/rest/v1/loads?filter={"circle_area":{"start":{"latitude":"52,5234051","longitude":"13,4113999","distance":25000},"end":{"latitude":"52,2296756","longitude":"21,0122287","distance":25000}}}&page=1"
    }
  },
  "_embedded": {
    "loads": [
      {
        "id": 396399892,
        "creation_date": "2015-10-05T09:19:22 0000",
        "publication_date": null,
        "finish_date": "2015-10-07T16:00:00 0000",
        "loading_place": {
          "address": {
            "country": "DE",
            "postal_code": "10245",
            "locality": "Berlin"
          },
          "geo": {
            "latitude": 52.5011,
            "longitude": 13.4557
          }
        },
        "loading_date": "2015-10-06T10:00:00 0000",
        "unloading_place": {
          "address": {
            "country": "PL",
            "postal_code": "00-002",
            "locality": "Warszawa"
          },
          "geo": {
            "latitude": 52.2355,
            "longitude": 21.0102
          }
        },
        "unloading_date": "2015-10-07T16:00:00 0000",
        "price": 440,
        "price_currency": "EUR",
        "description": "",
        "type": "public",
        "load_length": {
          "value": 15.4,
          "unit_code": "MTR"
        },
        "load_height": {
          "value": 2.8,
          "unit_code": "MTR"
        },
        "load_volume": {
          "value": null,
          "unit_code": null
        },
        "load_weight": {
          "value": 10.5,
          "unit_code": "TNE"
        },
        "pallets": null,
        "is_ltl": false,
        "is_lift_required": false,
        "is_truck_crane_required": false,
        "is_tir_cable_required": false,
        "is_tracking_system_required": false,
        "is_for_clearance": false,
        "required_ways_of_loading": [
          "side"
        ],
        "required_adr_classes": null,
        "_embedded": {
          "start_distance": {
            "id": "0.916317,0.234846-0.916706353354,0.234073085557",
            "value": 3899.559814,
            "unit_code": "MTR",
            "_links": {
              "self": {
                "href": "https://offers.system.trans.eu/api/rest/v1/distances/0.916317,0.234846-0.916706353354,0.234073085557"
              }
            }
          },
          "end_distance": {
            "id": "0.911681,0.366698-0.911579806469,0.366732573997",
            "value": 656.973145,
            "unit_code": "MTR",
            "_links": {
              "self": {
                "href": "https://offers.system.trans.eu/api/rest/v1/distances/0.911681,0.366698-0.911579806469,0.366732573997"
              }
            }
          }
        },
        "_links": {
          "self": {
            "href": "https://offers.system.trans.eu/api/rest/v1/loads/396399892"
          },
          "offerer": {
            "id": 950308,
            "href": "https://companies.system.trans.eu/api/rest/v1/employees/950308"
          },
          "company": {
            "id": 91299,
            "href": "https://companies.system.trans.eu/api/rest/v1/companies/91299"
          },
          "contact_persons": {
            "ids": [
              950308
            ],
            "href": "https://companies.system.trans.eu/api/rest/v1/employees?filter={"id":[950308]}"
          },
          "required_truck_body": {
            "id": "jumbo",
            "href": "https://offers.system.trans.eu/api/rest/v1/truck-bodies/jumbo"
          }
        }
      },
    ]
  },
  "page_count": 1,
  "page_size": 20,
  "total_items": 1
}

4. Adding vehicle offer

  • User of a system being integrated with Trans.eu platform (external system) vehicle is not involved in any load transport at this moment,
  • user adds an offer of free vehicle in Trans.eu offers exchange,
  • person or company interested in that offer contacts user.

HTTP Request

POST /api/rest/v1/vehicles HTTP/1.1
Accept: application/hal+json
Content-Type: application/hal+json
Authorization: Bearer {access_token}
Host: offers.system.trans.eu

{
  "cargo_space_capacity": {
    "value": 9.65,
    "unit_code": "TNE"
  },
  "loading_place": {
    "address": {
      "country": "PL",
      "locality": "Warszawa",
      "postal_code": "00-125"
    }
  },
  "truck_body": {
    "id": "tent"
  },
  "loading_date": "2015-10-22T14:57:56+00:00",
  "unloading_date" : "2015-10-23T14:59:56+00:00",
  "unloading_place": {
    "address": {
      "country": "PL",
      "locality": "Wrocław",
      "postal_code": "53-307"
    }
  }
}

Response body:

{
  "id": 123456789,
  "creation_date": "2015-10-21T12:08:01 0000",
  "publication_date": null,
  "finish_date": "2015-10-23T14:59:56 0000",
  "loading_place": {
    "address": {
      "country": "PL",
      "postal_code": "00-125",
      "locality": "Warszawa"
    },
    "geo": {
      "latitude": null,
      "longitude": null
    }
  },
  "loading_date": "2015-10-22T14:57:56 0000",
  "unloading_place": {
    "address": {
      "country": "PL",
      "postal_code": "53-307",
      "locality": "Wrocław"
    },
    "address": {
      "country": "PL",
      "postal_code": "53-307",
      "locality": "Wrocław"
    },
    "geo": {
      "latitude": null,
      "longitude": null
    }
  },
  "unloading_date": "2015-10-23T14:59:56 0000",
  "price": null,
  "price_currency": null,
  "description": null,
  "type": "public",
  "cargo_space_capacity": {
    "unit_code": "TNE",
    "value": 9.65
  },
  "cargo_space_length": null,
  "cargo_space_height": null,
  "cargo_space_volume": null,
  "ltl_available": null,
  "has_adr": null,
  "has_lift": null,
  "has_truck_crane": null,
  "has_tir_cable": null,
  "has_tir_carnet": null,
  "has_pallet_bin": null,
  "has_tracking_system": null,
  "available_ways_of_loading": [],
  "_links": {
    "self": {
      "href": "http://offers.dev-trans.rst.com.pl/api/rest/v1/vehicles/GENERATED_ID"
    },
    "company": {
      "id": 10,
      "href": "http://companies.dev-trans.rst.com.pl/api/rest/v1/companies/10"
    },
    "offerer": {
      "id": 1031652,
      "href": "http://companies.dev-trans.rst.com.pl/api/rest/v1/employees/1031652"
    },
    "truck_body": {
      "id": "tent",
      "href": "http://offers.dev-trans.rst.com.pl/api/rest/v1/truck-bodies/tent"
    },
    "contact_persons": {
      "ids": [
        1031652
      ],
      "href": "http://companies.dev-trans.rst.com.pl/api/rest/v1/employees?filter={"id":[1031652]}"
    }
  }
}

5. Search additional loading during transit

  • User of a system being integrated with Trans.eu platform (external system) vehicle will perform load transit from Warsaw to Berlin,
  • the vehicle has some free loading space left,
  • user wants to search for load offers matching available space at points along the vehicles route,
  • user receives list of matching load offers.

Available filters

URL with circle area (latitude, longitude): https://offers.system.trans.eu/api/rest/v1/loads?filter={json_filter}

  • Circle area
{
    "circle_area": {
        "start": {
            "latitude":"52,2296756",
            "longitude":"21,0122287",
            "distance":25000
        },
        "end": {
            "latitude":"52,5234051",
            "longitude":"13,4113999",
            "distance":25000
        }
    }
}

HTTP Request

GET /api/rest/v1/loads?filter={json_filter}
Accept: application/hal+json
Content-Type: application/hal+json
Authorization: Bearer {access_token}
Host: offers.system.trans.eu

Response body:

{
  "_links": {
    "self": {
      "href": "https://offers.system.trans.eu/api/rest/v1/loads?filter={"circle_area":{"start":{"latitude":"52,2296756","longitude":"21,0122287","distance":25000},"end":{"latitude":"52,5234051","longitude":"13,4113999","distance":25000}}}&page=1"
    },
    "first": {
      "href": "https://offers.system.trans.eu/api/rest/v1/loads?filter={"circle_area":{"start":{"latitude":"52,2296756","longitude":"21,0122287","distance":25000},"end":{"latitude":"52,5234051","longitude":"13,4113999","distance":25000}}}"
    },
    "last": {
      "href": "https://offers.system.trans.eu/api/rest/v1/loads?filter={"circle_area":{"start":{"latitude":"52,2296756","longitude":"21,0122287","distance":25000},"end":{"latitude":"52,5234051","longitude":"13,4113999","distance":25000}}}&page=1"
    }
  },
  "_embedded": {
    "loads": [
      {
        "id": 396504956,
        "creation_date": "2015-10-05T11:14:21 0000",
        "publication_date": null,
        "finish_date": "2015-10-06T18:00:00 0000",
        "loading_place": {
          "address": {
            "country": "PL",
            "postal_code": "00-693",
            "locality": "Warszawa"
          },
          "geo": {
            "latitude": 52.2298,
            "longitude": 21.0118
          }
        },
        "loading_date": "2015-10-05T12:00:00 0000",
        "unloading_place": {
          "address": {
            "country": "DE",
            "postal_code": "14050",
            "locality": "Charlottenburg"
          },
          "geo": {
            "latitude": 52.519,
            "longitude": 13.313
          }
        },
        "unloading_date": "2015-10-06T18:00:00 0000",
        "price": 0,
        "price_currency": "PLN",
        "description": "",
        "type": "public",
        "load_length": {
          "value": null,
          "unit_code": null
        },
        "load_height": {
          "value": null,
          "unit_code": null
        },
        "load_volume": {
          "value": null,
          "unit_code": null
        },
        "load_weight": {
          "value": 24,
          "unit_code": "TNE"
        },
        "pallets": null,
        "is_ltl": false,
        "is_lift_required": false,
        "is_truck_crane_required": false,
        "is_tir_cable_required": false,
        "is_tracking_system_required": false,
        "is_for_clearance": false,
        "required_ways_of_loading": null,
        "required_adr_classes": null,
        "_embedded": {
          "start_distance": {
            "id": "0.911581,0.366725-0.911579806469,0.366732573997",
            "value": 32.412907,
            "unit_code": "MTR",
            "_links": {
              "self": {
                "href": "https://offers.system.trans.eu/api/rest/v1/distances/0.911581,0.366725-0.911579806469,0.366732573997"
              }
            }
          },
          "end_distance": {
            "id": "0.916629,0.232356-0.916706353354,0.234073085557",
            "value": 6697.331055,
            "unit_code": "MTR",
            "_links": {
              "self": {
                "href": "https://offers.system.trans.eu/api/rest/v1/distances/0.916629,0.232356-0.916706353354,0.234073085557"
              }
            }
          }
        },
        "_links": {
          "self": {
            "href": "https://offers.system.trans.eu/api/rest/v1/loads/396504956"
          },
          "offerer": {
            "id": 459880,
            "href": "https://companies.system.trans.eu/api/rest/v1/employees/459880"
          },
          "company": {
            "id": 244310,
            "href": "https://companies.system.trans.eu/api/rest/v1/companies/244310"
          },
          "contact_persons": {
            "ids": [
              459880
            ],
            "href": "https://companies.system.trans.eu/api/rest/v1/employees?filter={"id":[459880]}"
          },
          "required_truck_body": {
            "id": "tent",
            "href": "https://offers.system.trans.eu/api/rest/v1/truck-bodies/tent"
          }
        }
      },
      ]
  },
  "page_count": 1,
  "page_size": 20,
  "total_items": 1
}

6. Malfunction of vehicle executing transit. Search for vehicle offers in the area, which can replace it

  • User of a system being integrated with Trans.eu platform (external system) vehicle executes load transit from Warsaw to Berlin,
  • During transit vehicle breaks,
  • User wants to search for matching vehicle offer,
  • User is able to browse matching vehicle offers details.

Available filters

URL with circle area (latitude, longitude): https://offers.system.trans.eu/api/rest/v1/vehicles?filter={json_filter}

  • Circle area
{
    "circle_area":{
        "start":{
            "latitude":"52,2296756",
            "longitude":"21,0122287",
            "distance":25000
        },
        "end":{
            "latitude":"52,5234051",
            "longitude":"13,4113999",
            "distance":25000
        }
    }
}

HTTP Request

GET /api/rest/v1/vehicles?filter={json_filter}
Accept: application/hal+json
Content-Type: application/hal+json
Authorization: Bearer {access_token}
Host: offers.system.trans.eu

Response body:

{
  "_links": {
    "self": {
      "href": "https://offers.system.trans.eu/api/rest/v1/vehicles?filter={"circle_area":{"start":{"latitude":"52,2296756","longitude":"21,0122287","distance":25000},"end":{"latitude":"52,5234051","longitude":"13,4113999","distance":25000}}}&page=1"
    },
    "first": {
      "href": "https://offers.system.trans.eu/api/rest/v1/vehicles?filter={"circle_area":{"start":{"latitude":"52,2296756","longitude":"21,0122287","distance":25000},"end":{"latitude":"52,5234051","longitude":"13,4113999","distance":25000}}}"
    },
    "last": {
      "href": "https://offers.system.trans.eu/api/rest/v1/vehicles?filter={"circle_area":{"start":{"latitude":"52,2296756","longitude":"21,0122287","distance":25000},"end":{"latitude":"52,5234051","longitude":"13,4113999","distance":25000}}}&page=1"
    }
  },
  "_embedded": {
    "vehicles": [
      {
        "id": 396045311,
        "creation_date": "2015-10-02T12:12:08 0000",
        "publication_date": null,
        "finish_date": "2015-10-05T19:00:00 0000",
        "loading_place": {
          "address": {
            "country": "PL",
            "postal_code": "00-001",
            "locality": "Warszawa"
          },
          "geo": {
            "latitude": 52.2445,
            "longitude": 21.0291
          }
        },
        "loading_date": "2015-10-03T13:00:00 0000",
        "unloading_place": {
          "address": {
            "country": "DE",
            "postal_code": "12043",
            "locality": "Berlin"
          },
          "geo": {
            "latitude": 52.4763,
            "longitude": 13.4458
          }
        },
        "unloading_date": "2015-10-05T19:00:00 0000",
        "price": 0,
        "price_currency": "PLN",
        "description": "",
        "type": "public",
        "cargo_space_capacity": {
          "value": 24,
          "unit_code": "TNE"
        },
        "cargo_space_length": {
          "value": null,
          "unit_code": null
        },
        "cargo_space_height": {
          "value": null,
          "unit_code": null
        },
        "cargo_space_volume": {
          "value": null,
          "unit_code": null
        },
        "ltl_available": false,
        "has_adr": true,
        "has_lift": false,
        "has_truck_crane": false,
        "has_tir_cable": false,
        "has_tir_carnet": false,
        "has_pallet_bin": false,
        "has_tracking_system": false,
        "available_ways_of_loading": null,
        "_embedded": {
          "start_distance": {
            "id": "0.911839,0.367027-0.911579806469,0.366732573997",
            "value": 2012.332764,
            "unit_code": "MTR",
            "_links": {
              "self": {
                "href": "https://offers.system.trans.eu/api/rest/v1/distances/0.911839,0.367027-0.911579806469,0.366732573997"
              }
            }
          },
          "end_distance": {
            "id": "0.915884,0.234673-0.916706353354,0.234073085557",
            "value": 5738.689453,
            "unit_code": "MTR",
            "_links": {
              "self": {
                "href": "https://offers.system.trans.eu/api/rest/v1/distances/0.915884,0.234673-0.916706353354,0.234073085557"
              }
            }
          }
        },
        "_links": {
          "self": {
            "href": "https://offers.system.trans.eu/api/rest/v1/vehicles/396045311"
          },
          "offerer": {
            "id": 402308,
            "href": "https://companies.system.trans.eu/api/rest/v1/employees/402308"
          },
          "company": {
            "id": 228588,
            "href": "https://companies.system.trans.eu/api/rest/v1/companies/228588"
          },
          "contact_persons": {
            "ids": [
              402308
            ],
            "href": "https://companies.system.trans.eu/api/rest/v1/employees?filter={"id":[402308]}"
          },
          "truck_body": {
            "id": "tent",
            "href": "https://offers.system.trans.eu/api/rest/v1/truck-bodies/tent"
          }
        }
      },
    ]
  },
  "page_count": 1,
  "page_size": 20,
  "total_items": 3
}

7. Additional transport offer on route

  • User of a system being integrated with Trans.eu platform (external system) has a vehicle executing transport, but not all cargo space is used,
  • User adds single vehicle offer as a number of vehicle offers in Trans.eu platform with different cities placed on route to fill available cargo space,
  • Person or company interested in vehicle offer contacts user using contact data provided,
  • Each of load offers is deleted from Trans.eu platform by external system.

Offer 1

HTTP Request

POST /api/rest/v1/vehicles HTTP/1.1
Content-Type: application/hal+json
Accept: application/hal+json
Authorization: Bearer {access_token}
Host: offers.system.trans.eu

{
  "loading_place": {
    "address": {
      "country": "PL",
      "postal_code": "80-858",
      "locality": "Gdańsk"
    },
  },
  "loading_date": "2016-03-07T07:00:00+0000",
  "unloading_place": {
    "address": {
      "country": "PL",
      "postal_code": "02-495",
      "locality": "Warszawa"
    },
  },
  "unloading_date": "2016-03-09T07:00:00+0000"
}

HTTP Response

HTTP/1.1 201 Created
Content-Type: application/hal+json

{
  "id": 123456789
}

Offer 2

HTTP Request

POST /api/rest/v1/vehicles HTTP/1.1
Content-Type: application/hal+json
Accept: application/hal+json
Authorization: Bearer {access_token}
Host: offers.system.trans.eu

{
  "loading_place": {
    "address": {
      "country": "PL",
      "postal_code": "83-322",
      "locality": "Malbork"
    },
  },
  "loading_date": "2016-03-07T07:00:00+0000",
  "unloading_place": {
    "address": {
      "country": "PL",
      "postal_code": "02-495",
      "locality": "Warszawa"
    },
  },
  "unloading_date": "2016-03-09T07:00:00+0000"
}

HTTP Response

HTTP/1.1 201 Created
Content-Type: application/hal+json

{
  "id": 123456790
}

Offer 3

HTTP Request

POST /api/rest/v1/vehicles HTTP/1.1
Content-Type: application/hal+json
Accept: application/hal+json
Authorization: Bearer {access_token}
Host: offers.system.trans.eu

{
  "loading_place": {
    "address": {
      "country": "PL",
      "postal_code": "06-500",
      "locality": "Mława"
    },
  },
  "loading_date": "2016-03-07T07:00:00+0000",
  "unloading_place": {
    "address": {
      "country": "PL",
      "postal_code": "02-495",
      "locality": "Warszawa"
    },
  },
  "unloading_date": "2016-03-09T07:00:00+0000"
}

HTTP Response

HTTP/1.1 201 Created
Content-Type: application/hal+json

{
  "id": 123456791
}

8. Finding specific vehicle offer type

  • User of a system being integrated with Trans.eu platform (external system) receives a contract to transport a hazardous load, but doesn't have contact with proper transport company or doesn't have any vehicle available with ADR license,
  • User adds the load offer in Trans.eu based on existing offer in external system,
  • Person or company interested in transport execution contacts user,
  • When offer is accepted, it is removed from Trans.eu platform by external system.

HTTP Request

POST /api/rest/v1/loads HTTP/1.1
Content-Type: application/hal+json
Accept: application/hal+json
Authorization: Bearer {access_token}
Host: offers.system.trans.eu

{
  "required_adr_classes": [ "1", "4.3", "5.2" ]
}

HTTP Response

HTTP/1.1 201 Created
Content-Type: application/hal+json

{
  "id": 123456791,
}

9. Several different types of truck body

  • User of a system being integrated with Trans.eu platform (external system) wants to offer an available vehicle with 'mega' body,
  • External system posts several vehicle offers with different truck body types corresponding to 'mega' body type ('curtainsider', 'tent' and 'colimulde')
  • Person or company interested in using given vehicle contacts user,
  • When offer is accepted, all vehicle offers are removed by external system.

Offer 1

HTTP Request

POST /api/rest/v1/loads HTTP/1.1
Content-Type: application/hal+json
Accept: application/hal+json
Authorization: Bearer {access_token}
Host: offers.system.trans.eu

{
 "required_truck_body" : {
    "id": "curtainsider"
  },
}

HTTP Response

HTTP/1.1 201 Created
Content-Type: application/hal+json

{
  "id": 123456791,
}

Offer 2

HTTP Request

POST /api/rest/v1/loads HTTP/1.1
Content-Type: application/hal+json
Accept: application/hal+json
Authorization: Bearer {access_token}
Host: offers.system.trans.eu

{
 "required_truck_body" : {
    "id": "tent"
  },
}

HTTP Response

HTTP/1.1 201 Created
Content-Type: application/hal+json

{
  "id": 123456791,
}

Offer 3

HTTP Request

POST /api/rest/v1/loads HTTP/1.1
Content-Type: application/hal+json
Accept: application/hal+json
Authorization: Bearer {access_token}
Host: offers.system.trans.eu

{
 "required_truck_body" : {
    "id": "coilmulde"
  },
}

HTTP Response

HTTP/1.1 201 Created
Content-Type: application/hal+json

{
  "id": 123456791,
}

10. Adding load offers within cluster

  • User of a system being integrated with Trans.eu platform (external system) wants wants to offer load for transporting to trusted company,
  • User is a employee of company being a member of transport cluster in Trans.eu System
  • Load transport offer is added within cluster
  • Person or company belonging to the same cluster as offer was added is able to contact user using contact data provided.

HTTP Request

POST /api/rest/v1/loads HTTP/1.1
Content-Type: application/hal+json
Accept: application/hal+json
Authorization: Bearer {access_token}
Host: offers.system.trans.eu

{
  "load_weight": {
    "value":12.00,
    "unit_code": "TNE"
  },
  "loading_place": {
    "address": {
      "country": "PL",
      "locality": "Warszawa",
      "postal_code": "00-125"
    }
  },
  "required_truck_body": {
    "id": "tent"
  },
  "loading_date": "2015-10-22T14:57:56+00:00",
  "unloading_date" : "2015-10-23T14:59:56+00:00",
  "unloading_place": {
    "address": {
      "country": "PL",
      "locality": "Wrocław",
      "postal_code": "53-307"
    }
  },
  "type": "cluster",
    "clusters" : [
      { "id": 10192}
    ]
}

HTTP Response

HTTP/1.1 201 Created
Content-Type: application/hal+json

{
  "id": 123456791,
}

11. Find contractor data from transaction based on particular vehicle offer

  • User of a system being integrated with Trans.eu platform (external system) adds new vehicle offer using external system,
  • External system publishes vehicle offer via REST API integration with Trans.eu platform,
  • External system receives and stores response containing vehicle offer identifier,
  • Vehicle offer is accepted by both sides in Trans.eu exchange,
  • External system requests for transaction associated with previously stored vehicle offer identifier,
  • User of external system has now contractor data available within his system.

HTTP Request for finding collection of transactions:

GET /api/rest/v1/load-transactions/@company-offerer?filter={"offer":{"id":12345}} HTTP/1.1
Host: exchange-transactions.system.trans.eu
Accept: application/hal+json
Content-Type: application/hal+json
Authorization: Bearer {access_token}

Expected response body:

{
  "_links": {
    "self": {
      "href": "https://exchange-transactions.system.trans.eu/api/rest/v1/vehicle-transactions/@company-offerer?page=1"
    },
    "first": {
      "href": "https://exchange-transactions.system.trans.eu/api/rest/v1/vehicle-transactions/@company-offerer"
    },
    "last": {
      "href": "https://exchange-transactions.system.trans.eu/api/rest/v1/vehicle-transactions/@company-offerer?page=1"
    },
    "next": {
      "href": "https://exchange-transactions.system.trans.eu/api/rest/v1/vehicle-transactions/@company-offerer?page=1"
    }
  },
  "_embedded": {
    "vehicle_transactions": [
      {
        "id": "2b77a99c-3001-549f-a4b3-17d3e5740e7d",
        "creation_date": "2016-01-12T14:57:50+01:00",
        "_embedded": {
          "vehicle_offer": {
            "id": 12345,
            "creation_date": "2016-01-12T13:56:22+0000",
            "publication_date": null,
            "finish_date": "2016-01-13T20:00:00+0000",
            "loading_place": {
              "address": {
                "country": "PL",
                "postal_code": "12-345",
                "locality": "Brześce"
              },
              "geo": {
                "latitude": 11.0323,
                "longitude": 1.1813
              }
            },
            "loading_date": "2016-01-12T14:00:00+0000",
            "unloading_place": {
              "address": {
                "country": "PL",
                "postal_code": "12-345",
                "locality": "Człuchów"
              },
              "geo": {
                "latitude": 2.6672,
                "longitude": 3.3588
              }
            },
            "unloading_date": "2016-01-13T20:00:00+0000",
            "price": 0,
            "price_currency": "EUR",
            "price_in_euro": 0,
            "description": "",
            "type": "public",
            "cargo_space_capacity": {
              "value": 1,
              "unit_code": "TNE"
            },
            "cargo_space_length": {
              "value": null,
              "unit_code": null
            },
            "cargo_space_height": {
              "value": null,
              "unit_code": null
            },
            "cargo_space_volume": {
              "value": null,
              "unit_code": null
            },
            "ltl_available": false,
            "has_adr": false,
            "has_lift": false,
            "has_truck_crane": false,
            "has_tir_cable": false,
            "has_tir_carnet": false,
            "has_pallet_bin": false,
            "has_tracking_system": false,
            "available_ways_of_loading": [
              "side",
              "back"
            ],
            "_links": {
              "offerer": {
                "id": 5555,
                "href": "https://companies.system.trans.eu/api/rest/v1/employees/5555"
              },
              "company": {
                "id": 222,
                "href": "https://companies.system.trans.eu/api/rest/v1/companies/222"
              },
              "contact_persons": {
                "ids": [
                  5555
                ],
                "href": "https://companies.system.trans.eu/api/rest/v1/employees?filter=%7B%22id%22:%5B5555%5D%7D"
              },
              "truck_body": {
                "id": "van",
                "href": "https://offers.system.trans.eu/api/rest/v1/truck-bodies/van"
              }
            }
          },
          "offerer_company": {
            "id": 222,
            "legal_name": "Example company",
            "short_name": "Example",
            "native_name": null,
            "short_native_name": null,
            "email": "example@onet.pl",
            "address": {
              "postal_code": "45-1111",
              "locality": "Warszawa",
              "street_address": "ul Warszawska 100",
              "country": "PL"
            },
            "vat_id": "123456",
            "telephone": "(48) 123456789",
            "additional_telephones": null,
            "url": null,
            "registration_date": "2012-11-05T10:50:03+00:00",
            "fax_number": null,
            "company_number": "123456789",
            "registration_number": null,
            "establishment_date": "2012-07-31T22:00:00+00:00",
            "_links": {
              "self": {
                "href": "https://companies.system.trans.eu/api/rest/v1/companies/222"
              },
              "certificates": {
                "id": "222",
                "href": "https://company-certificates.system.trans.eu/api/rest/v1/companies/222/certifications"
              },
              "stats": {
                "href": "https://companies.system.trans.eu/api/rest/v1/companies/222/stats"
              },
              "ratings": {
                "href": "https://companies.system.trans.eu/api/rest/v1/companies/222/ratings"
              },
              "trans-risk": {
                "href": "https://companies.system.trans.eu/api/rest/v1/companies/222/trans-risk"
              },
              "structure": {
                "href": "https://companies.system.trans.eu/api/rest/v1/companies/222/structure"
              },
              "legal-forms": {
                "href": "https://companies.system.trans.eu/api/rest/v1/companies/222/legal-forms"
              },
              "services": {
                "href": "https://companies.system.trans.eu/api/rest/v1/companies/222/services"
              },
              "employees": {
                "href": "https://companies.system.trans.eu/api/rest/v1/companies/222/employees"
              }
            }
          },
          "offerer_employee": {
            "id": 5555,
            "given_name": "John",
            "family_name": "Doe",
            "trans_id": "123-123456",
            "email": "test@test.pl",
            "language": "PL",
            "telephone": null,
            "mobile_telephone": "(48) 531069683",
            "additional_telephones": null,
            "registration_date": "2015-11-05T10:50:03+00:00",
            "last_login_date": "2016-03-30T03:56:58+00:00",
            "entitled": true,
            "hidden": false,
            "is_driver": false,
            "is_moderator": false,
            "_links": {
              "self": {
                "href": "https://companies.system.trans.eu/api/rest/v1/employees/5555"
              },
              "company": {
                "href": "https://companies.system.trans.eu/api/rest/v1/companies/222"
              }
            }
          },
          "contractor_company": {
            "id": 444,
            "legal_name": "Example company 2",
            "short_name": "Example 2",
            "native_name": null,
            "short_native_name": null,
            "email": "info@trans.test",
            "address": {
              "postal_code": "12-212",
              "locality": "Warszawa",
              "street_address": "Transowa 4",
              "country": "PL"
            },
            "vat_id": "PL123456789",
            "telephone": "(48) 123456789",
            "additional_telephones": null,
            "url": "http://trans.eu",
            "registration_date": "2005-05-25T11:51:17+00:00",
            "fax_number": "123456789",
            "company_number": "123456789",
            "registration_number": "123456789",
            "establishment_date": "2003-04-30T22:00:00+00:00",
            "_links": {
              "self": {
                "href": "https://companies.system.trans.eu/api/rest/v1/companies/444"
              },
              "certificates": {
                "id": "444",
                "href": "https://company-certificates.system.trans.eu/api/rest/v1/companies/444/certifications"
              },
              "stats": {
                "href": "https://companies.system.trans.eu/api/rest/v1/companies/444/stats"
              },
              "ratings": {
                "href": "https://companies.system.trans.eu/api/rest/v1/companies/444/ratings"
              },
              "trans-risk": {
                "href": "https://companies.system.trans.eu/api/rest/v1/companies/444/trans-risk"
              },
              "structure": {
                "href": "https://companies.system.trans.eu/api/rest/v1/companies/444/structure"
              },
              "legal-forms": {
                "href": "https://companies.system.trans.eu/api/rest/v1/companies/444/legal-forms"
              },
              "services": {
                "href": "https://companies.system.trans.eu/api/rest/v1/companies/444/services"
              },
              "employees": {
                "href": "https://companies.system.trans.eu/api/rest/v1/companies/444/employees"
              }
            }
          },
          "contractor_employee": {
            "id": 11111,
            "given_name": "John",
            "family_name": "Doe",
            "trans_id": "444-121",
            "email": "info@trans.test",
            "language": "PL",
            "telephone": "(48) 123456789",
            "mobile_telephone": "(48) 123456789",
            "additional_telephones": null,
            "registration_date": "2008-03-23T18:48:07+00:00",
            "last_login_date": "2016-03-30T09:50:20+00:00",
            "entitled": false,
            "hidden": false,
            "is_driver": false,
            "is_moderator": false,
            "_links": {
              "self": {
                "href": "https://companies.system.trans.eu/api/rest/v1/employees/11111"
              },
              "company": {
                "href": "https://companies.system.trans.eu/api/rest/v1/companies/444"
              }
            }
          }
        },
        "_links": {
          "self": {
            "href": "https://exchange-transactions.system.trans.eu/api/rest/v1/vehicle-transactions/2b77a99c-3001-549f-a4b3-17d3e5740e7d"
          }
        }
      },
    ]
  },
  "page_count": 1,
  "page_size": 10,
  "total_items": 1,
  "page": 1
}

12. Listing transactions for vehicle offers published by company to search for contractors data

  • User of a system integrated with Trans.eu platform (external system) publishes offer using Trans communicator,
  • External system does not have offer identifier of that offer,
  • External system retrieves list of transactions concluded based on vehicle offers, where company was in the role of offerer,
  • User of external system can now browse the transaction list and search for information about contractors.

HTTP Request for finding collection of transactions:

GET /api/rest/v1/vehicle-transactions/@company-offerer HTTP/1.1
Host: exchange-transactions.system.trans.eu
Accept: application/hal+json
Content-Type: application/hal+json
Authorization: Bearer {access_token}

Expected response body:

{
  "_links": {
    "self": {
      "href": "https://exchange-transactions.system.trans.eu/api/rest/v1/vehicle-transactions/@company-offerer?page=1"
    },
    "first": {
      "href": "https://exchange-transactions.system.trans.eu/api/rest/v1/vehicle-transactions/@company-offerer"
    },
    "last": {
      "href": "https://exchange-transactions.system.trans.eu/api/rest/v1/vehicle-transactions/@company-offerer?page=1"
    },
    "next": {
      "href": "https://exchange-transactions.system.trans.eu/api/rest/v1/vehicle-transactions/@company-offerer?page=1"
    }
  },
  "_embedded": {
    "vehicle_transactions": [
      {
        "id": "2b77a99c-3001-549f-a4b3-17d3e5740e7d",
        "creation_date": "2016-01-12T14:57:50+01:00",
        "_embedded": {
          "vehicle_offer": {
            "id": 12345,
            "creation_date": "2016-01-12T13:56:22+0000",
            "publication_date": null,
            "finish_date": "2016-01-13T20:00:00+0000",
            "loading_place": {
              "address": {
                "country": "PL",
                "postal_code": "12-345",
                "locality": "Brześce"
              },
              "geo": {
                "latitude": 11.0323,
                "longitude": 1.1813
              }
            },
            "loading_date": "2016-01-12T14:00:00+0000",
            "unloading_place": {
              "address": {
                "country": "PL",
                "postal_code": "12-345",
                "locality": "Człuchów"
              },
              "geo": {
                "latitude": 2.6672,
                "longitude": 3.3588
              }
            },
            "unloading_date": "2016-01-13T20:00:00+0000",
            "price": 0,
            "price_currency": "EUR",
            "price_in_euro": 0,
            "description": "",
            "type": "public",
            "cargo_space_capacity": {
              "value": 1,
              "unit_code": "TNE"
            },
            "cargo_space_length": {
              "value": null,
              "unit_code": null
            },
            "cargo_space_height": {
              "value": null,
              "unit_code": null
            },
            "cargo_space_volume": {
              "value": null,
              "unit_code": null
            },
            "ltl_available": false,
            "has_adr": false,
            "has_lift": false,
            "has_truck_crane": false,
            "has_tir_cable": false,
            "has_tir_carnet": false,
            "has_pallet_bin": false,
            "has_tracking_system": false,
            "available_ways_of_loading": [
              "side",
              "back"
            ],
            "_links": {
              "offerer": {
                "id": 5555,
                "href": "https://companies.system.trans.eu/api/rest/v1/employees/5555"
              },
              "company": {
                "id": 222,
                "href": "https://companies.system.trans.eu/api/rest/v1/companies/222"
              },
              "contact_persons": {
                "ids": [
                  5555
                ],
                "href": "https://companies.system.trans.eu/api/rest/v1/employees?filter=%7B%22id%22:%5B5555%5D%7D"
              },
              "truck_body": {
                "id": "van",
                "href": "https://offers.system.trans.eu/api/rest/v1/truck-bodies/van"
              }
            }
          },
          "offerer_company": {
            "id": 222,
            "legal_name": "Example company",
            "short_name": "Example",
            "native_name": null,
            "short_native_name": null,
            "email": "example@onet.pl",
            "address": {
              "postal_code": "45-1111",
              "locality": "Warszawa",
              "street_address": "ul Warszawska 100",
              "country": "PL"
            },
            "vat_id": "123456",
            "telephone": "(48) 123456789",
            "additional_telephones": null,
            "url": null,
            "registration_date": "2012-11-05T10:50:03+00:00",
            "fax_number": null,
            "company_number": "123456789",
            "registration_number": null,
            "establishment_date": "2012-07-31T22:00:00+00:00",
            "_links": {
              "self": {
                "href": "https://companies.system.trans.eu/api/rest/v1/companies/222"
              },
              "certificates": {
                "id": "222",
                "href": "https://company-certificates.system.trans.eu/api/rest/v1/companies/222/certifications"
              },
              "stats": {
                "href": "https://companies.system.trans.eu/api/rest/v1/companies/222/stats"
              },
              "ratings": {
                "href": "https://companies.system.trans.eu/api/rest/v1/companies/222/ratings"
              },
              "trans-risk": {
                "href": "https://companies.system.trans.eu/api/rest/v1/companies/222/trans-risk"
              },
              "structure": {
                "href": "https://companies.system.trans.eu/api/rest/v1/companies/222/structure"
              },
              "legal-forms": {
                "href": "https://companies.system.trans.eu/api/rest/v1/companies/222/legal-forms"
              },
              "services": {
                "href": "https://companies.system.trans.eu/api/rest/v1/companies/222/services"
              },
              "employees": {
                "href": "https://companies.system.trans.eu/api/rest/v1/companies/222/employees"
              }
            }
          },
          "offerer_employee": {
            "id": 5555,
            "given_name": "John",
            "family_name": "Doe",
            "trans_id": "123-123456",
            "email": "test@test.pl",
            "language": "PL",
            "telephone": null,
            "mobile_telephone": "(48) 531069683",
            "additional_telephones": null,
            "registration_date": "2015-11-05T10:50:03+00:00",
            "last_login_date": "2016-03-30T03:56:58+00:00",
            "entitled": true,
            "hidden": false,
            "is_driver": false,
            "is_moderator": false,
            "_links": {
              "self": {
                "href": "https://companies.system.trans.eu/api/rest/v1/employees/5555"
              },
              "company": {
                "href": "https://companies.system.trans.eu/api/rest/v1/companies/222"
              }
            }
          },
          "contractor_company": {
            "id": 444,
            "legal_name": "Example company 2",
            "short_name": "Example 2",
            "native_name": null,
            "short_native_name": null,
            "email": "info@trans.test",
            "address": {
              "postal_code": "12-212",
              "locality": "Warszawa",
              "street_address": "Transowa 4",
              "country": "PL"
            },
            "vat_id": "PL123456789",
            "telephone": "(48) 123456789",
            "additional_telephones": null,
            "url": "http://trans.eu",
            "registration_date": "2005-05-25T11:51:17+00:00",
            "fax_number": "123456789",
            "company_number": "123456789",
            "registration_number": "123456789",
            "establishment_date": "2003-04-30T22:00:00+00:00",
            "_links": {
              "self": {
                "href": "https://companies.system.trans.eu/api/rest/v1/companies/444"
              },
              "certificates": {
                "id": "444",
                "href": "https://company-certificates.system.trans.eu/api/rest/v1/companies/444/certifications"
              },
              "stats": {
                "href": "https://companies.system.trans.eu/api/rest/v1/companies/444/stats"
              },
              "ratings": {
                "href": "https://companies.system.trans.eu/api/rest/v1/companies/444/ratings"
              },
              "trans-risk": {
                "href": "https://companies.system.trans.eu/api/rest/v1/companies/444/trans-risk"
              },
              "structure": {
                "href": "https://companies.system.trans.eu/api/rest/v1/companies/444/structure"
              },
              "legal-forms": {
                "href": "https://companies.system.trans.eu/api/rest/v1/companies/444/legal-forms"
              },
              "services": {
                "href": "https://companies.system.trans.eu/api/rest/v1/companies/444/services"
              },
              "employees": {
                "href": "https://companies.system.trans.eu/api/rest/v1/companies/444/employees"
              }
            }
          },
          "contractor_employee": {
            "id": 11111,
            "given_name": "John",
            "family_name": "Doe",
            "trans_id": "444-121",
            "email": "info@trans.test",
            "language": "PL",
            "telephone": "(48) 123456789",
            "mobile_telephone": "(48) 123456789",
            "additional_telephones": null,
            "registration_date": "2008-03-23T18:48:07+00:00",
            "last_login_date": "2016-03-30T09:50:20+00:00",
            "entitled": false,
            "hidden": false,
            "is_driver": false,
            "is_moderator": false,
            "_links": {
              "self": {
                "href": "https://companies.system.trans.eu/api/rest/v1/employees/11111"
              },
              "company": {
                "href": "https://companies.system.trans.eu/api/rest/v1/companies/444"
              }
            }
          }
        },
        "_links": {
          "self": {
            "href": "https://exchange-transactions.system.trans.eu/api/rest/v1/vehicle-transactions/2b77a99c-3001-549f-a4b3-17d3e5740e7d"
          }
        }
      },
    ]
  },
  "page_count": 2,
  "page_size": 10,
  "total_items": 1,
  "page": 1
}

13. Listing transactions for load offers published by other companies

  • User of a system integrated with Trans.eu platform (external system) accepts load offer published by other company within Trans.eu exchange,
  • User is employed by transport company, so all accepted transactions are based on load offers,
  • External system retrieves list of transactions concluded based on load offers, where company was in the role of contractor,
  • User of external system can now browse the transaction list and search information about offerers.

HTTP Request for finding collection of transactions:

GET /api/rest/v1/load-transactions/@company-contractor HTTP/1.1
Host: exchange-transactions.system.trans.eu
Accept: application/hal+json
Content-Type: application/hal+json
Authorization: Bearer {access_token}

Response will look analogously to previous exchange-transactions service responses.

14. Adding an order based on an order in external system

  • User of a system (i.e. "Jan Kowalski") integrated with Trans.eu platform (external system) has a contract with carrier (i.e. "Michał Nowak" from "Transport Company") concerning transporting a load.
  • User adds order based on existing order in external system. As a result he retrieves unique identifier of added order.
  • User can now use features provided by Orders module of Trans.eu system

HTTP Request for adding an order from external system

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

{
    "number": "DE/3455/4460",
    "payment": {
        "price": {
            "value": 34,
            "currency": "PLN"
        },
        "interval": "P10D"
    },
    "carrier": {
        "company": {
            "name": "Transport Company"
        },
        "contact_person": {
            "given_name": "Michał",
            "family_name": "Nowak",
            "email": "michal.nowak@transport-company.pl",
            "telephone": "(48) 313131313"
        }
    },
    "route" : {
        "events": [
            {
                "place": {
                    "address": {
                        "locality": "Berlin",
                        "postal_code": "3456",
                        "country": "DE"
                    }
                },
                "type": "loading"
            },
            {
                "place": {
                    "address": {
                        "locality": "Wysoka",
                        "postal_code": "12345",
                        "country": "PL"
                    }
                },
                "type": "unloading"
            }
        ]
    }
}

Expected HTTP Response

HTTP/1.1 201 Created
Content-Type: application/hal+json

{
    "id": "56acf700-1774-11e6-8ab6-0002a5d5c51b",
    "number": "DE/3455/4460",
    "payment": {
        "price": {
            "value": 34,
            "currency": "PLN"
        },
        "interval": "P10D"
    },
    "shipper": {
        "company": {
            "name": "Shipping Company",
            "vat_id": "PL0123456789",
            "address": {
                "locality": "Wrocław",
                "postal_code": "50-572",
                "country": "PL"
            }
        },
        "contact_person": {
            "given_name": "Jan",
            "family_name": "Kowalski",
            "email": "jan.kowalski@shipping-company.pl",
            "telephone": "(48) 111222333"
        }
    },
    "carrier": {
        "company": {
            "name": "Transport Company"
        },
        "contact_person": {
            "given_name": "Michał",
            "family_name": "Nowak",
            "email": "michal.nowak@transport-company.pl",
            "telephone": "(48) 313131313"
        }
    },
    "route" : {
        "events": [
            {
                "place": {
                    "address": {
                        "locality": "Berlin",
                        "postal_code": "3456",
                        "country": "DE"
                    }
                },
                "type": "loading"
            },
            {
                "place": {
                    "address": {
                        "locality": "Wysoka",
                        "postal_code": "12345",
                        "country": "PL"
                    }
                },
                "type": "unloading"
            }
        ]
    },
    "_links": {
        "self": {
            "href": "https://orders.system.trans.eu/api/rest/v1/orders/56acf700-1774-11e6-8ab6-0002a5d5c51b"
        }
    }
}

15. Retrieving order added from external system

  • User of a system (i.e. "Jan Kowalski") once added an order from external system to process it in Trans.eu system.
  • User wants to export processed order back to external system.
  • User gets the order data using its unique identifier.

HTTP Request for getting an order from Trans.eu system

GET /api/rest/v1/orders/56acf700-1774-11e6-8ab6-0002a5d5c51b HTTP/1.1
Host: orders.system.trans.eu
Accept: application/hal+json
Authorization: Bearer {access_token}

Expected HTTP Response

HTTP/1.1 200 OK
Content-Type: application/hal+json

{
    "id": "56acf700-1774-11e6-8ab6-0002a5d5c51b",
    "number": "DE/3455/4460",
    "payment": {
        "price": {
            "value": 34,
            "currency": "PLN"
        },
        "interval": "P10D"
    },
    "shipper": {
        "company": {
            "name": "Shipping Company",
            "vat_id": "PL0123456789",
            "address": {
                "locality": "Wrocław",
                "postal_code": "50-572",
                "country": "PL"
            }
        },
        "contact_person": {
            "given_name": "Jan",
            "family_name": "Kowalski",
            "email": "jan.kowalski@shipping-company.pl",
            "telephone": "(48) 111222333"
        }
    },
    "carrier": {
        "company": {
            "name": "Transport Company"
        },
        "contact_person": {
            "given_name": "Michał",
            "family_name": "Nowak",
            "email": "michal.nowak@transport-company.pl",
            "telephone": "(48) 313131313"
        }
    },
    "route" : {
        "events": [
            {
                "place": {
                    "address": {
                        "locality": "Berlin",
                        "postal_code": "3456",
                        "country": "DE"
                    }
                },
                "type": "loading"
            },
            {
                "place": {
                    "address": {
                        "locality": "Wysoka",
                        "postal_code": "12345",
                        "country": "PL"
                    }
                },
                "type": "unloading"
            }
        ]
    },
    "_links": {
        "self": {
            "href": "https://orders.system.trans.eu/api/rest/v1/orders/56acf700-1774-11e6-8ab6-0002a5d5c51b"
        }
    }
}