Add announcement with additional purchase orders using time window id

This method allows a car­ri­er to cre­ate a ware­house announce­ment from one or more time win­dows, option­al­ly adding pur­chase order num­bers on top of those already attached to the time win­dows.

It sup­ports two relat­ed capa­bil­i­ties in a sin­gle request:

Con­sol­i­dat­ing mul­ti­ple time win­dows into one announce­ment (for exam­ple, com­bin­ing sev­er­al deliv­er­ies to the same ware­house into a sin­gle book­ing).

Adding addi­tion­al pur­chase order num­bers to the announce­ment beyond any pur­chase orders already car­ried by the time win­dows.

Where the time window id comes from

Each announce­ment is built from one or more time win­dow ids. To obtain them, and to con­firm which time slots are actu­al­ly book­able with­in a time win­dow, use the flow described in Gen­er­ate a ware­house announce­ment as a car­ri­er — specif­i­cal­ly:

• Fil­ter avail­able time win­dows to find the rel­e­vant timeWin­dowId (and its valid­i­ty dates).
• Retrieve the avail­able slots for that win­dow using Get time slots with time win­dow id (/ext/dock-scheduler-api/v2/time-window/{id}/possible).

Choosing the time slot

"date_from": "2026-05-22T12:20:00Z",
  "date_to": "2026-05-22T12:30:00Z"

 "date_from": "2026-05-22T12:20:00Z",
  "operation_time": "PT10M"

General notes

• Announce­ments from a time win­dow can only be cre­at­ed as a car­ri­er, not as a ship­per.
• As a car­ri­er, pro­vid­ing car­ri­er details (id, legal_name, type, etc.) is not manda­to­ry — the car­ri­er assigned to the book­ing is treat­ed as the book­ing par­ty in this sce­nario.
• operation_type can­not be null. Allowed val­ues: loading, unloading (low­er­case).

Consolidating multiple time windows

You can com­bine sev­er­al time win­dows into a sin­gle announce­ment by sup­ply­ing more than one entry in the time_windows array:

  "time_windows": [
    {
      "id": 120205
    },
    {
      "id": 120206
    }        
  ]

All pur­chase orders attached to the con­sol­i­dat­ed time win­dows become part of the result­ing book­ing as its main pur­chase orders. See Pur­chase orders: main vs. addi­tion­al below for how this inter­acts with additional_purchase_orders.

Validation rules for consolidation

When two or more time win­dows are con­sol­i­dat­ed, they must sat­is­fy all of the fol­low­ing con­di­tions. Fail­ing any one of them returns 400 Bad Request (see Error han­dling for the exact response bod­ies).

1. Ramp inter­sec­tion — the time win­dows must share at least one com­mon ramp. For exam­ple, if win­dow X allows ramps 1, 2, 3 and win­dow Y allows ramps 3, 4, they inter­sect on ramp 3. If win­dow Y allowed only ramp 4, there would be no inter­sec­tion. A time win­dow whose ramp is set to any inter­sects with any oth­er time win­dow regard­less of its assigned ramps.
2. Same ware­house — all con­sol­i­dat­ed time win­dows must belong to the same ware­house.
3. Oper­a­tion time inter­sec­tion — the operation_time in the request must be com­pat­i­ble with the max­i­mum oper­a­tion time shared across the time win­dows. If the request spec­i­fies PT10M but at least one time win­dow is con­fig­ured for a 30-minute oper­a­tion, the request is reject­ed.
4. Date/time inter­sec­tion — the time win­dows must over­lap in time. Win­dows of 13:00–15:00 and 15:30–17:00 can­not be con­sol­i­dat­ed. How­ev­er, a time win­dow with an open range (a full day, or mul­ti­ple days) inter­sects with a nar­row­er win­dow whose slot falls inside that range.
5. Match­ing oper­a­tion type — all con­sol­i­dat­ed time win­dows must have the same oper­a­tion type. A win­dow con­fig­ured for loading can­not be con­sol­i­dat­ed with one con­fig­ured for unloading.

Ramp id when consolidating

