# Referencia de la API

Cada operación, generada desde el registro de operaciones de la propia plataforma.

> **Info:** Esta página se genera desde el mismo registro contra el que autoriza la puerta de enlace. El alcance, derecho, idempotencia y soporte de sandbox de abajo no son una descripción de la implementación: son los propios metadatos de la implementación.

### `GET /v1/me/membership`

Si este cliente tiene una membresía Ryde One activa. Consúltalo antes de ofrecer transaccionar, para que el agente explique el requisito en vez de chocar con un 403 a media frase.

- operation: `get_membership_status`
- scope: `profile.read`
- entitlement: none
- creates a transaction: no
- idempotency key: not required
- MCP tool: `get_membership_status`
- status: beta

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

### `GET /v1/food/merchants`

Encuentra restaurantes, supermercados y tiendas abiertos cerca de un punto.

- operation: `search_restaurants`
- scope: `food.read`
- entitlement: none
- creates a transaction: no
- idempotency key: not required
- MCP tool: `search_restaurants`
- status: beta

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

### `GET /v1/food/merchants/{merchant_id}/menu`

El catálogo público de un comercio. El costo, el inventario, los códigos de barras y los identificadores de proveedor son asunto del comercio y nunca se devuelven aquí.

- operation: `get_restaurant_menu`
- scope: `food.read`
- entitlement: none
- creates a transaction: no
- idempotency key: not required
- MCP tool: `get_restaurant_menu`
- status: beta

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

### `POST /v1/food/orders/quote`

Cotiza una canasta exactamente como lo haría el checkout: artículos, cargos, impuestos, cualquier descuento de miembro y el total. Devuelve el quote_id que requiere place_food_order.

- operation: `quote_food_order`
- scope: `food.read`
- entitlement: none
- creates a transaction: no
- idempotency key: not required
- MCP tool: `quote_food_order`
- status: beta

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

### `POST /v1/food/orders`

Realiza el pedido que el cliente confirmó, a partir de un quote_id que se le mostró.

- operation: `place_food_order`
- scope: `food.order`
- entitlement: ryde_one
- creates a transaction: yes
- idempotency key: required
- MCP tool: `place_food_order`
- status: beta

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

### `GET /v1/food/orders/{order_id}`

Estado en vivo de un pedido, incluido el avance del mensajero. Deliberadamente SIN restricción de membresía: un pedido que existe sigue siendo rastreable.

- operation: `get_food_order`
- scope: `food.read`
- entitlement: none
- creates a transaction: no
- idempotency key: not required
- MCP tool: `get_food_order`
- status: beta

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

### `GET /v1/food/orders`

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

- operation: `list_food_orders`
- scope: `food.read`
- entitlement: none
- creates a transaction: no
- idempotency key: not required
- MCP tool: `list_food_orders`
- status: beta

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

### `POST /v1/food/orders/{order_id}/cancel`

Cancela un pedido, cuando su estado actual aún lo permite. Nunca restringido por membresía: SALIR de una transacción no debe requerir un derecho.

- operation: `cancel_food_order`
- scope: `food.read`
- entitlement: none
- creates a transaction: no
- idempotency key: supported
- MCP tool: `cancel_food_order`
- status: beta

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

### `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: beta

```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: beta

```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: beta

```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: beta

```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: beta

```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: beta

```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 '{ … }'
```

### `POST /v1/deliveries/quote`

Cotiza un envío de mensajería entre dos puntos. Usa la misma ruta de precios que la solicitud, así que la cotización es el cobro.

- operation: `quote_delivery`
- scope: `delivery.read`
- entitlement: none
- creates a transaction: no
- idempotency key: not required
- MCP tool: `quote_delivery`
- status: beta

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

### `POST /v1/deliveries`

Despacha un mensajero para mover un paquete, a partir de un quote_id que se mostró al cliente.

- operation: `request_delivery`
- scope: `delivery.request`
- entitlement: ryde_one
- creates a transaction: yes
- idempotency key: required
- MCP tool: `request_delivery`
- status: beta

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

### `GET /v1/deliveries/{delivery_id}`

Estado en vivo de una entrega, incluido el avance del mensajero y la prueba de entrega una vez recogida.

- operation: `get_delivery`
- scope: `delivery.read`
- entitlement: none
- creates a transaction: no
- idempotency key: not required
- MCP tool: `get_delivery`
- status: beta

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

### `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"
```

### `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: beta

```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: beta

```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: beta

```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: beta

```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: beta

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

### `GET /v1/tasks/types`

Los tipos de tarea que este mercado puede ejecutar realmente, con la evidencia que recoge cada uno. Solo se listan los tipos que Ryde puede cubrir con personal.

- operation: `list_task_types`
- scope: `tasks.read`
- entitlement: none
- creates a transaction: no
- idempotency key: not required
- MCP tool: `list_task_types`
- status: beta

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

### `POST /v1/tasks/quote`

