O Routing calcula um preview de rota sobre uma sequência de 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.
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.
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) |
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.
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 |
pointIds e vehicleType.
O preview usa roteamento com tráfego e polyline codificada. O mesmo fluxo de mapas atende a busca de Places. 