For a car­ri­er, pro­vid­ing a ramp.id is not manda­to­ry. If you do include a ramp.id while con­sol­i­dat­ing, it must be a ramp com­mon to all time win­dows in the announce­ment. When ramp is left unspec­i­fied (or the win­dows use “any”), the plat­form resolves an eli­gi­ble shared ramp auto­mat­i­cal­ly.

Purchase orders: main vs. additional

There is an impor­tant dis­tinc­tion between pur­chase orders that arrive via a time win­dow and those sup­plied in additional_purchase_orders:

• Pur­chase orders already attached to a con­sol­i­dat­ed time win­dow are added to the book­ing as main pur­chase orders — they are con­sumed as part of con­sol­i­dat­ing that win­dow
• additional_purchase_orders are for pur­chase orders that are not rep­re­sent­ed by any time win­dow in the request.

Worked exam­ple (con­sol­i­da­tion + addi­tion­al PO): An announce­ment is built from two time win­dows — win­dow A car­ries PO101, win­dow B car­ries PO202 — and the request also sup­plies PO303 in additional_purchase_orders. All three pur­chase orders become part of the book­ing, but only PO303 is an addi­tion­al pur­chase order; PO101 and PO202 are main pur­chase orders car­ried in by their win­dows.

Addi­tion­al POs can­not sub­sti­tute for a time win­dow. Sup­ply­ing a pur­chase order in additional_purchase_orders does not con­sol­i­date the time win­dow that owns it. If win­dow 123 car­ries PO11 and win­dow 124 car­ries PO22, and the request includes only time win­dow id 123 while pass­ing PO22 as an addi­tion­al PO, then only win­dow 123 is con­sumed; PO22 is attached as an addi­tion­al pur­chase order and win­dow 124 is not con­sol­i­dat­ed. To con­sol­i­date win­dow 124, its id must be present in the time_windows array.

JSON request body example

{
  "additional_purchase_orders": [
    {
      "number": "PO-API-5050"
    }
  ],
  "carrier": {
    "contact_phone": {
      "number": "555123456",
      "prefix": "+48"
    },
    "email": "dispatch@fastfreight.pl",
    "id": 10542,
    "legal_name": "Fast Freight Logistics Sp. z o.o.",
    "subcontractor": {
      "contact_phone": {
        "number": "987654321",
        "prefix": "+48"
      },
      "email": "contact@subcarrier.pl",
      "legal_name": "SubCarrier Transport LLC",
      "telephone": "+48987654321"
    },
    "telephone": "+48555123456",
    "type": "REGISTERED"
  },
  "date_from": "2026-05-12T12:52:11.778Z",
  "driver": {
    "account_id": 8821,
    "contact_phone": { "number": "600111222", "prefix": "+48" },
    "country": "47_poland",
    "first_document": {
      "issuing_authority": "Prezydent Miasta Wrocławia",
      "number": "ABC123456",
      "type": "IDENTITY_CARD"
    },
    "full_name": "Jan Kowalski",
    "languages": "1_pl",
    "phone_number": "+48600111222",
    "second_document": {
      "issuing_authority": "Wydział Komunikacji",
      "number": "PRAWO-123",
      "type": "IDENTITY_CARD"
    }
  },
  "external_reference_number": "EXT-REF-2026-001",
  "operation_time": "PT30M",
  "operation_type": "loading",
  "ramp": {
    "id": 15
  },
  "time_windows": [
    {
      "id": 30401
    }
  ],
  "vehicle": {
    "combustion_norm": "8_euro_6",
    "trailer_plate_number": "DW 9988A",
    "truck_plate_number": "DW 1122B",
    "vehicle_manufacturer": "459_scania"
  }
}

Note on ramp.id in this exam­ple: the val­ue 15 is illus­tra­tive. As explained under Con­sol­i­dat­ing mul­ti­ple time win­dows, a car­ri­er is not required to sup­ply a ramp; if one is sup­plied while con­sol­i­dat­ing, it must be com­mon to every time win­dow in the announce­ment.

Minimum required payload as a carrier