Cotiza una tarea y confirma que podría encontrarse un proveedor calificado antes de comprometerse.

- operation: `quote_task`
- scope: `tasks.read`
- entitlement: none
- creates a transaction: no
- idempotency key: not required
- MCP tool: `quote_task`
- status: beta

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

### `POST /v1/tasks`

Despacha trabajo del mundo real con requisitos estructurados y reglas de evidencia.

- operation: `create_task`
- scope: `tasks.create`
- entitlement: ryde_one
- creates a transaction: yes
- idempotency key: required
- MCP tool: `create_task`
- status: beta

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

### `GET /v1/tasks/{task_id}`

Estado de la tarea, el proveedor asignado y la evidencia recogida hasta el momento.

- operation: `get_task`
- scope: `tasks.read`
- entitlement: none
- creates a transaction: no
- idempotency key: not required
- MCP tool: `get_task`
- status: beta

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

### `GET /v1/tasks/{task_id}/evidence`

La evidencia recogida para una tarea: fotos con sus hashes de contenido, GPS de captura, marcas de tiempo del dispositivo y las respuestas de cualquier lista de verificación.

- operation: `get_task_evidence`
- scope: `tasks.read`
- entitlement: none
- creates a transaction: no
- idempotency key: not required
- MCP tool: `get_task_evidence`
- status: beta

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

### `POST /v1/tasks/{task_id}/cancel`

Cancela una tarea que no ha comenzado.

- operation: `cancel_task`
- scope: `tasks.read`
- entitlement: none
- creates a transaction: no
- idempotency key: supported
- MCP tool: `cancel_task`
- status: beta

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

### `GET /v1/business/orders`

Lista los pedidos de la tienda, del mas reciente al mas antiguo. Filtra por estado o tipo de entrega.

- operation: `list_business_orders`
- scope: `orders.read`
- entitlement: business_agreement
- creates a transaction: no
- idempotency key: not required
- MCP tool: `list_business_orders`
- status: beta

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

### `GET /v1/business/orders/{order_id}`

Consulta un pedido de la tienda en detalle, con sus articulos y su historial de estados.

- operation: `get_business_order`
- scope: `orders.read`
- entitlement: business_agreement
- creates a transaction: no
- idempotency key: not required
- MCP tool: `get_business_order`
- status: beta

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

### `POST /v1/business/orders/{order_id}/accept`

Acepta un pedido entrante. Se rechaza con 402 si un pedido con tarjeta o billetera aun no esta pagado.

- operation: `accept_business_order`
- scope: `orders.manage`
- entitlement: business_agreement
- creates a transaction: no
- idempotency key: supported
- MCP tool: `accept_business_order`
- status: beta

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

### `POST /v1/business/orders/{order_id}/reject`

Rechaza un pedido. Un pedido pagado se reembolsa a la billetera Ryde del cliente — o, si la tienda lo cobró en su propia cuenta de Stripe, a la tarjeta del cliente por la tienda — y se libera la cita reservada.

- operation: `reject_business_order`
- scope: `orders.manage`
- entitlement: business_agreement
- creates a transaction: no
- idempotency key: supported
- MCP tool: `reject_business_order`
- status: beta

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

### `POST /v1/business/orders/{order_id}/preparing`

Marca un pedido aceptado como en preparacion, para que el seguimiento del cliente lo refleje.

- operation: `start_business_order_prep`
- scope: `orders.manage`
- entitlement: business_agreement
- creates a transaction: no
- idempotency key: supported
- MCP tool: `start_business_order_prep`
- status: beta

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

### `POST /v1/business/orders/{order_id}/ready`

Marca un pedido como listo para recoger. En un pedido a domicilio esto despacha un mensajero de Ryde.

- operation: `mark_business_order_ready`
- scope: `orders.manage`
- entitlement: business_agreement
- creates a transaction: no
- idempotency key: supported
- MCP tool: `mark_business_order_ready`
- status: beta

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

### `POST /v1/business/orders/{order_id}/complete`

Completa un pedido para recoger o en el local. Se rechaza con 409 si la cuenta de la mesa sigue abierta.

- operation: `complete_business_order`
- scope: `orders.manage`
- entitlement: business_agreement
- creates a transaction: no
- idempotency key: supported
- MCP tool: `complete_business_order`
- status: beta

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

### `GET /v1/business/catalog/items`

Lista los articulos del catalogo de la tienda con precios, modificadores y disponibilidad.

- operation: `list_catalog_items`
- scope: `menu.read`
- entitlement: business_agreement
- creates a transaction: no
- idempotency key: not required
- MCP tool: `list_catalog_items`
- status: beta

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

### `GET /v1/business/catalog/items/{item_id}`

Lee un articulo del catalogo por su id: precio, SKU, codigo de barras, impuesto, existencia y disponibilidad.

