Skip to main content

​
Tickets

Manage support tickets for community issue tracking and resolution.

​
Get All Tickets

GET /api/tickets
Retrieves all tickets across all communities. Authorization: ADMIN_COMPANY, SYSTEM_ADMIN Response: Array of TicketDto 
[
  {
    "id": 1,
    "communityId": "123e4567-e89b-12d3-a456-426614174000",
    "communityName": "Green Valley",
    "residentId": "123e4567-e89b-12d3-a456-426614174001",
    "residentName": "John Doe",
    "residentNumber": "A-101",
    "categoriaTicketId": 1,
    "categoriaTicketNombre": "Mantenimiento",
    "statusId": 1,
    "statusCode": "NUEVO",
    "statusDescripcion": "Nuevo",
    "statusColor": "#FF9800",
    "fechaReporte": "2026-03-01T10:30:00Z",
    "contenido": "Water leak in bathroom",
    "imageUrls": ["uploads/tickets/1/photo.jpg"],
    "createdAt": "2026-03-01T10:30:00Z",
    "updatedAt": "2026-03-01T14:20:00Z"
  }
]

​
Get Tickets by Community

GET /api/tickets/community/{communityId}
Retrieves all tickets for a specific community. Authorization: ADMIN_COMPANY, SYSTEM_ADMIN Path Parameters:
  • communityId (UUID, required): Community identifier
Response: Array of TicketDto

​
Get My Tickets

GET /api/tickets/my
Retrieves all tickets created by the authenticated resident. Authorization: Any authenticated user Response: Array of TicketDto Errors:
  • 400 BAD_REQUEST: User is not registered as a resident

​
Get Ticket by ID

GET /api/tickets/{id}
Retrieves a specific ticket by ID. Authorization: Any authenticated user Path Parameters:
  • id (integer, required): Ticket identifier
Response: TicketDto Errors:
  • 404 NOT FOUND: Ticket does not exist

​
Create Ticket

POST /api/tickets
Creates a new support ticket. Authorization: Any authenticated user Behavior by Role:
  • Residents: Ticket is automatically created for their account. ResidentId and CommunityId fields are ignored.
  • Admins (ADMIN_COMPANY/SYSTEM_ADMIN): Must specify either residentId or communityId:
    • If residentId provided: Creates ticket for that specific resident
    • If communityId provided (without residentId): Uses first resident from that community
    • If neither provided: Returns error
Request Body: CreateTicketDto 
{
  "categoriaTicketId": 1,
  "contenido": "Water leak in bathroom sink, needs immediate attention",
  "residentId": "123e4567-e89b-12d3-a456-426614174001",
  "communityId": "123e4567-e89b-12d3-a456-426614174000"
}
Fields:
  • categoriaTicketId (integer, required): Category identifier (1 to 2147483647)
  • contenido (string, optional): Ticket description (max 4,000 characters)
  • residentId (UUID, optional): Resident ID (admin only - creates ticket for specific resident)
  • communityId (UUID, optional): Community ID (admin only - uses first resident if residentId not provided)
Response: TicketDto (201 Created) Location Header: Location: /api/tickets/{id} Errors:
  • 400 BAD_REQUEST: User not registered as resident (non-admin)
  • 400 BAD_REQUEST: Resident not found (admin with invalid residentId)
  • 400 BAD_REQUEST: Community has no registered residents (admin with communityId)
  • 400 BAD_REQUEST: Must specify CommunityId or ResidentId (admin without either)
  • 400 INVALID_OPERATION: Business logic validation failed

​
Update Ticket

PUT /api/tickets/{id}
Updates an existing ticket. Authorization:
  • Residents can update their own tickets only
  • Admins (ADMIN_COMPANY/SYSTEM_ADMIN) can update any ticket
Path Parameters:
  • id (integer, required): Ticket identifier
Request Body: UpdateTicketDto 
{
  "statusId": 2,
  "contenido": "Water leak in bathroom sink - now affecting floor",
  "imageUrls": ["uploads/tickets/1/photo1.jpg", "uploads/tickets/1/photo2.jpg"]
}
Fields (all optional):
  • statusId (integer, optional): New status identifier
  • contenido (string, optional): Updated description (max 4,000 characters)
  • imageUrls (array of strings, optional): Image paths (replaces existing images)