{
  "date_from": "2026-05-22T12:20:00Z",
  "date_to": "2026-05-22T12:30:00Z",
  "operation_type": "loading",
  "time_windows": [
    {
      "id": 114234
    }
  ]
}

Response

A suc­cess­ful call returns the cre­at­ed announce­ment object with status: "INITIAL". An abridged exam­ple:

{
  "id": 121631,
  "status": "INITIAL",
  "stage": null,
  "vehicle": null,
  "ramp": {
    "warehouse": {
      "id": 23706,
      "name": "10 minute warehouse",
      "address": {
        "coordinates": { "latitude": 50.40502, "longitude": 16.51226 },
        "street": "Zdrojowa",
        "number": "5",
        "locality": "Polanica-Zdrój",
        "postal_code": "57-320",
        "country": "pl",
        "id": 23844
      },
      "time_zone": { "id": "Europe/Warsaw", "offset": "+02:00", "offset_minutes": 120 }
    },
    "id": 28744,
    "name": "Rampa 1",
    "ramp_type": "RAMP",
    "operation_type": "any"
  },
  "carrier": {
    "id": 1079413,
    "type": "REGISTERED",
    "legal_name": "(P3DT) TFC Carrier Test"
  },
  "shipper": {
    "id": 1079411,
    "legal_name": "(P3DT) CargoON Test"
  },
  "date_from": "2026-05-22T12:20:00",
  "date_to": "2026-05-22T12:30:00",
  "operation_time": "PT10M",
  "operation_type": "loading",
  "reference_number": "DS/F9DFD5D/6",
  "forward_permissions": {
    "allow": true,
    "disallow": null,
    "require_carrier_data": true
  },
  "time_windows": [
    []
  ],
  "additional_purchase_orders": [
    []
  ]
}

In the response, time_windows and additional_purchase_orders are returned as arrays of emp­ty arrays — for exam­ple [[]], or [[], []] when two time win­dows were con­sol­i­dat­ed, and [[], [], []] for three.

Error handling

Con­sol­i­da­tion fail­ures return 400 Bad Request with a DomainValidationException body. The detail field iden­ti­fies which rule was vio­lat­ed.

No ramp inter­sec­tion between time win­dows:

{
  "detail": "Time windows must have ramps intersection",
  "error_code": "C6718B0731F24C4A888B0B3F43A317ED",
  "status": 400,
  "timestamp": "2026-07-20T09:30:17.481346964",
  "title": "Bad Request",
  "type": "DomainValidationException",
  "service_code": 5313
}

Time win­dows belong to dif­fer­ent ware­hous­es:

{
  "detail": "Time windows must have the same warehouse id. Time windows with different warehouse [120228]",
  "error_code": "786C04D463AF4F288EF250385C131211",
  "status": 400,
  "timestamp": "2026-07-20T09:48:11.802588068",
  "title": "Bad Request",
  "type": "DomainValidationException",
  "service_code": 5313
}

Request­ed oper­a­tion time incom­pat­i­ble with the time win­dows’ inter­sec­tion:

{
  "detail": "Carrier cannot get possible slot with operation time different from time windows intersection max operation time",
  "error_code": "176687413C80466DB298C74F98071B40",
  "status": 400,
  "timestamp": "2026-07-20T09:47:11.474046216",
  "title": "Bad Request",
  "type": "DomainValidationException",
  "service_code": 5313
}

No date/time inter­sec­tion between time win­dows:

{
  "detail": "Time windows must have date time intersection",
  "error_code": "EE645A14ED9A49AA8AD6780A793645E5",
  "status": 400,
  "timestamp": "2026-07-20T09:53:14.419942363",
  "title": "Bad Request",
  "type": "DomainValidationException",
  "service_code": 5313
}

Time win­dows have dif­fer­ent oper­a­tion types:

{
  "detail": "Time windows [120206] have different operation type",
  "error_code": "D5219A90A97B4E939198F692366908C8",
  "status": 400,
  "timestamp": "2026-07-20T10:13:21.082019539",
  "title": "Bad Request",
  "type": "DomainValidationException",
  "service_code": 5313
}