Skip to main content

​
Mesa de Ayuda API

A production-ready helpdesk REST API built with FastAPI and PostgreSQL. It provides a complete support ticket management system with JWT authentication, role-based access control, SLA enforcement, and rich lifecycle operations.

Quickstart

Get the API running in minutes with your first ticket creation

Authentication

Learn JWT authentication and the four role system

Ticket Lifecycle

Understand ticket states, transitions, and operations

API Reference

Explore all 18 endpoints with request/response schemas

​
Key features

Role-based access control

Four roles — ADMIN, MESA, AREA, USUARIO — each with precisely scoped endpoint access

Full ticket lifecycle

Create, assign, transfer, pause, reopen, cancel, and archive tickets through a structured state machine

SLA tracking

Automatic SLA calculation per ticket priority with hours-remaining and expiration indicators

Public ticket lookup

End-users can check ticket status with just their label and email — no account required

Dashboard & metrics

Role-filtered dashboards and full metrics endpoints for analytics and reporting

PostgreSQL stored procedures

Complex business logic encapsulated in database functions and stored procedures for consistency

​
Ticket request types

The API supports seven standardized ticket types aligned with ITIL best practices:
TypeDescription
PETICIONGeneral service request
QUEJAFormal complaint
RECLAMOEscalated claim or dispute
SUGERENCIAImprovement suggestion
INCIDENTEService disruption or failure
SOLICITUDSpecific resource request
CONSULTAInformation inquiry

​
Architecture overview

Mesa de Ayuda API
├── FastAPI application (main.py)
├── app/
│   ├── routers/        # HTTP endpoints (auth, tickets)
│   ├── schemas/        # Pydantic request/response models
│   ├── services/       # Business logic layer
│   ├── core/           # Config, security, dependencies
│   └── db/             # SQLAlchemy session management
└── PostgreSQL          # Stored procedures & functions
The API follows a clean layered architecture: routers handle HTTP concerns, services contain business logic, and PostgreSQL stored procedures (sp_*) and functions (fn_*) enforce data integrity and complex operations at the database level.

​
Tech stack

  • Framework: FastAPI
  • Database: PostgreSQL via SQLAlchemy
  • Authentication: JWT (python-jose) with bcrypt password hashing
  • Validation: Pydantic v2
  • Server: Uvicorn

​
Next steps

Quickstart

Create your first ticket

Roles

Understand access control

API Reference

Browse all endpoints

Build docs developers (and LLMs) love

Get started for freeTalk to us