# Bettermile Route API

Part of Bettermile API responsible for tour management.

## Typical lifecycle
1. **Create a tour** (`POST /v1/tours`) for a given date, assignment (vehicle / route / driver) and depot. Bettermile looks up the jobs associated with that assignment from Data Gateway.
2. **Create a sequence** (`POST /v1/tours/{tourId}/sequences`) to get an optimised order of waypoints for the respective tour. Sequence creation is synchronous — the returned `sequenceId` is usable immediately to fetch the full sequence via `GET /v1/tours/{tourId}/sequences/{sequenceId}` or `GET /v1/tours/{tourId}/sequences/latest`.
3. (optional) **Track and adjust the tour as it's driven**: pin or unpin a waypoint's timeframe or stop time when it needs to be fixed against automatic recalculation, and report job status changes (`POST /v1/tours/{tourId}/jobs/statuses`) as an auxiliary channel alongside the DataGateWay connector updates.
4. (optional) **Custom jobs and waypoints** (`Custom Job` / `Custom Waypoint` tags) let you add a job to a tour that wasn't provided via DataGateway, and group jobs into a waypoint manually.

All endpoints share a single `x-api-key` for authentication and a general per-customer rate limit (see the `429` response on each operation).

Version: 1.0.0
License: Proprietary

## Servers

Dev API
```
https://dev.routes.bettermile.com
```

## Security

### ApiKeyAuth

Type: apiKey
In: header
Name: x-api-key

## Download OpenAPI description

 - [Bettermile Route API](https://docs.bettermile.com/_bundle/products/route/apis/ntc/@1.0/tour-commander-api.yaml)

## Tour

 - [POST /v1/tours](https://docs.bettermile.com/products/route/apis/ntc/tour-commander-api/tour/createtour.md)
 - [GET /v1/tours](https://docs.bettermile.com/products/route/apis/ntc/tour-commander-api/tour/gettours.md)
 - [GET /v1/tours/{tourId}](https://docs.bettermile.com/products/route/apis/ntc/tour-commander-api/tour/gettourbyid.md)
 - [PUT /v1/tours/{tourId}/destination](https://docs.bettermile.com/products/route/apis/ntc/tour-commander-api/tour/settourdestination.md)
 - [GET /v1/tours/{tourId}/potential-recalc-gain](https://docs.bettermile.com/products/route/apis/ntc/tour-commander-api/tour/getpotentialrecalcgain.md): Get potential recalculation gain for tour - how much time could be save, if instead of a fixed optimisation sequence update a full optimsation sequence update is done instead. Recommended for tours
## Sequence

 - [POST /v1/tours/{tourId}/sequences](https://docs.bettermile.com/products/route/apis/ntc/tour-commander-api/sequence/createsequence.md): Creates a new sequence synchronously. The returned sequenceId is usable immediately to fetch the full sequence via GET .../sequences/{sequenceId} or GET .../sequences/latest.
 - [GET /v1/tours/{tourId}/sequences](https://docs.bettermile.com/products/route/apis/ntc/tour-commander-api/sequence/getsequences.md)
 - [GET /v1/tours/{tourId}/sequences/latest](https://docs.bettermile.com/products/route/apis/ntc/tour-commander-api/sequence/getlatestsequence.md)
 - [GET /v1/tours/{tourId}/sequences/{sequenceId}](https://docs.bettermile.com/products/route/apis/ntc/tour-commander-api/sequence/getsequencebyid.md)
## Waypoint

 - [PUT /v1/tours/{tourId}/waypoints/{waypointId}/time-frame](https://docs.bettermile.com/products/route/apis/ntc/tour-commander-api/waypoint/pinwaypointtimeframe.md): Pins the provided timeframe to the waypoint. If the provided timeframe is NULL, the current waypoint timeframe will be removed if present. Calling this endpoint, even with the NULL timeframe, prevents
 - [PUT /v1/tours/{tourId}/waypoints/{waypointId}/stop-time](https://docs.bettermile.com/products/route/apis/ntc/tour-commander-api/waypoint/pinwaypointstoptime.md): Pins the provided stop time value to the waypoint. Calling this endpoint "freezes" the stop time of the waypoint at provided value.
 - [DELETE /v1/tours/{tourId}/waypoints/{waypointId}/stop-time](https://docs.bettermile.com/products/route/apis/ntc/tour-commander-api/waypoint/unpinwaypointstoptime.md): Removes the previously pinned stop time value from the waypoint. Calling this endpoint "unfreezes" the stop time of the waypoint, allowing for the stop time value to be to dynamically calculated.
## Job

 - [POST /v1/tours/{tourId}/jobs/statuses](https://docs.bettermile.com/products/route/apis/ntc/tour-commander-api/job/applyjobstatuschanges.md): Updates the status of one of more jobs, so that these changes can be reflected upon the tour instantly. This is only an auxiliary way for providing Bettermile with job updates, while the main job upda
## Custom Job

 - [POST /v1/tours/{tourId}/custom-jobs](https://docs.bettermile.com/products/route/apis/ntc/tour-commander-api/custom-job/createcustomjob.md): Creates a custom job
 - [DELETE /v1/tours/{tourId}/custom-jobs/{jobId}](https://docs.bettermile.com/products/route/apis/ntc/tour-commander-api/custom-job/deletecustomjob.md): Deletes a custom job
## Custom Waypoint

 - [POST /v1/tours/{tourId}/custom-waypoints](https://docs.bettermile.com/products/route/apis/ntc/tour-commander-api/custom-waypoint/createcustomwaypoint.md): Creates a custom waypoint by grouping provided jobs together
 - [DELETE /v1/tours/{tourId}/custom-waypoints/{waypointId}](https://docs.bettermile.com/products/route/apis/ntc/tour-commander-api/custom-waypoint/deletecustomwaypoint.md): Deletes a custom waypoint, allowing the backend to regroup the jobs from this waypoint freely.