# Viajes

Cotiza una tarifa, solicita un viaje y síguelo hasta el final. Una cotización devuelve la distancia real por carretera, el tiempo de conducción y el precio final por categoría de vehículo, impuestos incluidos: las mismas cifras que muestran las apps de Ryde, porque vienen de la misma ruta de precios.

Cotiza una tarifa, solicita un viaje y síguelo hasta el final. Una cotización devuelve la distancia real por carretera, el tiempo de conducción y el precio final por categoría de vehículo, impuestos incluidos: las mismas cifras que muestran las apps de Ryde, porque vienen de la misma ruta de precios.

## Ciclo de vida

```
  QUOTED
     |
  REQUESTED  -----> no driver found -----> cancelled
     |
  MATCHING           (offers go out to nearby drivers in rounds,
     |                widening the search radius as they lapse)
  DRIVER ASSIGNED
     |
  DRIVER EN ROUTE
     |
  DRIVER ARRIVED
     |
  TRIP STARTED
     |
  COMPLETED                         (or CANCELLED, before it starts)
```

## Operaciones

### `GET /v1/rides/products`

Las categorías de vehículo que se pueden solicitar, con la tarifa base de cada una.

- operation: `search_ride_options`
- scope: `rides.read`
- entitlement: none
- creates a transaction: no
- idempotency key: not required
- MCP tool: `search_ride_options`
- status: planned

```bash
curl -s 'https://sandbox-api.ryde.us.com/v1/rides/products' \
  -H "Authorization: Bearer $RYDE_ACCESS_TOKEN"
```

### `POST /v1/rides/quote`

Distancia por carretera, tiempo de conducción y la tarifa final por categoría de vehículo, impuestos incluidos. Devuelve el quote_id que requiere request_ride.

- operation: `quote_ride`
- scope: `rides.read`
- entitlement: none
- creates a transaction: no
- idempotency key: not required
- MCP tool: `quote_ride`
- status: planned

```bash
curl -sX POST 'https://sandbox-api.ryde.us.com/v1/rides/quote' \
  -H "Authorization: Bearer $RYDE_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{ … }'
```

### `POST /v1/rides`

Solicita el viaje que el cliente confirmó, a partir de un quote_id que se le mostró.

- operation: `request_ride`
- scope: `rides.request`
- entitlement: ryde_one
- creates a transaction: yes
- idempotency key: required
- MCP tool: `request_ride`
- status: planned

```bash
curl -sX POST 'https://sandbox-api.ryde.us.com/v1/rides' \
  -H "Authorization: Bearer $RYDE_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{ … }'
```

### `GET /v1/rides/{ride_id}`

Estado en vivo de un viaje: avance del despacho, el conductor y vehículo asignados, y el tiempo estimado de llegada. Nunca restringido por membresía: un viaje en curso sigue siendo rastreable.

- operation: `get_ride`
- scope: `rides.read`
- entitlement: none
- creates a transaction: no
- idempotency key: not required
- MCP tool: `get_ride`
- status: planned

```bash
curl -s 'https://sandbox-api.ryde.us.com/v1/rides/$ride_id' \
  -H "Authorization: Bearer $RYDE_ACCESS_TOKEN"
```

### `GET /v1/rides`

El historial de viajes del propio cliente, del más reciente al más antiguo.

- operation: `list_rides`
- scope: `rides.read`
- entitlement: none
- creates a transaction: no
- idempotency key: not required
- MCP tool: `list_rides`
- status: planned

```bash
curl -s 'https://sandbox-api.ryde.us.com/v1/rides' \
  -H "Authorization: Bearer $RYDE_ACCESS_TOKEN"
```

### `POST /v1/rides/{ride_id}/cancel`

Cancela un viaje que no ha comenzado. Nunca restringido por membresía, por la misma razón que cancelar un pedido.

- operation: `cancel_ride`
- scope: `rides.read`
- entitlement: none
- creates a transaction: no
- idempotency key: supported
- MCP tool: `cancel_ride`
- status: planned

```bash
curl -sX POST 'https://sandbox-api.ryde.us.com/v1/rides/$ride_id/cancel' \
  -H "Authorization: Bearer $RYDE_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{ … }'
```