/addons/route-optimization/jobs

Submit an asynchronous route optimization job

Đường dẫn

POST/api/v1/partners/addons/route-optimization/jobs

Xác thực yêu cầuapi-key

Ví dụ gọi bằng curl

curl -X POST "https://<your-host>/api/v1/partners/addons/route-optimization/jobs" \
  -H "api-key: YOUR_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "content-type: application/json" \
  -d '{
  "external_reference": "string",
  "replaces_job_id": "string",
  "optimization_options": {
    "delivery_mode": "1",
    "kind_of_plan": "1",
    "tour_mode": "string"
  },
  "vehicles": [
    {
      "external_vehicle_id": "string",
      "resource_id": 0,
      "from_address": "string",
      "from_lat": 0,
      "from_lon": 0,
      "from_working_time": "2026-01-01T00:00:00+07:00",
      "to_working_time": "2026-01-01T00:00:00+07:00",
      "handling_unit_ids": [
        0
      ],
      "height_of_vehicle": 0,
      "length_of_vehicle": 0,
      "width_of_vehicle": 0,
      "vehicle_tonnage": 0,
      "to_address": "string",
      "to_lat": 0,
      "to_lon": 0
    }
  ],
  "orders": [
    {
      "external_order_id": "string",
      "transport_mode": "firstmile",
      "handling_unit_id": 0,
      "service_id": 0,
      "pickup_address": "string",
      "pickup_lat": 0,
      "pickup_lon": 0,
      "pickup_date_time": "2026-01-01T00:00:00+07:00",
      "pickup_date_time_to": "2026-01-01T00:00:00+07:00",
      "drop_address": "string",
      "drop_lat": 0,
      "drop_lon": 0,
      "drop_date_time": "2026-01-01T00:00:00+07:00",
      "drop_date_time_to": "2026-01-01T00:00:00+07:00",
      "rlength": 0,
      "rwidth": 0,
      "rheight": 0,
      "rweight": 0,
      "count_of_parcels": 0,
      "resource_id": 0,
      "distance": 0,
      "pickup_wid": 0,
      "drop_wid": 0,
      "loading_time": 0,
      "unloading_time": 0,
      "sender_name": "string",
      "sender_phone": "string",
      "receiver_name": "string",
      "receiver_phone": "string"
    }
  ]
}'

Tham số

Tên	Vị trí	Kiểu	Bắt buộc	Mô tả
Idempotency-Key	header	string	Có	Client-scoped key retained indefinitely; maximum 128 chars

Nội dung gửi lên

Bổ sung ngoài bản đặc tả

Bản đặc tả OpenAPI chưa mô tả đầy đủ phần này, nên chúng tôi bổ sung nội dung dưới đây từ mã nguồn của API. Khi bản đặc tả có đủ thông tin, phần này sẽ được cập nhật theo.

Trường	Kiểu	Bắt buộc	Mô tả
external_reference	string	Không	Your own identifier for this job. 0 to 128 characters.
replaces_job_id	string (uuid)	Không	Identifier of one of your own jobs still in QUEUED status. Submitting with this field atomically supersedes that job, which becomes CANCELLED: this is the only way a job reaches CANCELLED, and there is no separate cancel endpoint. The guard fires once the target job has been picked up for processing, which can happen while it still reports QUEUED; past that point the submit is refused with JOB_ALREADY_PROCESSING.
optimization_options	object	Có	Controls how the optimizer weighs distance, vehicle count, workload balance, time windows and driver availability for this job.
vehicles	object[]	Có	The fleet available for this job. 1 to 200 vehicles.
orders	object[]	Có	The drop points to plan for this job. At least 1 order.

Các trường của `optimization_options`

Trường	Kiểu	Bắt buộc	Mô tả
delivery_mode	'1' \| '2' \| '3' \| '4'	Có	Delivery mode. '1' normal, '2' same day, '3' express (2 hour), '4' four hour.
kind_of_plan	'1' \| '2'	Có	Planning mode. '1' actual planning, '2' plan in advance.
tour_mode	string	Có	Five binary flags plus a time limit, joined by semicolons in this exact order: minimize_total_distance, minimize_vehicle_count, balance_workload, prioritize_time_windows, require_available_driver, time_limited_route. Each flag is 0 or 1; time_limited_route is an integer number of minutes, 0 meaning no limit. Example: '1;0;0;0;0;0'. Length 11 to 32 characters, pattern ^[01](;[01]){4};\d+$.

Các trường của `vehicles`

