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

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