# Servicios

Encuentra proveedores que van donde el cliente, consulta su disponibilidad real y reserva una franja. La disponibilidad se deriva por solicitud del estado en vivo del proveedor y su horario publicado; nunca la guardes en caché en el cliente, porque un proveedor que acaba de aceptar un trabajo ya no está disponible.

Encuentra proveedores que van donde el cliente, consulta su disponibilidad real y reserva una franja. La disponibilidad se deriva por solicitud del estado en vivo del proveedor y su horario publicado; nunca la guardes en caché en el cliente, porque un proveedor que acaba de aceptar un trabajo ya no está disponible.

## Ciclo de vida

```
  QUOTED
     |
  REQUESTED  or  SCHEDULED   (booked into a specific slot)
     |
  ACCEPTED                   (or rejected by the provider)
     |
  ON THE WAY
     |
  IN PROGRESS                (some providers require the customer to
     |                        sign a liability waiver before starting)
  COMPLETED                  (or CANCELLED, before work begins)
```

## Operaciones

### `GET /v1/services/providers`

Encuentra proveedores que se desplazan al cliente, con su disponibilidad en vivo. La disponibilidad se deriva por solicitud y el cliente nunca debe guardarla en caché.

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

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

### `GET /v1/services/providers/{provider_id}/slots`

Franjas de cita libres en una fecha, para un trabajo de cierta duración. A un trabajo largo solo se le ofrece un inicio cuyas franjas consecutivas estén todas libres.

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

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

### `POST /v1/services/bookings/quote`

Cotiza una reserva de servicio antes de comprometer una franja.

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

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

### `POST /v1/services/bookings`

Reserva un proveedor, opcionalmente en una franja concreta. La competencia por una franja la resuelve la plataforma: una reserva perdedora se rechaza, nunca se duplica.

- operation: `book_service`
- scope: `services.book`
- entitlement: ryde_one
- creates a transaction: yes
- idempotency key: required
- MCP tool: `book_service`
- status: planned

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

### `GET /v1/services/bookings/{booking_id}`

Estado en vivo de una reserva, desde la llegada hasta el inicio y la finalización.

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

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