Trường	Kiểu	Bắt buộc	Mô tả
external_vehicle_id	string	Có	Your own identifier for this vehicle. 1 to 128 characters.
resource_id	integer	Có	Internal resource identifier for the vehicle. 1 or greater.
from_address	string	Có	Starting address of the vehicle. 1 to 500 characters.
from_lat	number	Có	Starting point latitude. Minus 90 to 90.
from_lon	number	Có	Starting point longitude. Minus 180 to 180.
from_working_time	string (date-time)	Có	Start of the vehicle working window. ISO 8601 date time.
to_working_time	string (date-time)	Có	End of the vehicle working window. ISO 8601 date time.
handling_unit_ids	integer[]	Có	Handling unit identifiers this vehicle can carry. Maximum 100 entries.
height_of_vehicle	number	Có	Vehicle height, in centimetres. 1 or greater. An earlier revision of this documentation named the wrong unit for this field; the stored column has always been an integer count of centimetres with no conversion applied, so submit the value directly in centimetres.
length_of_vehicle	number	Có	Vehicle length, in centimetres. 1 or greater. See the note on height_of_vehicle above.
width_of_vehicle	number	Có	Vehicle width, in centimetres. 1 or greater. See the note on height_of_vehicle above.
vehicle_tonnage	number	Có	Vehicle payload capacity, in kilograms despite the field name. 0 or greater. The stored column is an integer count of kilograms with no conversion applied, so submit the value directly in kilograms.
to_address	string	Không	Ending address of the vehicle, if different from the start. 0 to 500 characters.
to_lat	number	Không	Ending point latitude, if the vehicle ends somewhere other than from_lat.
to_lon	number	Không	Ending point longitude, if the vehicle ends somewhere other than from_lon.

Các trường của `orders`

Trường	Kiểu	Bắt buộc	Mô tả
external_order_id	string	Có	Your own identifier for this order. 1 to 128 characters.
transport_mode	'firstmile' \| 'midmile' \| 'lastmile'	Có	Which leg of the haul this order belongs to.
handling_unit_id	integer	Có	Handling unit identifier for the cargo. 1 or greater.
service_id	integer	Có	Service identifier for the order. 1 or greater.
pickup_address	string	Có	Pickup address. 1 to 500 characters.
pickup_lat	number	Có	Pickup point latitude.
pickup_lon	number	Có	Pickup point longitude.
pickup_date_time	string (date-time)	Có	Start of the pickup window. ISO 8601 date time.
pickup_date_time_to	string (date-time)	Có	End of the pickup window. ISO 8601 date time.
drop_address	string	Có	Drop off address. 1 to 500 characters.
drop_lat	number	Có	Drop off point latitude.
drop_lon	number	Có	Drop off point longitude.
drop_date_time	string (date-time)	Có	Start of the drop off window. ISO 8601 date time.
drop_date_time_to	string (date-time)	Có	End of the drop off window. ISO 8601 date time.
rlength	number	Có	Cargo length, in centimetres. 0 or greater.
rwidth	number	Có	Cargo width, in centimetres. 0 or greater.
rheight	number	Có	Cargo height, in centimetres. 0 or greater.
rweight	number	Có	Cargo weight, in kilograms. 0.01 or greater.
count_of_parcels	integer	Có	Number of parcels in this order. 1 or greater.
resource_id	integer	Không	Internal resource identifier, if known. 0 or greater.
distance	number	Không	Known distance for this order, in kilometres, if you have one. 0 or greater.
pickup_wid	integer	Không	Pickup warehouse identifier. 0 or greater.
drop_wid	integer	Không	Drop off warehouse identifier. 0 or greater.
loading_time	integer	Không	Loading time, in minutes. 0 or greater.
unloading_time	integer	Không	Unloading time, in minutes. 0 or greater.
sender_name	string	Không	Sender name. 0 to 200 characters.
sender_phone	string	Không	Sender phone number. 0 to 32 characters.
receiver_name	string	Không	Receiver name. 0 to 200 characters.
receiver_phone	string	Không	Receiver phone number. 0 to 32 characters.

5 trườngCreateRouteOptimizationJobDto

Kết quả trả về

202Public job aggregate committed

400ROUTE_OPT_VALIDATION_ERROR or DUPLICATE_EXTERNAL_ID

409IDEMPOTENCY_CONFLICT, ACTIVE_EXTERNAL_ID_CONFLICT, or JOB_ALREADY_PROCESSING

413ROUTE_OPT_PAYLOAD_TOO_LARGE

429ROUTE_OPT_RATE_LIMITED

Về nhóm: Tối ưu tuyến đường