Admin · Pedidos y sala

Esta área agrupa los endpoints de administración que el personal del restaurante usa para gobernar el ciclo de vida de las comandas y el control de sala en tiempo real. Por un lado, el router de order-batches (/order-batches) expone el flujo completo de una comanda —aprobar, rechazar, confirmar, marcar lista, servir y cerrar—, además de la cola de cocina, la consulta paginada de pedidos y lotes, y una vista pública de comanda por token de sesión. Por otro, el router de manager (/manager) ofrece el dashboard de mesas activas, la confirmación de entregas, las rondas de cortesía, el flag de cocina saturada y el feed en vivo de la tablet de sala.

Todos los endpoints (salvo la vista pública de comanda) requieren autenticación de admin y propiedad del restaurante: el restaurant_id se valida siempre vía require_restaurant_access, nunca se confía en el cuerpo de la petición. La multitenancy es estricta por restaurant_id y SUPER_ADMIN tiene acceso a todos los restaurantes. Los listados siguen el shape canónico de paginación (page + per_page, con items/total/pages/has_next/has_prev).

Tiempo real por SSE

El control de sala se sirve por Server-Sent Events, no WebSocket. El feed GET /manager/restaurants/{id}/events emite primero una trama sala_snapshot y luego eventos en vivo (table_state_changed, silent_table_alert). Como EventSource no puede enviar cabeceras, este endpoint autentica vía query param ?token= (JWT de admin); un token inválido o caducado devuelve 401. Las acciones de comanda publican sus eventos después del commit mediante un bus bufferizado. Detalle de cada evento en la referencia de eventos SSE.

Las transiciones del manager (entregas, reconciliación de pedidos) son idempotentes: pedir un estado no alcanzable es un no-op, nunca un error, lo que permite reconciliar por polling sin riesgo. Para entender el modelo de estados de la comanda y la máquina de estados de la mesa, consulta la arquitectura de comandas y de control de sala; la visión transversal de la API está en esta página.

Generado automáticamente

Las tablas y fichas de endpoints de esta página se generan desde el contrato OpenAPI. No las edites a mano; edita la intro en documentation/reference/api/_intros/admin-pedidos-sala.md y regenera con python scripts/gen_openapi_reference.py.

Resumen de endpoints

Método	Ruta	Resumen	Auth
GET	/api/v1/admin/order-batches/kitchen-queue/{restaurant_id}	Kitchen Queue	Bearer (admin)
GET	/api/v1/admin/order-batches/public/comanda/{session_token}/{comanda_id}	Get Comanda Public	Pública
GET	/api/v1/admin/order-batches/restaurants/{restaurant_id}/batches	List Restaurant Batches	Bearer (admin)
GET	/api/v1/admin/order-batches/restaurants/{restaurant_id}/orders	List Restaurant Orders	Bearer (admin)
GET	/api/v1/admin/order-batches/{comanda_id}	Get Comanda	Bearer (admin)
POST	/api/v1/admin/order-batches/{comanda_id}/approve	Approve Comanda	Bearer (admin)
POST	/api/v1/admin/order-batches/{comanda_id}/close	Close Comanda	Bearer (admin)
POST	/api/v1/admin/order-batches/{comanda_id}/confirm	Confirm Comanda	Bearer (admin)
POST	/api/v1/admin/order-batches/{comanda_id}/lines	Admin Add Line	Bearer (admin)
POST	/api/v1/admin/order-batches/{comanda_id}/ready	Ready Comanda	Bearer (admin)
POST	/api/v1/admin/order-batches/{comanda_id}/reject	Reject Comanda	Bearer (admin)
POST	/api/v1/admin/order-batches/{comanda_id}/serve	Serve Comanda	Bearer (admin)
PATCH	/api/v1/admin/order-batches/{order_id}/status	Update Order Status Endpoint	Bearer (admin)
PATCH	/api/v1/admin/orders/{order_id}/status	Update Order Status Endpoint	Bearer (admin)
POST	/api/v1/admin/qr/generate	Generate Qr	Bearer (admin)
POST	/api/v1/admin/qr/validate	Validate Qr	Pública
POST	/api/v1/admin/rooms	Create Room	Bearer (admin)
GET	/api/v1/admin/rooms/restaurant/{restaurant_id}	List Rooms	Bearer (admin)
DELETE	/api/v1/admin/rooms/{room_id}	Delete Room	Bearer (admin)
PATCH	/api/v1/admin/rooms/{room_id}	Update Room	Bearer (admin)

Detalle

GET /api/v1/admin/order-batches/kitchen-queue/{restaurant_id}

Kitchen Queue

Return the kitchen queue (PENDING/IN_PROGRESS/READY) for a restaurant.

• Auth: Bearer (admin)
• Parámetros: restaurant_id (path, requerido)
• Respuestas: 200 ComandaResponse[], 422 HTTPValidationError

GET /api/v1/admin/order-batches/public/comanda/{session_token}/{comanda_id}

Get Comanda Public

Public, unauthenticated lookup of a comanda by session token and id.

• Auth: Pública
• Parámetros: comanda_id (path, requerido), session_token (path, requerido)
• Respuestas: 200 OrderPublicResponse, 422 HTTPValidationError

GET /api/v1/admin/order-batches/restaurants/{restaurant_id}/batches

List Restaurant Batches

List a restaurant's comanda batches, paginated.

