# Transporte

Entrega paquetes a Ryde para que los reparta. Esta es la superficie que un operador logístico o un marketplace integra una vez y luego olvida: consulta si un código postal tiene cobertura, envía un manifiesto de hasta 500 paquetes en una sola solicitud y sigue cada uno por su número de rastreo de Ryde hasta que se entregue, se rechace o se devuelva. Cada paquete responde con el mismo vocabulario de siete estados que espera un agregador de rastreo, así que el flujo que construyas aquí es el que tus clientes ya saben leer. El acceso requiere una organización transportista aprobada con un Acuerdo de Transporte de Ryde firmado; los precios vienen de la tarifa de ese acuerdo, no de una cotización por solicitud.

Entrega paquetes a Ryde para que los reparta. Esta es la superficie que un operador logístico o un marketplace integra una vez y luego olvida: consulta si un código postal tiene cobertura, envía un manifiesto de hasta 500 paquetes en una sola solicitud y sigue cada uno por su número de rastreo de Ryde hasta que se entregue, se rechace o se devuelva. Cada paquete responde con el mismo vocabulario de siete estados que espera un agregador de rastreo, así que el flujo que construyas aquí es el que tus clientes ya saben leer. El acceso requiere una organización transportista aprobada con un Acuerdo de Transporte de Ryde firmado; los precios vienen de la tarifa de ese acuerdo, no de una cotización por solicitud.

## Ciclo de vida

```
  CREATED               (we have the parcel's details, not the parcel)
     |
  AT HUB / SORTED       (it is at the depot it will be collected from)
     |
  COLLECTED             (a courier has it in hand, scanned at the depot)
     |
  OUT FOR DELIVERY      (the run has started; the recipient is told)
     |
  DELIVERED  <----+     (photo and recipient name are the proof)
     |            |
  ATTEMPTED ------+     (nobody home, refused, cannot reach the door;
     |                   it goes back on a later run)
  RETURNED TO HUB
     |
  RETURNED TO SHIPPER   (attempts exhausted, or you asked for it back)

  You may CANCEL at any point before a parcel is delivered or returned
  — including while it is already on a van.
```

## Operaciones

### `GET /v1/coverage`

Consulta si Ryde entrega en un código postal o un punto, y con qué niveles de servicio.

- operation: `check_coverage`
- scope: `coverage.read`
- entitlement: carrier_agreement
- creates a transaction: no
- idempotency key: not required
- MCP tool: `check_coverage`
- status: beta

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

### `GET /v1/rates`

Cotiza un paquete a una dirección con tu tarifa contratada, por nivel de servicio. No crea nada.

- operation: `quote_rates`
- scope: `coverage.read`
- entitlement: carrier_agreement
- creates a transaction: no
- idempotency key: not required
- MCP tool: `quote_rates`
- status: beta

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

### `POST /v1/shipments`

Entrega a Ryde un paquete para repartir. Devuelve su número de rastreo de Ryde.

- operation: `create_shipment`
- scope: `shipments.create`
- entitlement: carrier_agreement
- creates a transaction: no
- idempotency key: supported
- MCP tool: `create_shipment`
- status: beta

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

### `POST /v1/shipments/batch`

Entrega a Ryde un manifiesto de hasta 500 paquetes en una sola solicitud. Cada fila informa creado, duplicado o rechazado con su motivo.

- operation: `create_shipments_batch`
- scope: `shipments.create`
- entitlement: carrier_agreement
- creates a transaction: no
- idempotency key: supported
- MCP tool: `create_shipments_batch`
- status: beta

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

### `GET /v1/shipments/{tracking_number}`

El estado actual de un paquete, con su historial de escaneos y la prueba de entrega una vez entregado.

- operation: `get_shipment`
- scope: `shipments.read`
- entitlement: carrier_agreement
- creates a transaction: no
- idempotency key: not required
- MCP tool: `get_shipment`
- status: beta

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

### `GET /v1/shipments`

Tus paquetes, del más reciente al más antiguo, filtrables por estado y fecha.

- operation: `list_shipments`
- scope: `shipments.read`
- entitlement: carrier_agreement
- creates a transaction: no
- idempotency key: not required
- MCP tool: `list_shipments`
- status: beta

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

### `POST /v1/shipments/{tracking_number}/cancel`

Cancela un paquete que entregaste a Ryde, en cualquier momento antes de que se entregue o se devuelva.

- operation: `cancel_shipment`
- scope: `shipments.manage`
- entitlement: carrier_agreement
- creates a transaction: no
- idempotency key: supported
- MCP tool: `cancel_shipment`
- status: beta

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

### `GET /v1/shipments/{tracking_number}/events`

Todos los eventos registrados de un paquete, del más antiguo al más reciente: dónde se escaneó, cuándo y por qué falló un intento.

- operation: `list_shipment_events`
- scope: `shipments.read`
- entitlement: carrier_agreement
- creates a transaction: no
- idempotency key: not required
- MCP tool: `list_shipment_events`
- status: beta

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

### `GET /v1/hubs`

Los depósitos desde donde se recogen tus paquetes.

- operation: `list_hubs`
- scope: `coverage.read`
- entitlement: carrier_agreement
- creates a transaction: no
- idempotency key: not required
- MCP tool: `list_hubs`
- status: beta

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