Tickets Overview

Comprehensive ticket management system for urban management

Overview

The Tickets API provides a comprehensive support ticket management system for urban management operations. It allows citizens to submit service requests and enables administrators to manage, assign, and track ticket progress through various stages.

Ticket Schema

Core Fields

interface Ticket {
  id: string;                    // UUID - Primary key
  userId: string;                 // UUID - Reference to user who created the ticket
  status: TicketStatus;          // Current status of the ticket
  category: TicketCategory;      // Type/category of the ticket
  title: string;                 // Short title/summary of the ticket (max 120 chars)
  description: string;            // Detailed description of the issue
  attachments?: string[];        // Array of attachment URLs
  assignedTo?: string;           // UUID - Reference to assigned technician/admin
  notes?: string;                // Notes/comments about the ticket
  createdAt: string;            // ISO timestamp - Creation date
  updatedAt: string;            // ISO timestamp - Last update date
}

Ticket Status

Tickets progress through the following statuses:

• PENDING: Newly created ticket awaiting assignment
• IN_PROGRESS: Ticket assigned and work in progress
• COMPLETED: Work completed, ticket resolved
• CANCELLED: Ticket cancelled (no longer needed)

Ticket Categories

Tickets are categorized by service type:

• MAINTENANCE: Building maintenance and repairs
• SECURITY: Security-related issues and concerns
• CLEANING: Cleaning and sanitation requests
• WASTE: Waste management and disposal
• ELECTRICITY: Electrical issues and repairs
• WATER: Water supply and plumbing issues
• GAS: Gas supply and safety concerns
• INTERNET: Internet connectivity and IT issues
• OTHER: Miscellaneous requests

Response Format

Grouped Response

Most ticket endpoints return tickets grouped by status:

{
  "PENDING": [
    {
      "id": "uuid",
      "userId": "uuid",
      "status": "PENDING",
      "category": "MAINTENANCE",
      "title": "Elevator Issue - Floor 3",
      "description": "Broken elevator",
      "attachments": ["url1", "url2"],
      "assignedTo": null,
      "notes": "Urgent issue",
      "createdAt": "2024-01-01T00:00:00Z",
      "updatedAt": "2024-01-01T00:00:00Z",
      "user": {
        "id": "uuid",
        "fullname": "John Doe",
        "phoneNumber": "[phone]",
        "profilePhoto": "url"
      },
      "technician": null
    }
  ],
  "IN_PROGRESS": [],
  "COMPLETED": [],
  "CANCELLED": []
}

Single Ticket Response

Individual ticket operations return a single ticket object:

{
  "id": "uuid",
  "userId": "uuid",
  "status": "PENDING",
  "category": "MAINTENANCE",
  "title": "Elevator Issue - Floor 3",
  "description": "Broken elevator",
  "attachments": ["url1", "url2"],
  "assignedTo": null,
  "notes": "Urgent issue",
  "createdAt": "2024-01-01T00:00:00Z",
  "updatedAt": "2024-01-01T00:00:00Z"
}

Permissions

The ticket system uses role-based permissions:

• ticket:read: View tickets and ticket details
• ticket:write: Create, update, assign, and change ticket status
• ticket:delete: Delete tickets

Workflow

1. Creation: Citizens create tickets with description and category
2. Assignment: Administrators assign tickets to technicians
3. Progress: Technicians update ticket status and add notes
4. Resolution: Tickets marked as completed or cancelled

Related Endpoints

Query Endpoints

• Get All Tickets - Retrieve all tickets with optional status filtering
• Get Tickets by User ID - Get tickets created by a specific user
• Get Tickets by Technician ID - Get tickets assigned to a specific technician

Management Endpoints

• Create Ticket - Create a new support ticket
• Update Ticket - Update ticket details
• Assign Ticket - Assign ticket to technician
• Unassign Ticket - Remove technician assignment
• Change Status - Update ticket status
• Delete Ticket - Permanently delete a ticket