Pular para o conteúdo principal
Routal
API ReferencePlan

Optimize a plan

Triggers the Routal optimizer for this plan.

POST
/v2/plan/{id}/optimize

Triggers the Routal optimizer for this plan. Stops are assigned to vehicles, ordered, and the ETA, distance and load of every route are recomputed.

By default, all routes are rebuilt — stops may move between vehicles. Routes flagged as is_locked are always preserved and excluded from re-optimization.

Pass keep_current_assignment=true to keep each stop on its currently assigned route and only re-sequence stops within that route (useful when a driver has already started or when you want to lock the assignment).

Most calls are synchronous — the response contains the optimized plan. Very large plans fall back to an asynchronous run; progress can be polled at GET /v2/plan/{id}/running_optimization, or subscribe to webhooks for push notifications.

Constraints respected by the optimizer: time windows, service duration per stop, vehicle capacities (weight / volume / units), required vs. provided skills (stop requires matched against vehicle provides), route time windows, break times, route start / end locations and geo-fenced zones.

Authorization

api_key
private_key<token>

The Routal API authenticates requests with an API key passed as the private_key query string parameter. Generate and rotate your keys from the Developer Settings section of your Routal workspace.Never ship API keys to a browser or mobile app — they must stay server-side.

In: query

Path Parameters

id*string

Plan ID

Match^[0-9a-f]{24}

Query Parameters

keep_current_assignment?boolean

When true, stops stay on their currently assigned route and only the in-route sequence is re-optimized. Use this once dispatch has started.

Defaultfalse