• Auth: Bearer (admin)
• Parámetros: restaurant_id (path, requerido), page (query, opcional), per_page (query, opcional)
• Respuestas: 200 ComandaBatchListResponse, 422 HTTPValidationError

GET /api/v1/admin/order-batches/restaurants/{restaurant_id}/orders

List Restaurant Orders

List a restaurant's orders, paginated and optionally filtered by status.

• Auth: Bearer (admin)
• Parámetros: restaurant_id (path, requerido), page (query, opcional), per_page (query, opcional), status (query, opcional)
• Respuestas: 200 OrderListResponse, 422 HTTPValidationError

GET /api/v1/admin/order-batches/{comanda_id}

Get Comanda

Fetch a single comanda by id (admin, restaurant-scoped).

• Auth: Bearer (admin)
• Parámetros: comanda_id (path, requerido)
• Respuestas: 200 ComandaResponse, 422 HTTPValidationError

POST /api/v1/admin/order-batches/{comanda_id}/approve

Approve Comanda

Manager-approve a comanda (PENDING_MANAGER → PENDING).

• Auth: Bearer (admin)
• Parámetros: comanda_id (path, requerido)
• Body: BatchNotesRequest
• Respuestas: 200 ComandaResponse, 422 HTTPValidationError

POST /api/v1/admin/order-batches/{comanda_id}/close

Close Comanda

Close a served comanda (SERVED → CLOSED).

• Auth: Bearer (admin)
• Parámetros: comanda_id (path, requerido)
• Respuestas: 200 ComandaResponse, 422 HTTPValidationError

POST /api/v1/admin/order-batches/{comanda_id}/confirm

Confirm Comanda

Confirm a comanda into preparation (PENDING → IN_PROGRESS).

• Auth: Bearer (admin)
• Parámetros: comanda_id (path, requerido)
• Respuestas: 200 ComandaResponse, 422 HTTPValidationError

POST /api/v1/admin/order-batches/{comanda_id}/lines

Admin Add Line

Add a product line to an existing comanda on behalf of the admin.

• Auth: Bearer (admin)
• Parámetros: comanda_id (path, requerido)
• Body: ComandaLineCreate
• Respuestas: 200 ComandaLineResponse, 422 HTTPValidationError

POST /api/v1/admin/order-batches/{comanda_id}/ready

Ready Comanda

Mark a comanda as ready (IN_PROGRESS → READY).

• Auth: Bearer (admin)
• Parámetros: comanda_id (path, requerido)
• Respuestas: 200 ComandaResponse, 422 HTTPValidationError

POST /api/v1/admin/order-batches/{comanda_id}/reject

Reject Comanda

Manager-reject a comanda (PENDING_MANAGER → MANAGER_REJECTED).

• Auth: Bearer (admin)
• Parámetros: comanda_id (path, requerido)
• Body: BatchNotesRequest
• Respuestas: 200 ComandaResponse, 422 HTTPValidationError

POST /api/v1/admin/order-batches/{comanda_id}/serve

Serve Comanda

Mark a comanda as served (IN_PROGRESS/READY → SERVED).

• Auth: Bearer (admin)
• Parámetros: comanda_id (path, requerido)
• Respuestas: 200 ComandaResponse, 422 HTTPValidationError

PATCH /api/v1/admin/order-batches/{order_id}/status

Update Order Status Endpoint

Update a comanda's status via the generic status-transition dispatcher.

• Auth: Bearer (admin)
• Parámetros: order_id (path, requerido)
• Body: StatusUpdate
• Respuestas: 200 StatusUpdateResponse, 422 HTTPValidationError

PATCH /api/v1/admin/orders/{order_id}/status

Update Order Status Endpoint

Update a comanda's status via the generic status-transition dispatcher (legacy Router E).

• Auth: Bearer (admin)
• Parámetros: order_id (path, requerido)
• Body: StatusUpdate
• Respuestas: 200, 422 HTTPValidationError

POST /api/v1/admin/qr/generate

Generate Qr

Generate a QR session token for a table.

• Auth: Bearer (admin)
• Parámetros: —
• Body: QRGenerateRequest
• Respuestas: 200 QRGenerateResponse, 422 HTTPValidationError

POST /api/v1/admin/qr/validate

Validate Qr

Validate a QR session token (public endpoint).

• Auth: Pública
• Parámetros: —
• Body: QRValidateRequest
• Respuestas: 200 QRValidateResponse, 422 HTTPValidationError

POST /api/v1/admin/rooms

Create Room

Create a new room.

• Auth: Bearer (admin)
• Parámetros: —
• Body: RoomCreateRequest
• Respuestas: 201 RoomResponse, 422 HTTPValidationError

GET /api/v1/admin/rooms/restaurant/{restaurant_id}

List Rooms

List all rooms for a restaurant.

• Auth: Bearer (admin)
• Parámetros: restaurant_id (path, requerido), page (query, opcional), size (query, opcional)
• Respuestas: 200, 422 HTTPValidationError

DELETE /api/v1/admin/rooms/{room_id}

Delete Room

Delete a room (and all its tables).

• Auth: Bearer (admin)
• Parámetros: room_id (path, requerido)
• Respuestas: 204, 422 HTTPValidationError

PATCH /api/v1/admin/rooms/{room_id}

Update Room

Update room settings.

• Auth: Bearer (admin)
• Parámetros: room_id (path, requerido)
• Body: RoomUpdateRequest
• Respuestas: 200 RoomResponse, 422 HTTPValidationError