Examples
Contents
- Authentication at RIO IAM using the
partner_integration client (see Getting started) - Requesting transport orders
- Confirmation of transport orders
Requesting transport orders
Sample request
The following request returns the transport orders containing all their shipments:
GET https://api.transport-order-exchange.rio.cloud/transport-orders?embed=(shipments)
Sample technical requests
Sample responses
The following JSON documents show sample responses of the endpoint:
{
"items": [
{
"id": "0e1f55d8-2554-4fc4-9995-444732a74751",
"ordering_party_transport_order_id": "0e1f55d8-2554-4fc4-9995-444732a74751",
"contractor": {
"name": "RIO Spedition KG",
"account_id": "8ef04c71-8105-4bfb-a97c-a70db9d66974",
"supplier_code": "0123456789",
"duns": "123456789"
},
"ordering_party": {
"name": "MAN Truck & Bus SE"
},
"process_indicator": "ltl",
"priority": "regular",
"etag": "0",
"created_at": "2024-02-01T14:43:14Z",
"modified_at": "2024-02-01T14:43:14Z",
"aggregated_modified_at": "2024-02-01T14:43:14Z",
"_embedded": {
"shipments": [
{
"id": "ed04187b-4586-4033-b113-cbb839b08cbe",
"ordering_party_shipment_id": "360",
"supplier": {
"name": "Hengst SE",
"address": {
"street": "Industriestrasse 6",
"postal_code": "48356",
"city": "Nordwalde",
"country": "DE"
},
"supplier_code": "0080061722",
"duns": "012345678"
},
"loading": {
"shipper": {
"name": "Hengst SE",
"address": {
"street": "Industriestrasse 6",
"postal_code": "48356",
"city": "Nordwalde",
"country": "DE"
},
"supplier_code": "0080061722"
},
"time_window": {
"start_at": "2024-02-01T10:20:00Z",
"finish_at": "2024-02-01T11:00:20Z"
},
"location": {
"address": {
"street": "Industriestrasse 6",
"postal_code": "48356",
"city": "Nordwalde",
"country": "DE"
},
"coordinates": {
"latitude": 48.177412,
"longitude": 11.593972
}
},
"place_of_loading": "3",
"access_code": "386490"
},
"unloading": {
"recipient": {
"name": "ES",
"address": {
"street": "Industriestraße Mitte 2",
"postal_code": "38239",
"city": "Salzgitter",
"country": "DE"
},
"plant_code": "ES"
},
"time_window": {
"start_at": "2024-02-01T15:40:00Z",
"finish_at": "2024-02-01T17:00:00Z"
},
"location": {
"address": {
"street": "Industriestraße Mitte 2",
"postal_code": "38239",
"city": "Salzgitter",
"country": "DE"
},
"coordinates": {
"latitude": 52.144661,
"longitude": 10.412231
}
},
"place_of_discharge": "ES2"
},
"goods": {
"type": "cargo-material",
"handling_units": [
{
"type": "handling-unit",
"packaging_code": "09.84019-0957",
"quantity": 2,
"stacking_factor": 3,
"dimensions": {
"length_m": 1.23,
"width_m": 0.83,
"height_m": 0.925
},
"weight": {
"gross_weight_kg": 111.28,
"net_weight_kg:": 71.28
},
"auxiliary_packagings": [
{
"packaging_code": "09.84019-0956",
"quantity": 1
}
],
"contents": [
{
"type": "article",
"id": "51.12501-7444",
"delivery_instruction_reference": "00001195",
"internal_place_of_destination": {
"id": "L200"
},
"order_reference": "5400328508",
"country_of_origin": {
"country_code": "DE",
"dutiable_goods": false
},
"quantity": {
"type": "piece",
"value": 16
},
"net_explosive_mass_kg": 0,
"dangerous_goods_information": {
"undg": "2800",
"description": "2800 8 : Batterien, nass, auslaufsicher",
"exception_regulation": "Sondervorschrift 238 ADR"
}
}
]
}
]
}
}
]
}
}
]
} {
"items": [
{
"id": "2e601e53-b683-4c60-8a5e-667ce0c014f3",
"ordering_party_transport_order_id": "2e601e53-b683-4c60-8a5e-667ce0c014f3",
"contractor": {
"name": "RIO Spedition KG",
"account_id": "8ef04c71-8105-4bfb-a97c-a70db9d66974",
"supplier_code": "0123456789",
"duns": "123456789"
},
"ordering_party": {
"name": "MAN Truck & Bus SE"
},
"process_indicator": "ltl",
"priority": "regular",
"created_at": "2024-02-01T14:43:14.41636775Z",
"modified_at": "2024-02-01T14:43:14.41636775Z",
"_embedded": {
"shipments": [
{
"id": "ed04187b-4586-4033-b113-cbb839b08cbe",
"ordering_party_shipment_id": "344",
"supplier": {
"name": "Hengst SE",
"address": {
"street": "Industriestrasse 6",
"postal_code": "48356",
"city": "Nordwalde",
"country": "DE"
},
"supplier_code": "0080061722",
"duns": "012345678"
},
"loading": {
"shipper": {
"name": "Hengst SE",
"address": {
"street": "Industriestrasse 6",
"postal_code": "48356",
"city": "Nordwalde",
"country": "DE"
},
"supplier_code": "0080061722"
},
"time_window": {
"start_at": "2024-02-01T10:20:00Z",
"finish_at": "2024-02-01T11:00:20Z"
},
"location": {
"address": {
"street": "Industriestrasse 6",
"postal_code": "48356",
"city": "Nordwalde",
"country": "DE"
},
"coordinates": {
"latitude": 48.177412,
"longitude": 11.593972
}
},
"place_of_loading": "3",
"access_code": "386490"
},
"unloading": {
"recipient": {
"name": "ES",
"address": {
"street": "Industriestraße Mitte 2",
"postal_code": "38239",
"city": "Salzgitter",
"country": "DE"
},
"plant_code": "ES"
},
"time_window": {
"start_at": "2024-02-01T15:40:00Z",
"finish_at": "2024-02-01T17:00:00Z"
},
"location": {
"address": {
"street": "Industriestraße Mitte 2",
"postal_code": "38239",
"city": "Salzgitter",
"country": "DE"
},
"coordinates": {
"latitude": 52.144661,
"longitude": 10.412231
}
},
"place_of_discharge": "ES2"
},
"goods": {
"type": "cargo-material",
"handling_units": [
{
"type": "handling-unit",
"packaging_code": "09.84019-0957",
"quantity": 2,
"stacking_factor": 3,
"dimensions": {
"length_m": 1.23,
"width_m": 0.83,
"height_m": 0.925
},
"weight": {
"gross_weight_kg": 111.28,
"net_weight_kg:": 71.28
},
"auxiliary_packagings": [
{
"packaging_code": "09.84019-0956",
"quantity": 1
}
],
"contents": [
{
"type": "handling-unit",
"packaging_code": "09.84019-0780",
"quantity": 4,
"stacking_factor": 4,
"weight": {
"gross_weight_kg": 21.82,
"net_weight_kg:": 17.82
},
"auxiliary_packagings": [],
"contents": [
{
"type": "article",
"id": "51.12501-7444",
"delivery_instruction_reference": "00001195",
"internal_place_of_destination": {
"id": "L200"
},
"order_reference": "5400328508",
"country_of_origin": {
"country_code": "DE",
"dutiable_goods": false
},
"quantity": {
"type": "piece",
"value": 16
}
}
]
}
]
}
]
}
}
]
}
}
]
} Confirmation
Confirmation of shipments
Use this endpoint to confirm individual shipments and provide details such as means of transport, time windows, and time window IDs.
You can also update a previously submitted confirmation if new information becomes available.
Sample request
POST https://api.transport-order-exchange.rio.cloud/transport-orders/{transportOrderId}/shipments/{shipmentId}/confirmations
{
"means_of_transport": {
"license_plate": "M RI 0284",
"country_code": "DE"
},
"loading": {
"access_code": "ABCDEF",
"time_window": {
"time_from": "2022-03-08T07:58:10.123Z",
"time_to": "2022-03-08T07:58:10.123Z"
}
},
"unloading": {
"access_code": "ABCDEF",
"time_window": {
"time_from": "2022-03-08T07:58:10.123Z",
"time_to": "2022-03-08T07:58:10.123Z"
}
}
} Sample technical requests
Confirmation of transportDeprecated
Use this endpoint to confirm all shipments of a transport order.
Note: This endpoint is deprecated and will be removed on 01.08.2025. It is recommended to use the dedicated endpoint for confirming shipments instead.
Sample request
PUT https://api.transport-order-exchange.rio.cloud/confirmed-transport-orders/{transportOrderId}
Note: The If-Match header must be set to the current version (etag) of the transport order to be confirmed.
{
"id": "0e1f55d8-2554-4fc4-9995-444732a74751",
"status": "confirmed"
} Sample technical requests
Transport status updates
Using the transport status API you can inform the shipper about milestones reached as well as location data in between the milestones.
Note: It is not possible to send transport status messages for transport orders created before December 5th, 2024.
Milestone messages for direct transports
In case of a direct transport, the following three milestone messages are expected:
1
left-loading-location (Stage: direct)
2
arrived-at-unloading-location (Stage: at-arrival)
left-unloading-location (Stage: at-arrival)
Sample request
POST https://api.transport-order-exchange.rio.cloud/transport-orders/{transport-order-id}/shipments/{shipment-id}/transport-status
Sample payload for Left-Loading-Location
Note: For this message type, the stage field must be direct.
Note: In this example we show location_of_arrival containing a duns, but you can also provide a supplier_code or address.
{
"message_type": {
"type": "left-loading-location",
"stage": "direct"
},
"estimated_arrival_at": "2024-02-01T15:35:00Z",
"current_transport_leg": {
"departed_at": "2024-02-01T10:55:00Z",
"geo_location_of_arrival": {
"latitude": 51.935317,
"longitude": 10.145256
},
"location_of_arrival": {
"duns": "994444444"
}
},
"means_of_transport": {
"license_plate_number": "M RI 0284"
},
"location": {
"latitude": 52.075305,
"longitude": 7.452672
},
"data_collected_at": "2024-02-01T10:55:00Z",
"bordero_number": "123456789",
"shipment_number": "193248342",
"access_code_at_unloading": "123456"
} Sample technical requests
Sample payload for Arrived-At-Unloading-Location
Note: For this message type, the stage field must be at-arrival.
Note: In this example we show location_of_arrival containing a duns, but you can also provide a supplier_code or address.
{
"message_type": {
"type": "arrived-at-unloading-location",
"stage": "at-arrival"
},
"estimated_arrival_at": "2024-02-01T15:35:00Z",
"current_transport_leg": {
"departed_at": "2024-02-01T10:55:00Z",
"geo_location_of_arrival": {
"latitude": 51.935317,
"longitude": 10.145256
},
"location_of_arrival": {
"duns": "994444444"
}
},
"means_of_transport": {
"license_plate_number": "M RI 0284"
},
"location": {
"latitude": 51.935317,
"longitude": 10.145256
},
"data_collected_at": "2024-02-01T15:35:00Z",
"bordero_number": "123456789",
"shipment_number": "193248342",
"access_code_at_unloading": "123456"
} Sample technical requests
Sample payload for Left-Unloading-Location
Note: For this message type, the stage field must be at-arrival.
Note: In this example we show location_of_arrival containing a duns, but you can also provide a supplier_code or address.
{
"message_type": {
"type": "left-unloading-location",
"stage": "at-arrival"
},
"estimated_arrival_at": "2024-02-01T15:35:00Z",
"current_transport_leg": {
"departed_at": "2024-02-01T10:55:00Z",
"geo_location_of_arrival": {
"latitude": 51.935317,
"longitude": 10.145256
},
"location_of_arrival": {
"duns": "994444444"
}
},
"means_of_transport": {
"license_plate_number": "M RI 0284"
},
"location": {
"latitude": 51.935317,
"longitude": 10.145256
},
"data_collected_at": "2024-02-01T15:50:00Z",
"bordero_number": "123456789",
"shipment_number": "193248342",
"access_code_at_unloading": "123456"
} Sample technical requests
Milestone messages for transports via cross dock
In case of a transport via cross dock, the following five milestone messages are expected:
1
left-loading-location (Stage: preliminary-leg)
2
arrived-at-cross-dock (Stage: preliminary-leg)
3
left-cross-dock (Stage: main-leg)
4
arrived-at-unloading-location (Stage: at-arrival)
left-unloading-location (Stage: at-arrival)
Sample request
POST https://api.transport-order-exchange.rio.cloud/transport-orders/{transport-order-id}/shipments/{shipment-id}/transport-status
Sample payload for Left-Loading-Location
Note: For this message type, the stage field must be preliminary-leg.
Note: In this example we show location_of_arrival containing a supplier_code, but you can also provide a duns or address.
{
"message_type": {
"type": "left-loading-location",
"stage": "preliminary-leg"
},
"estimated_arrival_at": "2024-02-01T15:35:00Z",
"current_transport_leg": {
"departed_at": "2024-02-01T10:55:00Z",
"geo_location_of_arrival": {
"latitude": 52.352568,
"longitude": 9.880773
},
"location_of_arrival": {
"supplier_code": "9944444444"
},
"estimated_arrival_at": "2024-02-01T12:20:00Z"
},
"means_of_transport": {
"license_plate_number": "M RI 0284",
"license_plate_country_code": "DE",
"fuel_type": "petrol-and-electric"
},
"location": {
"latitude": 52.075305,
"longitude": 7.452672
},
"data_collected_at": "2024-02-01T10:55:00Z",
"shipment_number": "193248342",
"access_code_at_unloading": "123456"
} Sample technical requests
Sample payload for Arrived-At-Cross-Dock
Note: For this message type, the stage field must be preliminary-leg.
Note: In this example we show location_of_arrival containing a supplier_code, but you can also provide a duns or address.
{
"message_type": {
"type": "arrived-at-cross-dock",
"stage": "preliminary-leg"
},
"estimated_arrival_at": "2024-02-01T15:35:00Z",
"current_transport_leg": {
"departed_at": "2024-02-01T10:55:00Z",
"geo_location_of_arrival": {
"latitude": 52.352568,
"longitude": 9.880773
},
"location_of_arrival": {
"supplier_code": "9944444444"
},
"estimated_arrival_at": "2024-02-01T12:20:00Z"
},
"means_of_transport": {
"license_plate_number": "M RI 0284",
"license_plate_country_code": "DE",
"fuel_type": "petrol-and-electric"
},
"location": {
"latitude": 52.353237,
"longitude": 9.880859
},
"data_collected_at": "2024-02-01T12:25:00Z",
"shipment_number": "193248342",
"access_code_at_unloading": "123456"
} Sample technical requests
Sample payload for Left-Cross-Dock
Note: For this message type, the stage field must be main-leg.
Note: In this example we show location_of_arrival containing a supplier_code, but you can also provide a duns or address.
{
"message_type": {
"type": "left-cross-dock",
"stage": "main-leg"
},
"estimated_arrival_at": "2024-02-01T15:35:00Z",
"current_transport_leg": {
"departed_at": "2024-02-01T13:05:00Z",
"geo_location_of_arrival": {
"latitude": 52.074725,
"longitude": 7.45258
},
"location_of_arrival": {
"supplier_code": "9944444444"
}
},
"means_of_transport": {
"license_plate_number": "M RI 0284",
"license_plate_country_code": "DE",
"fuel_type": "petrol-and-electric"
},
"location": {
"latitude": 52.353097,
"longitude": 9.881199
},
"data_collected_at": "2024-02-01T13:05:00Z",
"bordero_number": "123456789",
"shipment_number": "193248342",
"access_code_at_unloading": "123456"
} Sample technical requests
Sample payload for Arrived-At-Unloading-Location
Note: For this message type, the stage field must be at-arrival.
Note: In this example we show location_of_arrival containing a supplier_code, but you can also provide a duns or address.
{
"message_type": {
"type": "arrived-at-unloading-location",
"stage": "at-arrival"
},
"estimated_arrival_at": "2024-02-01T15:35:00Z",
"current_transport_leg": {
"departed_at": "2024-02-01T13:05:00Z",
"geo_location_of_arrival": {
"latitude": 51.935317,
"longitude": 10.145256
},
"location_of_arrival": {
"supplier_code": "9944444444"
}
},
"means_of_transport": {
"license_plate_number": "M RI 0284",
"license_plate_country_code": "DE",
"fuel_type": "petrol-and-electric"
},
"location": {
"latitude": 51.935317,
"longitude": 10.145256
},
"data_collected_at": "2024-02-01T15:35:00Z",
"bordero_number": "123456789",
"shipment_number": "193248342",
"access_code_at_unloading": "123456"
} Sample technical requests
Sample payload for Left-Unloading-Location
Note: For this message type, the stage field must be at-arrival.
Note: In this example we show location_of_arrival containing a supplier_code, but you can also provide a duns or address.
{
"message_type": {
"type": "left-unloading-location",
"stage": "at-arrival"
},
"estimated_arrival_at": "2024-02-01T15:35:00Z",
"current_transport_leg": {
"departed_at": "2024-02-01T13:05:00Z",
"geo_location_of_arrival": {
"latitude": 51.935317,
"longitude": 10.145256
},
"location_of_arrival": {
"supplier_code": "9944444444"
}
},
"means_of_transport": {
"license_plate_number": "M RI 0284",
"license_plate_country_code": "DE",
"fuel_type": "petrol-and-electric"
},
"location": {
"latitude": 52.075305,
"longitude": 7.452672
},
"data_collected_at": "2024-02-01T15:50:00Z",
"bordero_number": "123456789",
"shipment_number": "193248342",
"access_code_at_unloading": "123456"
} Sample technical requests
Location messages
In between the milestone messages, additional location updates can be sent.
Sample request
POST https://api.transport-order-exchange.rio.cloud/transport-orders/{transport-order-id}/shipments/{shipment-id}/transport-status
Note: For this message type, the stage field must be direct, preliminary-leg, main-leg or at-arrival, depending on the last milestone message which has been sent.
Note: You only need to provide one of the location_of_arrival fields. The sample payload below demonstrates examples for each option: duns, supplier_code and address.
{
"message_type": {
"type": "location",
"stage": "preliminary-leg"
},
"estimated_arrival_at": "2024-02-01T15:35:00Z",
"current_transport_leg": {
"departed_at": "2024-02-01T10:55:00Z",
"geo_location_of_arrival": {
"latitude": 52.352568,
"longitude": 9.880773
},
"location_of_arrival": {
"duns": "994444444",
"supplier_code": "9944444444",
"address": {
"street": "Hannoversche Str. 27",
"postal_code": "31319",
"city": "Sehnde",
"country": "DE"
}
},
"estimated_arrival_at": "2024-02-01T12:20:00Z"
},
"means_of_transport": {
"license_plate_number": "M RI 0284",
"license_plate_country_code": "DE",
"fuel_type": "petrol-and-electric"
},
"location": {
"latitude": 52.256473,
"longitude": 9.306241
},
"data_collected_at": "2024-02-01T12:05:00Z",
"shipment_number": "193248342",
"access_code_at_unloading": "123456"
} Sample technical requests