# Comercio

Opera una tienda para la que tienes autorización: consulta y gestiona su cola de pedidos y administra su catálogo. Son las mismas rutas que usan el portal de comercios de Ryde y su punto de venta, así que un cambio hecho aquí aparece de inmediato en el terminal de la tienda: no existe un "catálogo de API" aparte que haya que sincronizar. El acceso requiere la autorización del propio comercio y su acuerdo comercial de Ryde firmado; un desarrollador no puede aceptar ese acuerdo en nombre de una tienda.

Opera una tienda para la que tienes autorización: consulta y gestiona su cola de pedidos y administra su catálogo. Son las mismas rutas que usan el portal de comercios de Ryde y su punto de venta, así que un cambio hecho aquí aparece de inmediato en el terminal de la tienda: no existe un "catálogo de API" aparte que haya que sincronizar. El acceso requiere la autorización del propio comercio y su acuerdo comercial de Ryde firmado; un desarrollador no puede aceptar ese acuerdo en nombre de una tienda.

## Ciclo de vida

```
  PLACED                (the customer has paid, or is paying cash)
     |
  MERCHANT ACCEPTED  ---> REJECTED   (a paid order is refunded to the
     |                                customer's Ryde wallet)
  PREPARING
     |
  READY FOR PICKUP      (for a delivery order, THIS is what dispatches
     |                   a Ryde courier — couriers accept first-come,
     |                   so there is nothing to assign)
  PICKED UP
     |
  DELIVERED             (or COMPLETED, for pickup and dine-in)
```

## Operaciones

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

### `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/{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`

Crea varios articulos del catalogo a la vez, con sus categorias. Solo crea: nunca cambia el precio de un articulo existente.

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