Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/LizandroCanul/back_sdo/llms.txt

Use this file to discover all available pages before exploring further.

​
Get Started in 5 Minutes

This guide will help you get the API running locally and make your first request. You’ll set up the database, start the server, and authenticate to retrieve public works data.
1

Clone the Repository

First, clone the repository and navigate to the project directory:
git clone <repository-url>
cd back_sdo
2

Install Dependencies

Install all required npm packages:
npm install
3

Start the Database

Use Docker Compose to launch PostgreSQL with PostGIS:
docker-compose up -d
This starts a PostgreSQL database with the PostGIS extension on port 5432.
Make sure Docker is installed and running on your system before executing this command.
4

Configure Environment

Create a .env file in the project root with your database credentials:
.env
DATABASE_HOST=localhost
DATABASE_PORT=5432
DATABASE_USER=admin
DATABASE_PASSWORD=password123
DATABASE_NAME=obras_yucatan_db
These are the default credentials from docker-compose.yml. Change them for production use.
5

Start the Development Server

Launch the API in development mode with auto-reload:
npm run start:dev
You should see:
🚀 Servidor corriendo en http://localhost:3000

​
Make Your First Request

Now that the API is running, let’s authenticate and retrieve some data.

​
1. Login to Get a JWT Token

The API uses JWT authentication. First, obtain an access token: 
curl -X POST http://localhost:3000/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "your-password"
  }'
Response: 
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": 1,
    "email": "[email protected]",
    "role": "admin"
  }
}
Save the access_token - you’ll need it for authenticated requests.

​
2. Retrieve Public Works

Use the token to fetch the list of obras (public works): 
curl -X GET http://localhost:3000/obras \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Response: 
[
  {
    "id": 1,
    "numeroObra": 1,
    "claveUnica": "YUC-2024-001",
    "nombre": "Pavimentación de Calle Principal",
    "descripcion": "Obra de pavimentación en zona centro",
    "monto": 1500000.00,
    "municipio": {
      "id": 1,
      "nombre": "Mérida"
    },
    "estatusObra": {
      "id": 2,
      "nombre": "En Proceso"
    },
    "ejercicioFiscal": {
      "id": 1,
      "anio": 2024
    }
  }
]

​
3. Get a Specific Obra

Retrieve details for a single public work by ID: 
curl -X GET http://localhost:3000/obras/1 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

​
Understanding the Response

Each obra (public work) includes:
  • numeroObra: Sequential number for the fiscal year
  • claveUnica: Unique identifier for the project
  • nombre: Project name
  • monto: Budget amount in Mexican pesos
  • municipio: Associated municipality
  • estatusObra: Current project status
  • ejercicioFiscal: Fiscal year
  • dependencia: Government agency responsible
  • ubicaciones: Geographic locations (with PostGIS data)
const response = await fetch('http://localhost:3000/obras', {
  headers: {
    'Authorization': `Bearer ${accessToken}`
  }
});

const obras = await response.json();
console.log(obras);

​
Role-Based Access Control

The API implements role-based permissions:
ActionAdminUser
View obras✅✅
Create obra✅❌
Update obra✅❌
Delete obra✅❌
Only admin users can create, update, or delete obras. Regular users have read-only access.

​
Filtering and Pagination

The API supports query parameters for filtering: 
# Filter by municipality
curl -X GET "http://localhost:3000/obras?municipioId=1" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# Filter by status
curl -X GET "http://localhost:3000/obras?estatusObraId=2" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# Filter by fiscal year
curl -X GET "http://localhost:3000/obras?ejercicioFiscalId=1" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

​
Next Steps

Full Installation Guide

Learn about production setup, migrations, and troubleshooting

Authentication Guide

Deep dive into JWT authentication and role management

API Reference

Explore all available endpoints and parameters

Database Schema

Understand the data model and relationships

Build docs developers (and LLMs) love

Get started for freeTalk to us