- operation: `get_catalog_item`
- scope: `menu.read`
- entitlement: business_agreement
- creates a transaction: no
- idempotency key: not required
- MCP tool: `get_catalog_item`
- status: beta

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

### `POST /v1/business/catalog/items`

Crea un articulo del catalogo. Aparece de inmediato en el POS de la tienda y en su tienda Ryde.

- operation: `create_catalog_item`
- scope: `menu.manage`
- entitlement: business_agreement
- creates a transaction: no
- idempotency key: supported
- MCP tool: `create_catalog_item`
- status: beta

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

### `PUT /v1/business/catalog/items/{item_id}`

Actualiza el nombre, la descripcion, el precio, la categoria o los modificadores de un articulo.

- operation: `update_catalog_item`
- scope: `menu.manage`
- entitlement: business_agreement
- creates a transaction: no
- idempotency key: supported
- MCP tool: `update_catalog_item`
- status: beta

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

### `PUT /v1/business/catalog/items/by-sku/{sku}`

Crea o actualiza el articulo del catalogo con este SKU. El SKU es unico en la tienda, asi que la misma llamada se puede repetir sin riesgo.

- operation: `upsert_catalog_item_by_sku`
- scope: `menu.manage`
- entitlement: business_agreement
- creates a transaction: no
- idempotency key: supported
- MCP tool: `upsert_catalog_item_by_sku`
- status: beta

```bash
curl -sX PUT 'https://sandbox-api.ryde.us.com/v1/business/catalog/items/by-sku/$sku' \
  -H "Authorization: Bearer $RYDE_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{ … }'
```

### `PUT /v1/business/catalog/items/{item_id}/availability`

Retira un articulo de la venta o vuelve a ofrecerlo, sin eliminarlo. La forma reversible de agotarlo.

- operation: `set_catalog_item_availability`
- scope: `menu.manage`
- entitlement: business_agreement
- creates a transaction: no
- idempotency key: supported
- MCP tool: `set_catalog_item_availability`
- status: beta

```bash
curl -sX PUT 'https://sandbox-api.ryde.us.com/v1/business/catalog/items/$item_id/availability' \
  -H "Authorization: Bearer $RYDE_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{ … }'
```

### `DELETE /v1/business/catalog/items/{item_id}`

Elimina un articulo del catalogo. No hay forma de deshacerlo por la API; para retirarlo temporalmente, cambia su disponibilidad.

- operation: `delete_catalog_item`
- scope: `menu.manage`
- entitlement: business_agreement
- creates a transaction: no
- idempotency key: supported
- MCP tool: `delete_catalog_item`
- status: beta

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

### `POST /v1/business/catalog/items/batch`

Agrega varios articulos del catalogo a la vez, con sus categorias. Sin duplicados: un articulo que coincide por SKU o codigo de barras se actualiza (precio y descripcion) en vez de agregarse dos veces, una coincidencia solo por nombre se omite salvo que se decida, y el modo "replace" retira los articulos que no estan en la lista cuando confirm_retire es igual al conteo que indica un 409.

- operation: `import_catalog_items`
- scope: `menu.manage`
- entitlement: business_agreement
- creates a transaction: no
- idempotency key: supported
- MCP tool: `import_catalog_items`
- status: beta

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

### `GET /v1/business/catalog/export`

Exporta el catalogo vendible de la tienda como filas en las columnas de la plantilla fija (nombre, SKU, codigo de barras, categoria, tipo, precio, impuesto, costo, existencia, almacen, descripcion). Costo, existencia y codigo de barras solo se llenan con un token menu.manage.

- operation: `export_catalog`
- scope: `menu.read`
- entitlement: business_agreement
- creates a transaction: no
- idempotency key: not required
- MCP tool: `export_catalog`
- status: beta

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

### `GET /v1/business/catalog/template`

Las columnas de la plantilla, los valores que acepta cada una, una fila de ejemplo, el limite de filas y los modos de importacion.

- operation: `get_catalog_template`
- scope: `menu.read`
- entitlement: business_agreement
- creates a transaction: no
- idempotency key: not required
- MCP tool: `get_catalog_template`
- status: beta

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

### `POST /v1/business/catalog/import/preview`

Revisa filas en las columnas de la plantilla contra el catalogo SIN escribir: que es nuevo, actualizado, sin cambios, posible duplicado o error, por fila. Devuelve un token para confirmar.

- operation: `preview_catalog_import`
- scope: `menu.manage`
- entitlement: business_agreement
- creates a transaction: no
- idempotency key: supported
- MCP tool: `preview_catalog_import`
- status: beta

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

### `POST /v1/business/catalog/import/commit`

Aplica una importacion revisada con su token, en modo merge, add_only o replace. Confirmar el mismo token otra vez devuelve el primer resultado y no escribe nada.

- operation: `commit_catalog_import`
- scope: `menu.manage`
- entitlement: business_agreement
- creates a transaction: no
- idempotency key: supported
- MCP tool: `commit_catalog_import`
- status: beta

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