Response Body

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v2/plan/string/optimize"
{
  "id": "4f75d991ac359f8c4c79d762",
  "organization_id": "4f75d991ac359f8c4c79d762",
  "project_id": "4f75d991ac359f8c4c79d762",
  "completed_stops": 1,
  "canceled_stops": 2,
  "pending_stops": 3,
  "incomplete_stops": 3,
  "total_stops": 6,
  "total_routes": 5,
  "label": "Eixample route — 2026-05-21",
  "execution_date": "2026-05-29T14:55:24.518Z",
  "status": "planning",
  "created_by": "4f75d991ac359f8c4c79d762",
  "created_at": "2026-05-29T14:55:24.518Z",
  "updated_at": "2026-05-29T14:55:24.518Z",
  "deleted_at": "2026-05-29T14:55:24.518Z",
  "deleted": true,
  "stops": [
    {
      "id": "4f75d991ac359f8c4c79d762",
      "fixed_id": "1",
      "organization_id": "4f75d991ac359f8c4c79d762",
      "project_id": "4f75d991ac359f8c4c79d762",
      "plan_id": "4f75d991ac359f8c4c79d762",
      "type": "delivery",
      "route_id": "4f75d991ac359f8c4c79d762",
      "vehicle_id": "4f75d991ac359f8c4c79d762",
      "client_id": "4f75d991ac359f8c4c79d762",
      "client_external_id": "CUST-58291",
      "external_id": "ORD-2026-58291",
      "location": {
        "location_id": "4f75d991ac359f8c4c79d762",
        "label": "Location label",
        "country": "Spain",
        "country_code": "ES",
        "state": "Catalonia",
        "city": "Barcelona",
        "street": "Calle de Pau Claris",
        "postal_code": "08302",
        "comments": "Location comments",
        "lat": 40.45,
        "lng": -3.68,
        "main_text": "Calle de Pau Claris 12",
        "secondary_text": "Barcelona, Catalonia, Spain"
      },
      "location_details": "Local 2, junto a la entrada principal",
      "label": "Acme Pharmacy — Aragó branch",
      "comments": "Ring intercom 2B. Do not leave at reception.",
      "phone": "+34612345678",
      "email": "sarah.johnson@example.com",
      "url": "https://shop.example.com/orders/58291",
      "reference_person": "Sarah Johnson",
      "duration": 180,
      "requires": [
        "refrigerated",
        "fragile"
      ],
      "cluster": "eixample-norte",
      "reward": 5,
      "time_windows": [
        [
          28800,
          61200
        ]
      ],
      "volume": 0.12,
      "weight": 8.4,
      "max_delivery_time": 7200,
      "status": "pending",
      "plan_execution_date": "2026-05-29T14:55:24.491Z",
      "order": 0,
      "planned_arrival_time": 29500,
      "planned_departure_time": 30000,
      "estimated_arrival_time": "2026-05-29T14:55:24.491Z",
      "estimated_departure_time": "2026-05-29T14:55:24.491Z",
      "pickup_id": "4f75d991ac359f8c4c79d762",
      "distance_to_previous_stop": 30000,
      "distance_to_next_stop": 20000,
      "optimization_warning": true,
      "chain_id": "order-58291",
      "chain_position": 1,
      "custom_fields": {
        "order_reference": "ORD-2026-58291",
        "parcel_count": 2,
        "cod_amount": 24.9
      },
      "tasks": [
        {
          "id": "4f75d991ac359f8c4c79d762",
          "stop_id": "4f75d991ac359f8c4c79d762",
          "label": "Deliver refrigerated parcel 1/2",
          "comments": "Keep cold chain. Weight 12.4 kg.",
          "barcode": "8410076472158",
          "status": "completed",
          "custom_fields": {
            "sku": "SKU-4582",
            "quantity": 2,
            "lot_number": "L-2026-038"
          },
          "created_by": "4f75d991ac359f8c4c79d762",
          "created_at": "2026-05-29T14:55:24.485Z",
          "updated_at": "2026-05-29T14:55:24.485Z",
          "deleted_at": "2026-05-29T14:55:24.485Z"
        }
      ],
      "reports": [
        {
          "id": "4f75d991ac359f8c4c79d762",
          "stop_id": "4f75d991ac359f8c4c79d762",
          "route_id": "4f75d991ac359f8c4c79d762",
          "project_id": "4f75d991ac359f8c4c79d762",
          "plan_id": "4f75d991ac359f8c4c79d762",
          "type": "service_report_completed",
          "comments": "Customer not present. Notice left in the mailbox.",
          "images": [
            {
              "id": "4f75d991ac359f8c4c79d762",
              "url": "https://api.routal.com"
            }
          ],
          "signature": {
            "id": "4f75d991ac359f8c4c79d762",
            "url": "https://api.routal.com"
          },
          "tasks": [
            {
              "task_id": "4f75d991ac359f8c4c79d762",
              "status": "completed",
              "comments": "Parcel delivered in perfect condition.",
              "custom_fields": {
                "sku": "SKU-4582",
                "quantity": 2,
                "lot_number": "L-2026-038"
              }
            }
          ],
          "cancel_reason": "nobody",
          "location": {
            "location_id": "4f75d991ac359f8c4c79d762",
            "label": "Location label",
            "country": "Spain",
            "country_code": "ES",
            "state": "Catalonia",
            "city": "Barcelona",
            "street": "Calle de Pau Claris",
            "postal_code": "08302",
            "comments": "Location comments",
            "lat": 40.45,
            "lng": -3.68,
            "main_text": "Calle de Pau Claris 12",
            "secondary_text": "Barcelona, Catalonia, Spain"
          },
          "time_in_stop": 180,
          "custom_fields": {
            "delivered_to": "neighbor 2A",
            "cod_collected": 24.9,
            "photo_count": 2
          },
          "created_at": "2026-05-29T14:55:24.486Z"
        }
      ],
      "report_attempts": 2,
      "survey": {
        "stop_id": "4f75d991ac359f8c4c79d762",
        "route_id": "4f75d991ac359f8c4c79d762",
        "rating": 1,
        "rating_tag": "time",
        "comments": "The delivery was very professional and punctual.",
        "created_at": "2026-05-29T14:55:24.489Z",
        "updated_at": "2026-05-29T14:55:24.489Z"
      },
      "pin": "4729",
      "customer_text_field": "Leave at reception if I'm not home.",
      "supervisors": [
        "4f75d991ac359f8c4c79d762"
      ],
      "location_validation_sent": false,
      "location_validation_sent_at": "2026-05-29T14:55:24.499Z",
      "location_validated": false,
      "location_validated_at": "2026-05-29T14:55:24.500Z",
      "created_by": "4f75d991ac359f8c4c79d762",
      "created_at": "2026-05-29T14:55:24.339Z",
      "updated_at": "2026-05-29T14:55:24.339Z",
      "deleted_at": "2026-05-29T14:55:24.339Z",
      "deleted": true,
      "pickup": {
        "id": "4f75d991ac359f8c4c79d762",
        "fixed_id": "1",
        "organization_id": "4f75d991ac359f8c4c79d762",
        "project_id": "4f75d991ac359f8c4c79d762",
        "plan_id": "4f75d991ac359f8c4c79d762",
        "type": "delivery",
        "route_id": "4f75d991ac359f8c4c79d762",
        "vehicle_id": "4f75d991ac359f8c4c79d762",
        "client_id": "4f75d991ac359f8c4c79d762",
        "client_external_id": "CUST-58291",
        "external_id": "ORD-2026-58291",
        "location": {
          "location_id": "4f75d991ac359f8c4c79d762",
          "label": "Location label",
          "country": "Spain",
          "country_code": "ES",
          "state": "Catalonia",
          "city": "Barcelona",
          "street": "Calle de Pau Claris",
          "postal_code": "08302",
          "comments": "Location comments",
          "lat": 40.45,
          "lng": -3.68,
          "main_text": "Calle de Pau Claris 12",
          "secondary_text": "Barcelona, Catalonia, Spain"
        },
        "location_details": "Local 2, junto a la entrada principal",
        "label": "Acme Pharmacy — Aragó branch",
        "comments": "Ring intercom 2B. Do not leave at reception.",
        "phone": "+34612345678",
        "email": "sarah.johnson@example.com",
        "url": "https://shop.example.com/orders/58291",
        "reference_person": "Sarah Johnson",
        "duration": 180,
        "requires": [
          "refrigerated",
          "fragile"
        ],
        "cluster": "eixample-norte",
        "reward": 5,
        "time_windows": [
          [
            28800,
            61200
          ]
        ],
        "volume": 0.12,
        "weight": 8.4,
        "max_delivery_time": 7200,
        "status": "pending",
        "plan_execution_date": "2026-05-29T14:55:24.491Z",
        "order": 0,
        "planned_arrival_time": 29500,
        "planned_departure_time": 30000,
        "estimated_arrival_time": "2026-05-29T14:55:24.491Z",
        "estimated_departure_time": "2026-05-29T14:55:24.491Z",
        "pickup_id": "4f75d991ac359f8c4c79d762",
        "distance_to_previous_stop": 30000,
        "distance_to_next_stop": 20000,
        "optimization_warning": true,
        "chain_id": "order-58291",
        "chain_position": 1,
        "custom_fields": {
          "order_reference": "ORD-2026-58291",
          "parcel_count": 2,
          "cod_amount": 24.9
        },
        "tasks": [
          {
            "id": "4f75d991ac359f8c4c79d762",
            "stop_id": "4f75d991ac359f8c4c79d762",
            "label": "Deliver refrigerated parcel 1/2",
            "comments": "Keep cold chain. Weight 12.4 kg.",
            "barcode": "8410076472158",
            "status": "completed",
            "custom_fields": {
              "sku": "SKU-4582",
              "quantity": 2,
              "lot_number": "L-2026-038"
            },
            "created_by": "4f75d991ac359f8c4c79d762",
            "created_at": "2026-05-29T14:55:24.485Z",
            "updated_at": "2026-05-29T14:55:24.485Z",
            "deleted_at": "2026-05-29T14:55:24.485Z"
          }
        ],
        "reports": [
          {
            "id": "4f75d991ac359f8c4c79d762",
            "stop_id": "4f75d991ac359f8c4c79d762",
            "route_id": "4f75d991ac359f8c4c79d762",
            "project_id": "4f75d991ac359f8c4c79d762",
            "plan_id": "4f75d991ac359f8c4c79d762",
            "type": "service_report_completed",
            "comments": "Customer not present. Notice left in the mailbox.",
            "images": [
              {
                "id": "4f75d991ac359f8c4c79d762",
                "url": "https://api.routal.com"
              }
            ],
            "signature": {
              "id": "4f75d991ac359f8c4c79d762",
              "url": "https://api.routal.com"
            },
            "tasks": [
              {
                "task_id": "4f75d991ac359f8c4c79d762",
                "status": "completed",
                "comments": "Parcel delivered in perfect condition.",
                "custom_fields": {
                  "sku": "SKU-4582",
                  "quantity": 2,
                  "lot_number": "L-2026-038"
                }
              }
            ],
            "cancel_reason": "nobody",
            "location": {
              "location_id": "4f75d991ac359f8c4c79d762",
              "label": "Location label",
              "country": "Spain",
              "country_code": "ES",
              "state": "Catalonia",
              "city": "Barcelona",
              "street": "Calle de Pau Claris",
              "postal_code": "08302",
              "comments": "Location comments",
              "lat": 40.45,
              "lng": -3.68,
              "main_text": "Calle de Pau Claris 12",
              "secondary_text": "Barcelona, Catalonia, Spain"
            },
            "time_in_stop": 180,
            "custom_fields": {
              "delivered_to": "neighbor 2A",
              "cod_collected": 24.9,
              "photo_count": 2
            },
            "created_at": "2026-05-29T14:55:24.486Z"
          }
        ],
        "report_attempts": 2,
        "survey": {
          "stop_id": "4f75d991ac359f8c4c79d762",
          "route_id": "4f75d991ac359f8c4c79d762",
          "rating": 1,
          "rating_tag": "time",
          "comments": "The delivery was very professional and punctual.",
          "created_at": "2026-05-29T14:55:24.489Z",
          "updated_at": "2026-05-29T14:55:24.489Z"
        },
        "pin": "4729",
        "customer_text_field": "Leave at reception if I'm not home.",
        "supervisors": [
          "4f75d991ac359f8c4c79d762"
        ],
        "location_validation_sent": false,
        "location_validation_sent_at": "2026-05-29T14:55:24.499Z",
        "location_validated": false,
        "location_validated_at": "2026-05-29T14:55:24.500Z",
        "created_by": "4f75d991ac359f8c4c79d762",
        "created_at": "2026-05-29T14:55:24.339Z",
        "updated_at": "2026-05-29T14:55:24.339Z",
        "deleted_at": "2026-05-29T14:55:24.339Z",
        "deleted": true
      }
    }
  ],
  "routes": [
    {
      "id": "4f75d991ac359f8c4c79d762",
      "project_id": "4f75d991ac359f8c4c79d762",
      "plan_id": "4f75d991ac359f8c4c79d762",
      "vehicle_id": "4f75d991ac359f8c4c79d762",
      "external_id": "ROUTE-2026-05-21-MAD03",
      "start_location": {
        "location_id": "4f75d991ac359f8c4c79d762",
        "label": "Location label",
        "country": "Spain",
        "country_code": "ES",
        "state": "Catalonia",
        "city": "Barcelona",
        "street": "Calle de Pau Claris",
        "postal_code": "08302",
        "comments": "Location comments",
        "lat": 40.45,
        "lng": -3.68,
        "main_text": "Calle de Pau Claris 12",
        "secondary_text": "Barcelona, Catalonia, Spain"
      },
      "end_location": {
        "location_id": "4f75d991ac359f8c4c79d762",
        "label": "Location label",
        "country": "Spain",
        "country_code": "ES",
        "state": "Catalonia",
        "city": "Barcelona",
        "street": "Calle de Pau Claris",
        "postal_code": "08302",
        "comments": "Location comments",
        "lat": 40.45,
        "lng": -3.68,
        "main_text": "Calle de Pau Claris 12",
        "secondary_text": "Barcelona, Catalonia, Spain"
      },
      "label": "Eixample route — Refrigerated van 02",
      "phone": "+34612345678",
      "comments": "Load at 06:00 at dock 4. Depart 06:30.",
      "email": "carlos.lopez@example.com",
      "plate": "2596 KHO",
      "vehicle_model": "Transit Custom L2H2",
      "color": "#1E88E5",
      "brand": "Ford",
      "vehicle": {
        "fuel_type": "diesel",
        "consumption": 8,
        "break": {
          "start": 43200,
          "end": 54000,
          "duration": 2700
        }
      },
      "planned_track": "spxsBsdb|Lymo`qvAx@TKvAr@K",
      "is_locked": true,
      "geo_fences": [
        "4f75d991ac359f8c4c79d762"
      ],
      "time_window": [
        28800,
        61200
      ],
      "max_distance": 120000,
      "min_distance": 5000,
      "max_time": 28800,
      "min_time": 3600,
      "max_weight": 800,
      "max_volume": 8,
      "max_services": 40,
      "provides": [
        "refrigerated",
        "lift_gate"
      ],
      "order": 0,
      "start_date": "2026-05-29T14:55:24.509Z",
      "end_date": "2026-05-29T14:55:24.509Z",
      "estimated_end_time": "2026-05-29T14:55:24.509Z",
      "last_position": {
        "lat": 40.45,
        "lng": -3.68,
        "created_at": "2026-05-29T14:55:24.508Z",
        "orientation": 270
      },
      "planned_start_time": 23400,
      "planned_end_time": 50400,
      "custom_fields": {},
      "distance_traveled": 0,
      "tracing_percent": 0,
      "price_per_minute": 0.0035,
      "price_per_distance": 0.00045,
      "toll_price": 4.8,
      "toll_price_currency": "EUR",
      "status": "not_started",
      "created_by": "4f75d991ac359f8c4c79d762",
      "created_at": "2026-05-29T14:55:24.339Z",
      "updated_at": "2026-05-29T14:55:24.339Z",
      "deleted_at": "2026-05-29T14:55:24.339Z",
      "deleted": true,
      "stops": [
        {
          "id": "4f75d991ac359f8c4c79d762",
          "fixed_id": "1",
          "organization_id": "4f75d991ac359f8c4c79d762",
          "project_id": "4f75d991ac359f8c4c79d762",
          "plan_id": "4f75d991ac359f8c4c79d762",
          "type": "delivery",
          "route_id": "4f75d991ac359f8c4c79d762",
          "vehicle_id": "4f75d991ac359f8c4c79d762",
          "client_id": "4f75d991ac359f8c4c79d762",
          "client_external_id": "CUST-58291",
          "external_id": "ORD-2026-58291",
          "location": {
            "location_id": "4f75d991ac359f8c4c79d762",
            "label": "Location label",
            "country": "Spain",
            "country_code": "ES",
            "state": "Catalonia",
            "city": "Barcelona",
            "street": "Calle de Pau Claris",
            "postal_code": "08302",
            "comments": "Location comments",
            "lat": 40.45,
            "lng": -3.68,
            "main_text": "Calle de Pau Claris 12",
            "secondary_text": "Barcelona, Catalonia, Spain"
          },
          "location_details": "Local 2, junto a la entrada principal",
          "label": "Acme Pharmacy — Aragó branch",
          "comments": "Ring intercom 2B. Do not leave at reception.",
          "phone": "+34612345678",
          "email": "sarah.johnson@example.com",
          "url": "https://shop.example.com/orders/58291",
          "reference_person": "Sarah Johnson",
          "duration": 180,
          "requires": [
            "refrigerated",
            "fragile"
          ],
          "cluster": "eixample-norte",
          "reward": 5,
          "time_windows": [
            [
              28800,
              61200
            ]
          ],
          "volume": 0.12,
          "weight": 8.4,
          "max_delivery_time": 7200,
          "status": "pending",
          "plan_execution_date": "2026-05-29T14:55:24.491Z",
          "order": 0,
          "planned_arrival_time": 29500,
          "planned_departure_time": 30000,
          "estimated_arrival_time": "2026-05-29T14:55:24.491Z",
          "estimated_departure_time": "2026-05-29T14:55:24.491Z",
          "pickup_id": "4f75d991ac359f8c4c79d762",
          "distance_to_previous_stop": 30000,
          "distance_to_next_stop": 20000,
          "optimization_warning": true,
          "chain_id": "order-58291",
          "chain_position": 1,
          "custom_fields": {
            "order_reference": "ORD-2026-58291",
            "parcel_count": 2,
            "cod_amount": 24.9
          },
          "tasks": [
            {
              "id": "4f75d991ac359f8c4c79d762",
              "stop_id": "4f75d991ac359f8c4c79d762",
              "label": "Deliver refrigerated parcel 1/2",
              "comments": "Keep cold chain. Weight 12.4 kg.",
              "barcode": "8410076472158",
              "status": "completed",
              "custom_fields": {
                "sku": "SKU-4582",
                "quantity": 2,
                "lot_number": "L-2026-038"
              },
              "created_by": "4f75d991ac359f8c4c79d762",
              "created_at": "2026-05-29T14:55:24.485Z",
              "updated_at": "2026-05-29T14:55:24.485Z",
              "deleted_at": "2026-05-29T14:55:24.485Z"
            }
          ],
          "reports": [
            {
              "id": "4f75d991ac359f8c4c79d762",
              "stop_id": "4f75d991ac359f8c4c79d762",
              "route_id": "4f75d991ac359f8c4c79d762",
              "project_id": "4f75d991ac359f8c4c79d762",
              "plan_id": "4f75d991ac359f8c4c79d762",
              "type": "service_report_completed",
              "comments": "Customer not present. Notice left in the mailbox.",
              "images": [
                {
                  "id": "4f75d991ac359f8c4c79d762",
                  "url": "https://api.routal.com"
                }
              ],
              "signature": {
                "id": "4f75d991ac359f8c4c79d762",
                "url": "https://api.routal.com"
              },
              "tasks": [
                {
                  "task_id": "4f75d991ac359f8c4c79d762",
                  "status": "completed",
                  "comments": "Parcel delivered in perfect condition.",
                  "custom_fields": {
                    "sku": "SKU-4582",
                    "quantity": 2,
                    "lot_number": "L-2026-038"
                  }
                }
              ],
              "cancel_reason": "nobody",
              "location": {
                "location_id": "4f75d991ac359f8c4c79d762",
                "label": "Location label",
                "country": "Spain",
                "country_code": "ES",
                "state": "Catalonia",
                "city": "Barcelona",
                "street": "Calle de Pau Claris",
                "postal_code": "08302",
                "comments": "Location comments",
                "lat": 40.45,
                "lng": -3.68,
                "main_text": "Calle de Pau Claris 12",
                "secondary_text": "Barcelona, Catalonia, Spain"
              },
              "time_in_stop": 180,
              "custom_fields": {
                "delivered_to": "neighbor 2A",
                "cod_collected": 24.9,
                "photo_count": 2
              },
              "created_at": "2026-05-29T14:55:24.486Z"
            }
          ],
          "report_attempts": 2,
          "survey": {
            "stop_id": "4f75d991ac359f8c4c79d762",
            "route_id": "4f75d991ac359f8c4c79d762",
            "rating": 1,
            "rating_tag": "time",
            "comments": "The delivery was very professional and punctual.",
            "created_at": "2026-05-29T14:55:24.489Z",
            "updated_at": "2026-05-29T14:55:24.489Z"
          },
          "pin": "4729",
          "customer_text_field": "Leave at reception if I'm not home.",
          "supervisors": [
            "4f75d991ac359f8c4c79d762"
          ],
          "location_validation_sent": false,
          "location_validation_sent_at": "2026-05-29T14:55:24.499Z",
          "location_validated": false,
          "location_validated_at": "2026-05-29T14:55:24.500Z",
          "created_by": "4f75d991ac359f8c4c79d762",
          "created_at": "2026-05-29T14:55:24.339Z",
          "updated_at": "2026-05-29T14:55:24.339Z",
          "deleted_at": "2026-05-29T14:55:24.339Z",
          "deleted": true,
          "pickup": {
            "id": "4f75d991ac359f8c4c79d762",
            "fixed_id": "1",
            "organization_id": "4f75d991ac359f8c4c79d762",
            "project_id": "4f75d991ac359f8c4c79d762",
            "plan_id": "4f75d991ac359f8c4c79d762",
            "type": "delivery",
            "route_id": "4f75d991ac359f8c4c79d762",
            "vehicle_id": "4f75d991ac359f8c4c79d762",
            "client_id": "4f75d991ac359f8c4c79d762",
            "client_external_id": "CUST-58291",
            "external_id": "ORD-2026-58291",
            "location": {
              "location_id": "4f75d991ac359f8c4c79d762",
              "label": "Location label",
              "country": "Spain",
              "country_code": "ES",
              "state": "Catalonia",
              "city": "Barcelona",
              "street": "Calle de Pau Claris",
              "postal_code": "08302",
              "comments": "Location comments",
              "lat": 40.45,
              "lng": -3.68,
              "main_text": "Calle de Pau Claris 12",
              "secondary_text": "Barcelona, Catalonia, Spain"
            },
            "location_details": "Local 2, junto a la entrada principal",
            "label": "Acme Pharmacy — Aragó branch",
            "comments": "Ring intercom 2B. Do not leave at reception.",
            "phone": "+34612345678",
            "email": "sarah.johnson@example.com",
            "url": "https://shop.example.com/orders/58291",
            "reference_person": "Sarah Johnson",
            "duration": 180,
            "requires": [
              "refrigerated",
              "fragile"
            ],
            "cluster": "eixample-norte",
            "reward": 5,
            "time_windows": [
              [
                28800,
                61200
              ]
            ],
            "volume": 0.12,
            "weight": 8.4,
            "max_delivery_time": 7200,
            "status": "pending",
            "plan_execution_date": "2026-05-29T14:55:24.491Z",
            "order": 0,
            "planned_arrival_time": 29500,
            "planned_departure_time": 30000,
            "estimated_arrival_time": "2026-05-29T14:55:24.491Z",
            "estimated_departure_time": "2026-05-29T14:55:24.491Z",
            "pickup_id": "4f75d991ac359f8c4c79d762",
            "distance_to_previous_stop": 30000,
            "distance_to_next_stop": 20000,
            "optimization_warning": true,
            "chain_id": "order-58291",
            "chain_position": 1,
            "custom_fields": {
              "order_reference": "ORD-2026-58291",
              "parcel_count": 2,
              "cod_amount": 24.9
            },
            "tasks": [
              {
                "id": "4f75d991ac359f8c4c79d762",
                "stop_id": "4f75d991ac359f8c4c79d762",
                "label": "Deliver refrigerated parcel 1/2",
                "comments": "Keep cold chain. Weight 12.4 kg.",
                "barcode": "8410076472158",
                "status": "completed",
                "custom_fields": {
                  "sku": "SKU-4582",
                  "quantity": 2,
                  "lot_number": "L-2026-038"
                },
                "created_by": "4f75d991ac359f8c4c79d762",
                "created_at": "2026-05-29T14:55:24.485Z",
                "updated_at": "2026-05-29T14:55:24.485Z",
                "deleted_at": "2026-05-29T14:55:24.485Z"
              }
            ],
            "reports": [
              {
                "id": "4f75d991ac359f8c4c79d762",
                "stop_id": "4f75d991ac359f8c4c79d762",
                "route_id": "4f75d991ac359f8c4c79d762",
                "project_id": "4f75d991ac359f8c4c79d762",
                "plan_id": "4f75d991ac359f8c4c79d762",
                "type": "service_report_completed",
                "comments": "Customer not present. Notice left in the mailbox.",
                "images": [
                  {
                    "id": "4f75d991ac359f8c4c79d762",
                    "url": "https://api.routal.com"
                  }
                ],
                "signature": {
                  "id": "4f75d991ac359f8c4c79d762",
                  "url": "https://api.routal.com"
                },
                "tasks": [
                  {
                    "task_id": "4f75d991ac359f8c4c79d762",
                    "status": "completed",
                    "comments": "Parcel delivered in perfect condition.",
                    "custom_fields": {
                      "sku": "SKU-4582",
                      "quantity": 2,
                      "lot_number": "L-2026-038"
                    }
                  }
                ],
                "cancel_reason": "nobody",
                "location": {
                  "location_id": "4f75d991ac359f8c4c79d762",
                  "label": "Location label",
                  "country": "Spain",
                  "country_code": "ES",
                  "state": "Catalonia",
                  "city": "Barcelona",
                  "street": "Calle de Pau Claris",
                  "postal_code": "08302",
                  "comments": "Location comments",
                  "lat": 40.45,
                  "lng": -3.68,
                  "main_text": "Calle de Pau Claris 12",
                  "secondary_text": "Barcelona, Catalonia, Spain"
                },
                "time_in_stop": 180,
                "custom_fields": {
                  "delivered_to": "neighbor 2A",
                  "cod_collected": 24.9,
                  "photo_count": 2
                },
                "created_at": "2026-05-29T14:55:24.486Z"
              }
            ],
            "report_attempts": 2,
            "survey": {
              "stop_id": "4f75d991ac359f8c4c79d762",
              "route_id": "4f75d991ac359f8c4c79d762",
              "rating": 1,
              "rating_tag": "time",
              "comments": "The delivery was very professional and punctual.",
              "created_at": "2026-05-29T14:55:24.489Z",
              "updated_at": "2026-05-29T14:55:24.489Z"
            },
            "pin": "4729",
            "customer_text_field": "Leave at reception if I'm not home.",
            "supervisors": [
              "4f75d991ac359f8c4c79d762"
            ],
            "location_validation_sent": false,
            "location_validation_sent_at": "2026-05-29T14:55:24.499Z",
            "location_validated": false,
            "location_validated_at": "2026-05-29T14:55:24.500Z",
            "created_by": "4f75d991ac359f8c4c79d762",
            "created_at": "2026-05-29T14:55:24.339Z",
            "updated_at": "2026-05-29T14:55:24.339Z",
            "deleted_at": "2026-05-29T14:55:24.339Z",
            "deleted": true
          }
        }
      ],
      "break_stop": {
        "is_completed": false,
        "order": 2,
        "planned_start_time": 20000,
        "planned_end_time": 30000,
        "real_start_time": 20000,
        "real_end_time": 30000
      }
    }
  ]
}
{
  "message": "Domain not found",
  "message_id": "highway.domain.error.not_found"
}
Empty
{
  "message": "Domain not found",
  "message_id": "highway.domain.error.not_found"
}
{
  "message": "Domain not found",
  "message_id": "highway.domain.error.not_found"
}
Empty
Empty

Create a plan

Creates a new plan inside the given project.

List and search vehicles

Returns a paginated, sortable list of the vehicles available in a project.