> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devmob.app.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Routing

> Route preview: polyline, distância e duração sobre uma sequência de Points.

O **Routing** calcula um **preview de rota** sobre uma sequência de [Points](/domain/operations/points): polyline, distância e duração. O resultado serve para visualizar o traçado e estimar distância/tempo antes de cadastrar rotas ou planejar paradas.

<Info>
  Routing **não** grava `distanceKm`/`estimatedDuration` em uma `Route`. Esses valores continuam sendo informados pela empresa no cadastro da rota; o preview é apenas uma ferramenta de apoio.
</Info>

## Entrada

| Campo         | Descrição                        |
| ------------- | -------------------------------- |
| `pointIds`    | 2 a 25 Points, na ordem desejada |
| `vehicleType` | Tipo de veículo usado no preview |

### Validações

| Regra                       | Erro                 |
| --------------------------- | -------------------- |
| Menos de 2 waypoints        | `too_few_waypoints`  |
| Mais de 25 waypoints        | `too_many_waypoints` |
| `pointIds` com duplicatas   | `invalid_point_ids`  |
| Algum `pointId` inexistente | `not_found` (Point)  |

Os Points são carregados e reordenados conforme a ordem de entrada.

## Segmentos e status

O preview percorre pares consecutivos de Points e monta segmentos:

* **`ROUTED`** — para um trecho contínuo de Points **com** coordenadas, devolve `polyline`, `distanceMeters` e `durationSeconds`.
* **`GAP`** — quando um par consecutivo tem algum Point **sem** coordenadas, registra um buraco com `missingPointIds` e `reason: MISSING_COORDINATES`.

```mermaid theme={null}
flowchart LR
    A[Point A<br/>com coords] -->|ROUTED| B[Point B<br/>com coords]
    B -->|GAP MISSING_COORDINATES| C[Point C<br/>sem coords]
    C -->|GAP MISSING_COORDINATES| D[Point D<br/>com coords]
```

O status geral é derivado dos segmentos:

| Status       | Condição                                  |
| ------------ | ----------------------------------------- |
| `COMPLETE`   | Nenhum gap                                |
| `PARTIAL`    | Há gaps e há pelo menos um trecho roteado |
| `UNROUTABLE` | Há gaps e nenhum trecho roteado           |

## Saída (RoutePreview)

| Campo             | Tipo                   | Descrição                                               |
| ----------------- | ---------------------- | ------------------------------------------------------- |
| `vehicleType`     | `'VAN'`                | Tipo de veículo                                         |
| `status`          | RoutePreviewStatus     | `COMPLETE`, `PARTIAL` ou `UNROUTABLE`                   |
| `polyline`        | string?                | Polyline geral (apenas quando `COMPLETE`; senão `null`) |
| `distanceMeters`  | integer                | Soma das distâncias dos trechos roteados                |
| `durationSeconds` | integer                | Soma das durações dos trechos roteados                  |
| `points`          | Point\[]               | Points hidratados, na ordem de entrada                  |
| `segments`        | RoutePreviewSegment\[] | Segmentos `ROUTED` e `GAP`                              |

## Capacidades

| Superfície | Acesso                                  |
| ---------- | --------------------------------------- |
| OPS        | `read:route`, escopado por organização  |
| Customer   | Disponível para preview público de rota |

Ambas recebem `pointIds` e `vehicleType`.

<Note>
  O preview usa roteamento com tráfego e polyline codificada. O mesmo fluxo de mapas atende a busca de [Places](/domain/operations/places).
</Note>