Skip to main content
1

Configure your environment

Create a .env file in the project root with the following variables:
.env
DATABASE_URL=postgresql://user:password@localhost:5432/mesa_de_ayuda
SECRET_KEY=your-secret-key-change-in-production
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=120
Never commit your .env file to version control. Add it to .gitignore before your first commit.
VariableRequiredDefaultDescription
DATABASE_URLYes—PostgreSQL connection string. The server will not start without this.
SECRET_KEYYesCHANGE_MESecret used to sign JWT tokens. Use a long random string in production.
ALGORITHMNoHS256JWT signing algorithm.
ACCESS_TOKEN_EXPIRE_MINUTESNo120Token lifetime in minutes.
2

Install dependencies

Install the Python packages listed in requirements.txt:
pip install -r requirements.txt
Key packages installed:
  • FastAPI — web framework
  • Uvicorn — ASGI server
  • SQLAlchemy + psycopg2-binary — database ORM and PostgreSQL driver
  • python-jose — JWT encoding and decoding
  • passlib[bcrypt] — password hashing
3

Run the development server

Start the API with Uvicorn:
uvicorn main:app --reload
The server starts at http://localhost:8000. The --reload flag restarts the server automatically when you change source files.
Visit http://localhost:8000/docs for the interactive Swagger UI, or http://localhost:8000/redoc for the ReDoc interface.
4

Obtain a JWT token

Send your credentials to the login endpoint to receive an access token:
curl -X POST http://localhost:8000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "your-password"
  }'
A successful response returns your token and user details:
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "user": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "email": "[email protected]",
    "rol": "ADMIN",
    "area": null,
    "nombre": "Ana García"
  }
}
Save the access_token value — you will include it in the Authorization header for all subsequent requests.
5

Create your first ticket

The ticket creation endpoint is public — no token required. Send a POST to /api/tickets/crear with the requester’s details and ticket information:
curl -X POST http://localhost:8000/api/tickets/crear \
  -H "Content-Type: application/json" \
  -d '{
    "nombre": "Ana García",
    "email": "[email protected]",
    "tipo": "INCIDENTE",
    "categoria": "Sistemas",
    "descripcion": "No puedo iniciar sesión desde esta mañana. Aparece error 403.",
    "prioridad": "ALTA"
  }'
A successful response returns the ticket reference and SLA deadline:
{
  "ticketUuid": "e3b2c1d4-5a6f-7890-abcd-ef1234567890",
  "ticketLabel": "TKT-2026-00042",
  "estado": "ABIERTO",
  "tipo": "INCIDENTE",
  "prioridad": "ALTA",
  "slaHoras": 4,
  "fechaCreacion": "2026-03-24T09:15:00Z",
  "fechaLimiteSla": "2026-03-24T13:15:00Z",
  "mensaje": "Ticket creado correctamente"
}
Save the ticketLabel value. Anyone can look up ticket status later using the label and the requester’s email via POST /api/tickets/consultar.

​
Complete end-to-end example

The following script demonstrates the full flow: authenticate as an agent, capture the token, then check the dashboard. 
# 1. Log in and store the token
TOKEN=$(curl -s -X POST http://localhost:8000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "password": "your-password"}' \
  | python3 -c "import sys, json; print(json.load(sys.stdin)['access_token'])")

# 2. View the ticket dashboard (role-filtered)
curl -X GET http://localhost:8000/api/tickets/dashboard \
  -H "Authorization: Bearer $TOKEN"

​
Next steps

Authentication

Learn about JWT Bearer tokens, roles, and how to handle 401 and 403 errors.

API Reference

Browse all available endpoints with request and response schemas.

Build docs developers (and LLMs) love

Get started for freeTalk to us