Tables API Overview

​

Table Lifecycle

• available: Ready for customers
• occupied: Currently serving customers (has active session)
• reserved: Reserved for future customers
• maintenance: Temporarily unavailable

​

Status Transitions

available    → occupied, reserved, maintenance
occupied     → available, maintenance
reserved     → occupied, available, maintenance
maintenance  → available

​

QR Code Workflow

1. QR Generation: When creating a table, a QR code is automatically generated using {branchSlug}-{tableNumber}
2. Customer Scan: Customers scan the QR code to access the menu and start a session
3. Session Creation: The customer app uses the QR code to identify the table and branch
4. Authentication: A customer JWT token is issued for session authentication

​

Core Endpoints

​

Table Management

• GET /api/tables - List all tables for a branch
• POST /api/tables - Create a new table
• PATCH /api/tables/:id - Update table capacity or space
• PATCH /api/tables/:id/status - Change table status
• PATCH /api/tables/:id/position - Update table position (for floor plan)
• DELETE /api/tables/:id - Delete a table

​

Table Sessions

• POST /api/tables/sessions - Start a new table session
• GET /api/tables/sessions - List sessions with optional status filter
• GET /api/tables/sessions/pending - List pending sessions awaiting approval
• GET /api/tables/sessions/:id - Get session details
• PATCH /api/tables/sessions/:id/approve - Approve a pending session
• PATCH /api/tables/sessions/:id/reject - Reject a pending session
• PATCH /api/tables/sessions/:id/end - End an active session

​

Waiter Assignments

• GET /api/tables/my-assignments - Get tables assigned to current user
• GET /api/tables/:id/assignments - List waiters assigned to a table
• POST /api/tables/:id/assignments - Assign a waiter to a table
• DELETE /api/tables/:id/assignments/:userId - Remove waiter assignment

​

History & Analytics

• GET /api/tables/:id/history - View table history with sessions and orders

​

Authentication

• Bearer token authentication (staff JWT)
• Organization and branch context via tenantMiddleware
• Appropriate permissions (e.g., tables:read, tables:create, tables:update)

​

Real-time Updates

• table:status - Table status changed
• session:started - New session started
• session:pending - Session awaiting approval
• session:approved - Session approved
• session:rejected - Session rejected
• session:ended - Session ended

​

Response Format

{
  "success": true,
  "data": { /* result */ }
}

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Mesa no encontrada"
  }
}