# Route Stops _(Realtime-enabled)_

`GET` `POST` `PATCH` `DELETE` _(Table: EONE Route Stop)_

```
eOne/core/v1.0/routeStops
```

Record the ordered stops on a route from an external planner (Stream, Descartes, Maxoptra). Each vehicle's load is a warehouse document, and this adds the sequenced drops, or collections, on top of it.

## The load is the warehouse document

eOne does not plan routes. That stays in the planner (Stream, Descartes, Maxoptra), which assigns the day's orders to vehicles and sequences the stops. This endpoint is the **writeback** of that plan.

A vehicle's load **is** a warehouse document. The route/trip id lives in its `integrationId`, the vehicle in its shipping agent and shipping agent service, the route date in its shipment or receipt date, and the load lifecycle in its native document status. `routeStops` adds only the thing a warehouse document has no native concept of: the **ordered stops**.

There is no separate run or trip entity to keep in step, and nothing to reconcile: the load already exists in Business Central as a document the warehouse works.

## Both directions

The model is bidirectional, and the direction follows from which warehouse document the load is:

| Direction | Load is a | Assembled from | Terminal stop status |
| --- | --- | --- | --- |
| Outbound: the van delivers | [warehouse shipment](https://eonesolutions.github.io/eone-bc-integration/core-warehouseShipments.md) | sales orders | `Delivered` |
| Inbound: the van picks up | [warehouse receipt](https://eonesolutions.github.io/eone-bc-integration/core-warehouseReceipts.md) | sales return orders | `Collected` |

## Addressing the load

Send `parentType` (`warehouseShipment` or `warehouseReceipt`) plus `parentDocumentNumber`. Two shorthand columns do the same job in one field, and read back only for their own direction so you can tell a drop from a collection at a glance:

- `whseShipmentNumber`: sets `parentType` to `warehouseShipment` and `parentDocumentNumber`.
- `whseReceiptNumber`: sets `parentType` to `warehouseReceipt` and `parentDocumentNumber`.

`whseShipmentNumber` is the original column from the outbound-only release and behaves exactly as it did: a payload that sends only `whseShipmentNumber` still creates a delivery stop, because `parentType` defaults to `warehouseShipment`. **No column was renamed** when the endpoint became bidirectional.

> **Note:** `parentType` accepts only the two warehouse values. A stop hanging off a sales order or a customer is meaningless, so any other value is rejected, even though the underlying `parentType` enum is shared with [documentAttachments](https://eonesolutions.github.io/eone-bc-integration/core-documentAttachments.md) and [notes](https://eonesolutions.github.io/eone-bc-integration/core-notes.md) and carries many more values there.

## One stop per address

Grain is by **address**: a stop is a single destination, which may cover several orders handled at the same customer on the same vehicle. POST one stop per drop or collection with:

- The load, as described above.
- `stopSequence`: the order the vehicle drives. Defaults to the stop number if omitted.
- `customerNumber`: the destination.
- `externalStopId` and `plannedArrival`. The planner's own stop id and the ETA.

`stopNumber` is assigned automatically within the load. The load's lines tie back to their stop by destination.

> **Caution:** By-address grain is an **assumption**, not a customer decision. Keying on the order instead was the alternative. It is called out here so it can be revisited before the first live route; changing it later would change what a stop means.

## Updating as the run progresses

Unlike most writeback records, stops are **updatable**: PATCH `stopSequence`, `plannedArrival`, or `status` as the warehouse loads the van and the driver works the run.

`status` is `Planned`, `Loaded`, `Delivered`, or `Collected`. `Loaded` means "on the van" in both directions (at the depot outbound, at the customer inbound). `Delivered` closes an outbound drop; `Collected` closes an inbound pickup.

## Getting a load in the first place

Nothing in Business Central assembles a vehicle load: its own "create a warehouse document" actions work one source document at a time, so calling them per order gives you one warehouse document *per order*, the opposite of a load. Two bound actions do the assembly instead:

- `createDeliveryLoad` on a [sales order](https://eonesolutions.github.io/eone-bc-integration/core-salesOrders.md), one warehouse shipment from several released sales orders.
- `createPickupLoad` on a [sales return order](https://eonesolutions.github.io/eone-bc-integration/core-salesReturnOrders.md), one warehouse receipt from several released sales return orders.

Both are called on the **first** order of the load, with the rest passed as a delimited list, and both stamp the route id, the vehicle, and the route date onto the resulting document. Post the stops against that document once you have it.

## Guardrails

The assemblers enforce a small set of rules. Each is a **default this build chose** while the underlying question is still open with the customer, and each is deliberately strict, because a load that is wrong is worse than a load that was refused:

- **One location per load.** Every outstanding item line of every order in the load must sit on the same location, and that location must require shipment (outbound) or receipt (inbound). Checked on the lines, not the order header, because a line can override the header's location and a load cannot straddle two warehouses.
- **No order split across vehicles.** An order that already carries warehouse shipment or receipt lines is rejected outright rather than partly loaded.
- **Vehicles are shipping agents.** A vehicle is a shipping agent plus a shipping agent service. There is no vehicle master in Business Central and eOne does not add one.
- **Released orders only**, with something still outstanding to load.

## Route Stops fields

_API column → BC field._

**Legend**

- _(req)_ required on create
- _(res)_ resolver
- _(cur)_ currency-translated
- _(ro)_ read-only
- _(ext)_ added to this endpoint by another extension (BC field name shown; its API column name is not known here)

| API | BC field | Notes |
| --- | --- | --- |
| `id` | SystemId | BC record GUID. _(ro)_ |
| `bcCompanyId` | bcCompanyId | The company this row belongs to - the same GUID that appears in the request URL. Present on every endpoint so a store pooling several companies can keep them apart without relying on which URL it called. _(ro)_ |
| `bcCompanyName` | bcCompanyName | The name of the company this row belongs to. _(ro)_ |
| `parentType` | Parent Type | Which warehouse document the load is: warehouseShipment for a delivery run, warehouseReceipt for a pickup run. Defaults to warehouseShipment. |
| `parentDocumentNumber` | Parent Document No. | The warehouse document this stop belongs to - the vehicle's load. Reads as the warehouse shipment or warehouse receipt number, per parentType. _(req)_ |
| `whseShipmentNumber` | whseShipmentNumber | Shorthand for a delivery stop: sets parentType to warehouseShipment and parentDocumentNumber in one column. Blank on read for a pickup stop. See warehouseShipments. |
| `whseReceiptNumber` | whseReceiptNumber | Shorthand for a pickup stop: sets parentType to warehouseReceipt and parentDocumentNumber in one column. Blank on read for a delivery stop. See warehouseReceipts. |
| `stopNumber` | Stop No. | Identifier of the stop within the load; auto-assigned on create. _(ro)_ |
| `stopSequence` | Stop Sequence | The load/drop order the vehicle drives, from the planner. Defaults to the stop number if not sent. |
| `customerNumber` | Customer No. | The destination customer for this drop (by-address grain). |
| `externalStopId` | External Stop Id | The planner's own identifier for the stop, for correlation back to the route. |
| `plannedArrival` | Planned Arrival | Planned arrival time (ETA) at the stop, from the planner. |
| `status` | Status | Planned / Loaded / Delivered / Collected - updated as the vehicle is loaded and driven. Delivered closes an outbound drop, Collected closes an inbound pickup. |
| `lastModifiedDateTime` | SystemModifiedAt | _(ro)_ |

## Related pages

Nested under [Warehouse Shipments](https://eonesolutions.github.io/eone-bc-integration/core-warehouseShipments.md) and [Warehouse Receipts](https://eonesolutions.github.io/eone-bc-integration/core-warehouseReceipts.md).