apskel-pos-backend/TABLE_MANAGEMENT_API.md

Table Management API

This document describes the Table Management API endpoints for managing restaurant tables in the POS system.

Overview

The Table Management API allows you to:

• Create, read, update, and delete tables
• Manage table status (available, occupied, reserved, cleaning, maintenance)
• Occupy and release tables with orders
• Track table positions and capacity
• Get available and occupied tables for specific outlets

Table Entity

A table has the following properties:

{
  "id": "uuid",
  "organization_id": "uuid",
  "outlet_id": "uuid",
  "table_name": "string",
  "start_time": "datetime (optional)",
  "status": "available|occupied|reserved|cleaning|maintenance",
  "order_id": "uuid (optional)",
  "payment_amount": "decimal",
  "position_x": "decimal",
  "position_y": "decimal",
  "capacity": "integer (1-20)",
  "is_active": "boolean",
  "metadata": "object",
  "created_at": "datetime",
  "updated_at": "datetime",
  "order": "OrderResponse (optional)"
}

API Endpoints

1. Create Table

POST /api/v1/tables

Create a new table for an outlet.

Request Body:

{
  "outlet_id": "uuid",
  "table_name": "string",
  "position_x": "decimal",
  "position_y": "decimal",
  "capacity": "integer (1-20)",
  "metadata": "object (optional)"
}

Response: 201 Created

{
  "id": "uuid",
  "organization_id": "uuid",
  "outlet_id": "uuid",
  "table_name": "string",
  "status": "available",
  "position_x": "decimal",
  "position_y": "decimal",
  "capacity": "integer",
  "is_active": true,
  "metadata": "object",
  "created_at": "datetime",
  "updated_at": "datetime"
}

2. Get Table by ID

GET /api/v1/tables/{id}

Get table details by ID.

Response: 200 OK

{
  "id": "uuid",
  "organization_id": "uuid",
  "outlet_id": "uuid",
  "table_name": "string",
  "start_time": "datetime (optional)",
  "status": "string",
  "order_id": "uuid (optional)",
  "payment_amount": "decimal",
  "position_x": "decimal",
  "position_y": "decimal",
  "capacity": "integer",
  "is_active": "boolean",
  "metadata": "object",
  "created_at": "datetime",
  "updated_at": "datetime",
  "order": "OrderResponse (optional)"
}

3. Update Table

PUT /api/v1/tables/{id}

Update table details.

Request Body:

{
  "table_name": "string (optional)",
  "status": "available|occupied|reserved|cleaning|maintenance (optional)",
  "position_x": "decimal (optional)",
  "position_y": "decimal (optional)",
  "capacity": "integer (1-20) (optional)",
  "is_active": "boolean (optional)",
  "metadata": "object (optional)"
}

Response: 200 OK - Updated table object

4. Delete Table

DELETE /api/v1/tables/{id}

Delete a table. Cannot delete occupied tables.

Response: 204 No Content

5. List Tables

GET /api/v1/tables

Get paginated list of tables with optional filters.

Query Parameters:

• organization_id (optional): Filter by organization
• outlet_id (optional): Filter by outlet
• status (optional): Filter by status
• is_active (optional): Filter by active status
• search (optional): Search in table names
• page (default: 1): Page number
• limit (default: 10, max: 100): Page size

Response: 200 OK

{
  "tables": [
    {
      "id": "uuid",
      "table_name": "string",
      "status": "string",
      "capacity": "integer",
      "is_active": "boolean",
      "created_at": "datetime",
      "updated_at": "datetime"
    }
  ],
  "total_count": "integer",
  "page": "integer",
  "limit": "integer",
  "total_pages": "integer"
}

6. Occupy Table

POST /api/v1/tables/{id}/occupy

Occupy a table with an order.

Request Body:

{
  "order_id": "uuid",
  "start_time": "datetime"
}

Response: 200 OK - Updated table object with order information

7. Release Table

POST /api/v1/tables/{id}/release

Release a table and record payment amount.

Request Body:

{
  "payment_amount": "decimal"
}

Response: 200 OK - Updated table object

8. Get Available Tables

GET /api/v1/outlets/{outlet_id}/tables/available

Get list of available tables for a specific outlet.

Response: 200 OK

[
  {
    "id": "uuid",
    "table_name": "string",
    "status": "available",
    "capacity": "integer",
    "position_x": "decimal",
    "position_y": "decimal"
  }
]

9. Get Occupied Tables

GET /api/v1/outlets/{outlet_id}/tables/occupied

Get list of occupied tables for a specific outlet.

Response: 200 OK

[
  {
    "id": "uuid",
    "table_name": "string",
    "status": "occupied",
    "start_time": "datetime",
    "order_id": "uuid",
    "capacity": "integer",
    "position_x": "decimal",
    "position_y": "decimal",
    "order": "OrderResponse"
  }
]

Table Statuses

• available: Table is free and ready for use
• occupied: Table is currently in use with an order
• reserved: Table is reserved for future use
• cleaning: Table is being cleaned
• maintenance: Table is under maintenance

Business Rules

1. Table Creation: Tables must have unique names within an outlet
2. Table Occupation: Only available or cleaning tables can be occupied
3. Table Release: Only occupied tables can be released
4. Table Deletion: Occupied tables cannot be deleted
5. Capacity: Table capacity must be between 1 and 20
6. Position: Tables have X and Y coordinates for layout positioning

Error Responses

400 Bad Request:

{
  "error": "Error description",
  "message": "Detailed error message"
}

404 Not Found:

{
  "error": "Table not found",
  "message": "Table with specified ID does not exist"
}

500 Internal Server Error:

{
  "error": "Failed to create table",
  "message": "Database error or other internal error"
}

Authentication

All endpoints require authentication via JWT token in the Authorization header:

Authorization: Bearer <jwt_token>

Authorization

All table management endpoints require admin or manager role permissions.

Example Usage

Creating a Table

curl -X POST http://localhost:8080/api/v1/tables \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "outlet_id": "123e4567-e89b-12d3-a456-426614174000",
    "table_name": "Table 1",
    "position_x": 100.0,
    "position_y": 200.0,
    "capacity": 4
  }'

Occupying a Table

curl -X POST http://localhost:8080/api/v1/tables/123e4567-e89b-12d3-a456-426614174000/occupy \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "order_id": "123e4567-e89b-12d3-a456-426614174001",
    "start_time": "2024-01-15T10:30:00Z"
  }'

Getting Available Tables

curl -X GET http://localhost:8080/api/v1/outlets/123e4567-e89b-12d3-a456-426614174000/tables/available \
  -H "Authorization: Bearer <token>"