Description of creating a warehouse announcement as a carrier who possesses a purchase order number
Scenario
- Carrier and shipper are both present on Trans.eu platform
- Shipper’s Purchase Order Number is stored in Carrier’s external TMS/ERP and can be sent via API
- A time window has been assigned to the Carrier by the Shipper in the Schedules module
Authorize access
Before it is possible to send any request, user needs to authorize access.
- client app was registered using registration form
- external app was granted api keys (client_id and client_secret)
- authorization process has been implemented in external app
Step 1 — Filter out Time Windows to find proper timeWindowId
Each time window consists of a timeWindowId, which is required to find the proper time slot for scheduling a warehouse announcement. Using the “search” query parameter, it is possible to narrow the search result to a time window containing a specific purchase order number.
Endpoint
GET https://api.platform.trans.eu/dock-scheduler-api/v1/warehouse/timeWindowExample of use:
https://api.platform.trans.eu/dock-scheduler-api/v1/warehouse/timeWindow?filter={"search":"PO-API-999"}Response:
{
"content": [
{
"id": 114054,
"status": "AVAILABLE",
"route": {
"loading_place": {
"coordinates": {
"latitude": 50.40502,
"longitude": 16.51226
},
"description": null,
"name": "10 minute warehouse",
"street": "Zdrojowa",
"number": "5",
"locality": "Polanica-Zdrój",
"postal_code": "57-320",
"country": "pl"
},
"unloading_place": {
"coordinates": {
"latitude": 37.984385,
"longitude": 23.727456
},
"description": null,
"name": "Ateny",
"street": null,
"number": null,
"locality": "Ateny",
"postal_code": null,
"country": "gr"
}
},
"carrier": {
"id": 1079413,
"type": "REGISTERED",
"subcontractor": null,
"legal_name": "(P3DT) TFC Carrier Test"
},
"shipper": {
"id": 1079411,
"legal_name": "(P3DT) CargoON Test"
},
"warehouse": {
"id": 23706,
"name": "10 minute warehouse",
"is_active": true,
"is_locked": false,
"address": {
"coordinates": {
"latitude": 50.40502,
"longitude": 16.51226
},
"street": "Zdrojowa",
"number": "5",
"locality": "Polanica-Zdrój",
"postal_code": "57-320",
"country": "pl",
"remarks": null,
"id": 23844
},
"operation_time": 10,
"operation_type": "any",
"time_zone": {
"id": "Europe/Warsaw",
"offset": "+02:00",
"offset_minutes": 120
},
"announcement_template": {
"id": 3807
}
},
"remarks": null,
"forward": null,
"transport": null,
"billable": false,
"reference_number": "DS/F9DF9E5",
"external_number": "REF-321777",
"created_at": "2026-05-11T12:47:01",
"valid_from": "2026-07-23",
"valid_to": "2026-07-23",
"start_time": "12:00:00",
"end_time": "15:00:00",
"range_type": "CYCLE",
"is_expired": false,
"operation_type": "loading",
"operation_time": "PT10M",
"freight_order": {
"freight_id": null,
"freight_reference_number": null,
"publication_id": null,
"order_id": null,
"order_reference_number": null,
"external_reference_number": null
},
"forward_permissions": {
"allow": true,
"disallow": null,
"require_carrier_data": true
},
"purchase_order": {
"id": 114054,
"number": "PO-API-999"
},
"recurrence_config": null
}
],
"total_items": null,
"offset": 0,
"limit": 25,
"last": true
}Step 2 — Get list of available time windows
With the timeWindowId provided in the response:
{
"content": [
{
"id": 114054,
...as well as the validity dates provided in the response:
"valid_from": "2026-07-23",
"valid_to": "2026-07-23",it is now possible to verify available time slots within this time window.
Endpoint:
GET https://api.platform.trans.eu/ext/dock-scheduler-api/v2/time-window/{id}/possibleThe validity dates from the previous step must be supplied as the date_from and date_to query parameters. The maximum allowed period between them is 3 days.
Example of use:
https://api.platform.trans.eu/ext/dock-scheduler-api/v2/time-window/{114054}/possible?date_from=07.23.2026&date_to=07.23.2026 Response:
{
"time_windows": {
"0": {
"2026-07-23": [
{
"start_time": "12:00:00",
"end_time": "12:10:00",
"ramp_id": 28744
},
{
"start_time": "12:10:00",
"end_time": "12:20:00",
"ramp_id": 28744
}
]
},
"28744": {
"2026-07-23": [
{
"start_time": "12:00:00",
"end_time": "12:10:00",
"ramp_id": 28744
},
{
"start_time": "12:10:00",
"end_time": "12:20:00",
"ramp_id": 28744
}
]
}
},
"ramps": {
"28744": {
"id": 28744,
"is_locked": false,
"is_active": true,
"time_zone": "Europe/Warsaw",
"operation_type": "any",
"name": "Rampa 1",
"ramp_type": "RAMP"
}
},
"quantity": 2
}
Once it has been decided which time slot is preferable, it is now possible to add a warehouse booking as a carrier.
For the full reference of this method, see Get time slots with time window id.
Step 3 — Create the announcement as a carrier
Once you have decided which time slot is preferable, create the warehouse announcement.
Endpoint:
POST https://api.platform.trans.eu/ext/dock-scheduler-api/v2/announcementThe endpoint requires the definition of the following in the request body:
- Start date & time of the announcement (date_from)
- End date & time of the announcement (date_to) — or, alternatively, the operation time / duration (operation_time)
- Alternatively to the end date & time, it is possible to add the operation time (duration) of the booking
- Operation type (operation_type) — allowed values: loading, unloading (lowercase)
- timeWindowId
You can also add up to 25 additional purchase order numbers to the announcement as a carrier.
Consolidating multiple time windows and adding purchase orders: this endpoint can combine several time windows into one announcement and attach additional purchase orders. The distinction between purchase orders carried in by a time window and those passed in additional_purchase_orders, along with the validation rules for consolidation, is documented in full in Add announcement with additional purchase orders using time window id.
Request body example:
{
"additional_purchase_orders": [
{
"number": "PO-19960225420"
}
],
"date_from": "2026-07-23T12:00:00Z",
"date_to": "2026-07-23T12:10:00Z",
"operation_type": "loading",
"time_windows": [
{
"id": 114054
}
]
}Response example:
{
"id": 121723,
"status": "INITIAL",
"stage": null,
"vehicle": null,
"ramp": {
"warehouse": {
"id": 23706,
"name": "10 minute warehouse",
"configurations": [
{
"slot": 10,
"id": 26210,
"valid_from": "2025-12-16",
"valid_until": null,
"quantity_of_slots": 1
}
],
"address": {
"coordinates": {
"latitude": 50.40502,
"longitude": 16.51226
},
"street": "Zdrojowa",
"number": "5",
"locality": "Polanica-Zdrój",
"postal_code": "57-320",
"country": "pl",
"remarks": null,
"id": 23844
},
"is_active": true,
"is_locked": false,
"operation_type": "any",
"slot": 10,
"quantity_of_slots": 1,
"time_zone": {
"id": "Europe/Warsaw",
"offset": "+02:00",
"offset_minutes": 120
},
"rules_file_id": null,
"rules_file_name": null,
"rules_file_original_name": null
},
"id": 28744,
"name": "Rampa 1",
"is_active": true,
"ramp_type": "RAMP",
"is_locked": false,
"operation_type": "any"
},
"carrier": {
"id": 1079413,
"telephone": "(0048) 6014338379",
"email": "aromkowska3@trans.eu",
"address": {
"coordinates": null,
"street": "Testowa 3",
"locality": "Warszawa",
"postal_code": "00-001",
"country": "PL"
},
"type": "REGISTERED",
"legal_name": "(P3DT) TFC Carrier Test"
},
"shipper": {
"id": 1079411,
"telephone": "(0048) 4253032299",
"email": "test113@trans.eu",
"address": {
"coordinates": null,
"street": "Szkoleniowa 1",
"locality": "Poznań",
"postal_code": "56-739",
"country": "PL"
},
"legal_name": "(P3DT) CargoON Test"
},
"route": {
"spots": [
{
"order": 1,
"operations": [
{
"order": 1,
"operation_type": "loading",
"time_window_id": null
}
],
"address": {
"coordinates": {
"latitude": 50.40502,
"longitude": 16.51226
},
"description": null,
"name": "10 minute warehouse",
"street": "Zdrojowa",
"number": "5",
"locality": "Polanica-Zdrój",
"postal_code": "57-320",
"country": "pl"
}
}
]
},
"forward": null,
"transport": null,
"date_from": "2026-07-23T12:00:00",
"date_to": "2026-07-23T12:10:00",
"operation_time": "PT10M",
"operation_type": "loading",
"driver": null,
"second_driver": null,
"reference_number": "DS/F9DF9E5/1",
"template_parameters": [
{
"group": "VEHICLE",
"name": "TRUCK_PLATE_NUMBER",
"is_mandatory": true,
"default_value": null
},
{
"group": "VEHICLE",
"name": "TRAILER_PLATE_NUMBER",
"is_mandatory": false,
"default_value": null
},
{
"group": "DRIVER",
"name": "DRIVER_NAME",
"is_mandatory": true,
"default_value": null
},
{
"group": "WEIGHT",
"name": "ENTRANCE_LEAVE_WEIGHTS",
"is_mandatory": true,
"default_value": null
},
{
"group": "WEIGHT",
"name": "CARGO_WEIGHT",
"is_mandatory": true,
"default_value": null
}
],
"external_reference_number": "REF-321777",
"freight_order": null,
"trans_task": null,
"forward_permissions": {
"allow": true,
"disallow": null,
"require_carrier_data": true
},
"time_windows": [
[]
],
"additional_purchase_orders": [
[]
]
}