Response: TicketDto Errors:
  • 404 NOT FOUND: Ticket does not exist
  • 403 FORBIDDEN: Resident trying to update another resident’s ticket

​
Delete Ticket

DELETE /api/tickets/{id}
Deletes a ticket. Authorization: Any authenticated user Path Parameters:
  • id (integer, required): Ticket identifier
Response: 204 No Content Errors:
  • 404 NOT FOUND: Ticket does not exist

​
Ticket Categories

Manage ticket categorization.

​
Get All Categories

GET /api/categoriaticket
Retrieves all available ticket categories. Authorization: Any authenticated user Response: Array of CategoriaTicketDto 
[
  {
    "id": 1,
    "categoria": "Mantenimiento"
  },
  {
    "id": 2,
    "categoria": "Seguridad"
  },
  {
    "id": 3,
    "categoria": "Amenidades"
  },
  {
    "id": 4,
    "categoria": "Areas comunes"
  }
]

​
Get Category by ID

GET /api/categoriaticket/{id}
Retrieves a specific category by ID. Authorization: Any authenticated user Path Parameters:
  • id (integer, required): Category identifier
Response: CategoriaTicketDto Errors:
  • 404 NOT FOUND: Category does not exist

​
Ticket Statuses

Manage ticket status tracking.

​
Get All Statuses

GET /api/statusticket
Retrieves all available ticket statuses. Authorization: Any authenticated user Response: Array of StatusTicketDto 
[
  {
    "id": 1,
    "code": "NUEVO",
    "descripcion": "Nuevo",
    "color": "#FF9800"
  },
  {
    "id": 2,
    "code": "EN_REVISION",
    "descripcion": "En revisión",
    "color": "#2196F3"
  },
  {
    "id": 3,
    "code": "EN_INVESTIGACION",
    "descripcion": "En investigación",
    "color": "#9C27B0"
  },
  {
    "id": 4,
    "code": "EN_PROCESO",
    "descripcion": "En proceso",
    "color": "#FFC107"
  },
  {
    "id": 5,
    "code": "CANCELADO",
    "descripcion": "Cancelado",
    "color": "#F44336"
  },
  {
    "id": 6,
    "code": "RESUELTO",
    "descripcion": "Resuelto",
    "color": "#4CAF50"
  }
]
Fields:
  • id: Status identifier
  • code: Status code for programmatic use
  • descripcion: Human-readable description
  • color: Hex color code for UI badges

​
Get Status by ID

GET /api/statusticket/{id}
Retrieves a specific status by ID. Authorization: Any authenticated user Path Parameters:
  • id (integer, required): Status identifier
Response: StatusTicketDto Errors:
  • 404 NOT FOUND: Status does not exist

​
Comments

Manage comments on tickets and other resources. Comments use an origin-based system where tickets are identified by origen="ticket" and idOrigen="{ticketId}".

​
Get Comments by Origin

GET /api/comentarios/origen/{origen}/{idOrigen}
Retrieves all comments for a specific resource. Authorization: Any authenticated user Path Parameters:
  • origen (string, required): Origin type (e.g., “ticket”, “event”, “post”, “provider”)
  • idOrigen (string, required): Origin resource identifier
Example: GET /api/comentarios/origen/ticket/1 Response: Array of ComentarioDto 
[
  {
    "id": 1,
    "residentId": "123e4567-e89b-12d3-a456-426614174001",
    "residentName": "John Doe",
    "origen": "ticket",
    "idOrigen": "1",
    "idComment": null,
    "comentarioTexto": "I've submitted a photo showing the leak location",
    "imageUrls": ["uploads/comments/1/photo.jpg"],
    "createdAt": "2026-03-01T11:00:00Z",
    "updatedAt": null
  },
  {
    "id": 2,
    "residentId": "123e4567-e89b-12d3-a456-426614174002",
    "residentName": "Admin User",
    "origen": "ticket",
    "idOrigen": "1",
    "idComment": 1,
    "comentarioTexto": "Thanks! Maintenance team has been notified",
    "imageUrls": null,
    "createdAt": "2026-03-01T11:30:00Z",
    "updatedAt": null
  }
]
Fields:
  • idComment: If set, indicates this is a reply to another comment (threaded discussion)
  • origen: Origin resource type
  • idOrigen: ID of the origin resource (ticket ID, event ID, etc.)

​
Get Comment by ID

GET /api/comentarios/{id}
Retrieves a specific comment by ID. Authorization: Any authenticated user Path Parameters:
  • id (integer, required): Comment identifier
Response: ComentarioDto Errors:
  • 404 NOT FOUND: Comment does not exist

​
Create Comment

POST /api/comentarios
Creates a new comment. Authorization: Any authenticated user Request Body: CreateComentarioDto 
{
  "origen": "ticket",
  "idOrigen": "1",
  "idComment": null,
  "comentarioTexto": "The maintenance team fixed the leak today. All working now!",
  "imageUrls": ["uploads/comments/3/after.jpg"]
}
Fields:
  • origen (string, required): Origin type (max 50 characters)
  • idOrigen (string, required): Origin resource ID (max 50 characters)
  • idComment (integer, optional): Parent comment ID for threaded replies
  • comentarioTexto (string, required): Comment text (max 4,000 characters)
  • imageUrls (array of strings, optional): Image paths
Response: ComentarioDto (201 Created) Location Header: Location: /api/comentarios/{id} Errors:
  • 400 BAD_REQUEST: User not registered as resident
  • 400 INVALID_OPERATION: Business logic validation failed

​
Update Comment

PUT /api/comentarios/{id}
Updates an existing comment. Authorization: Any authenticated user Path Parameters:
  • id (integer, required): Comment identifier
Request Body: UpdateComentarioDto 
{
  "comentarioTexto": "Updated comment text with more details"
}
Fields:
  • comentarioTexto (string, required): Updated comment text (max 4,000 characters)
Response: ComentarioDto Errors:
  • 404 NOT FOUND: Comment does not exist

​
Delete Comment

DELETE /api/comentarios/{id}
Deletes a comment. Authorization: Any authenticated user Path Parameters:
  • id (integer, required): Comment identifier
Response: 204 No Content Errors:
  • 404 NOT FOUND: Comment does not exist

​
Data Models

​
TicketDto

{
  "id": 1,
  "communityId": "123e4567-e89b-12d3-a456-426614174000",
  "communityName": "Green Valley",
  "residentId": "123e4567-e89b-12d3-a456-426614174001",
  "residentName": "John Doe",
  "residentNumber": "A-101",
  "categoriaTicketId": 1,
  "categoriaTicketNombre": "Mantenimiento",
  "statusId": 1,
  "statusCode": "NUEVO",
  "statusDescripcion": "Nuevo",
  "statusColor": "#FF9800",
  "fechaReporte": "2026-03-01T10:30:00Z",
  "contenido": "Water leak in bathroom",
  "imageUrls": ["uploads/tickets/1/photo.jpg"],
  "createdAt": "2026-03-01T10:30:00Z",
  "updatedAt": "2026-03-01T14:20:00Z"
}

​
CategoriaTicketDto

{
  "id": 1,
  "categoria": "Mantenimiento"
}

​
StatusTicketDto

{
  "id": 1,
  "code": "NUEVO",
  "descripcion": "Nuevo",
  "color": "#FF9800"
}

​
ComentarioDto

{
  "id": 1,
  "residentId": "123e4567-e89b-12d3-a456-426614174001",
  "residentName": "John Doe",
  "origen": "ticket",
  "idOrigen": "1",
  "idComment": null,
  "comentarioTexto": "I've submitted a photo showing the leak location",
  "imageUrls": ["uploads/comments/1/photo.jpg"],
  "createdAt": "2026-03-01T11:00:00Z",
  "updatedAt": null
}

​
Error Responses

All endpoints may return standard error responses: 
{
  "code": "BAD_REQUEST",
  "message": "User is not registered as a resident"
}
Common error codes:
  • BAD_REQUEST: Invalid request data or business rule violation
  • INVALID_OPERATION: Operation cannot be completed due to business logic
  • UNAUTHORIZED: Missing or invalid authentication
  • FORBIDDEN: Insufficient permissions
  • NOT_FOUND: Resource does not exist

Build docs developers (and LLMs) love

Get started for freeTalk to us