Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/JDzuu/AplicativoWEB_GestorFinanciero/llms.txt

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

The project endpoints are the backbone of Gestor Financiero. They let you create and edit financial projects, advance them through their lifecycle (from iniciando to finalizado), pause and resume work, cancel when needed, and generate a closure PDF summary once a project is complete. Every mutating response returns the full project object — including all computed financial fields — so your UI always has a consistent, up-to-date snapshot after each action.

​
GET /proyectos

Returns a list of all projects, each enriched with computed financial totals and state display metadata. This lightweight variant omits the individual entradas and salidas arrays for performance; use GET /proyectos/{proyecto_id} to retrieve the full detail.

​
Response

​
id
integer
Unique identifier of the project.
​
nombre
string
Project name (up to 200 characters).
​
cliente
string
Client name associated with the project (up to 200 characters).
​
tipo
string
Project type. One of: Construcción, Remodelación, Muebles, Mantenimiento, Otro.
​
total
decimal
Contracted total amount for the project.
​
fecha_inicio
string
Project start date in YYYY-MM-DD format.
​
estado
string
Current lifecycle state. One of: iniciando, proceso, acabando, pausa, finalizado, cancelado.
​
estado_previo
string | null
The active state the project was in before being paused. null when not paused.
​
fecha_fin
string | null
Closing date (YYYY-MM-DD) set when the project is finalized or cancelled. null while still active.
​
creado
string
ISO timestamp of when the project record was created.
​
total_entradas
decimal
Sum of all client payments received so far.
​
total_salidas
decimal
Sum of all expenses registered so far.
​
saldo
decimal
Current balance: total_entradas − total_salidas.
​
ganancia
decimal
Net profit computed as total_entradas − total_salidas.
​
porcentaje
integer
Percentage of the contracted total that has been collected (0–100).
​
duracion
integer | null
Total elapsed days between fecha_inicio and fecha_fin (or today if still active). null if dates are invalid.
​
estado_texto
string
Human-readable label for the current state (e.g., "En proceso", "Finalizado").
​
estado_color
string
UI color hint for the current state (e.g., "azul", "verde", "rojo").
curl -X GET http://localhost:8000/proyectos \
  --cookie cookies.txt

​
GET /proyectos/{proyecto_id}

Returns the full detail of a single project, including all associated payment records, expense records, and computed financial fields.

​
Path Parameters

​
proyecto_id
integer
required
The numeric ID of the project to retrieve.

​
Response

Returns the same fields as GET /proyectos, plus:
​
entradas
array
List of all client payment records for this project.
​
salidas
array
List of all expense records for this project.
​
dias_pausa
integer
Total number of days the project has spent in the pausa state.
​
dias_efectivos
integer | null
Effective working days: duracion − dias_pausa. null if duracion is unavailable.
Returns 404 if no project with the given proyecto_id exists.
curl -X GET http://localhost:8000/proyectos/42 \
  --cookie cookies.txt

​
POST /proyectos

Creates a new project. The project is created in iniciando state with no financial records.

​
Request Body

​
nombre
string
required
Project name. Maximum 200 characters. Cannot be blank.
​
cliente
string
required
Client name. Maximum 200 characters. Cannot be blank.
​
tipo
string
required
Project type. Maximum 60 characters. Must be one of: Construcción, Remodelación, Muebles, Mantenimiento, Otro.
​
total
decimal
required
Contracted total amount. Must be greater than 0.
​
fecha_inicio
string
required
Project start date in YYYY-MM-DD ISO format. Maximum 20 characters.

​
Response

Returns the full project object (same shape as GET /proyectos/{proyecto_id}).
Returns 400 with a field-keyed error object if any validation rule fails (e.g., blank name, non-positive total, invalid date).
curl -X POST http://localhost:8000/proyectos \
  -H "Content-Type: application/json" \
  --cookie cookies.txt \
  -H "X-CSRF-Token: <csrf>" \
  -d '{
    "nombre": "Remodelación Oficina Central",
    "cliente": "Empresa Ejemplo S.A.",
    "tipo": "Remodelación",
    "total": 15000.00,
    "fecha_inicio": "2025-02-01"
  }'

​
PUT /proyectos/{proyecto_id}

Updates the metadata of an existing project. Accepts the same body as POST /proyectos. Financial records and lifecycle state are unaffected by this call.

​
Path Parameters

​
proyecto_id
integer
required
The numeric ID of the project to update.

​
Request Body

Same fields as POST /proyectos: nombre, cliente, tipo, total, fecha_inicio.

​
Response

Returns the full updated project object.
Returns 404 if the project does not exist. Returns 400 if validation fails.
curl -X PUT http://localhost:8000/proyectos/42 \
  -H "Content-Type: application/json" \
  --cookie cookies.txt \
  -H "X-CSRF-Token: <csrf>" \
  -d '{
    "nombre": "Remodelación Oficina Central — Fase 2",
    "cliente": "Empresa Ejemplo S.A.",
    "tipo": "Remodelación",
    "total": 18500.00,
    "fecha_inicio": "2025-02-01"
  }'

​
POST /proyectos/{proyecto_id}/estado

Manually advances or changes the active state of a project within the set of working states. Use this to move a project between iniciando, proceso, and acabando as work progresses.

​
Path Parameters

​
proyecto_id
integer
required
The numeric ID of the project.

​
Request Body

​
estado
string
required
The target active state. Must be one of: iniciando, proceso, acabando.

​
Response

Returns the full project object with the updated estado.
Returns 400 if the supplied state is not one of the three active states. To pause, cancel, or finalize a project use the dedicated endpoints below.
curl -X POST http://localhost:8000/proyectos/42/estado \
  -H "Content-Type: application/json" \
  --cookie cookies.txt \
  -H "X-CSRF-Token: <csrf>" \
  -d '{"estado": "proceso"}'

​
POST /proyectos/{proyecto_id}/finalizar

Marks a project as finalizado and records today as fecha_fin. This transition is only allowed when 100 % of the contracted total has been collected via payment records.

​
Path Parameters

​
proyecto_id
integer
required
The numeric ID of the project to finalize.

​
Response

Returns the full project object with estado set to finalizado and fecha_fin populated.
Returns 400 with the message “Solo se puede finalizar cuando el proyecto está 100% cobrado.” if the collected amount has not yet reached total. Returns 404 if the project does not exist.

​
POST /proyectos/{proyecto_id}/cancelar

Cancels a project from any non-closed state (iniciando, proceso, acabando, or pausa). If the project is currently paused, the open pause period is automatically closed before the cancellation is applied. Records today as fecha_fin.

​
Path Parameters

​
proyecto_id
integer
required
The numeric ID of the project to cancel.

​
Response

Returns the full project object with estado set to cancelado and fecha_fin populated.
Returns 400 if the project is already in a closed state (finalizado or cancelado). Returns 404 if the project does not exist.

​
POST /proyectos/{proyecto_id}/pausar

Pauses a project that is currently in one of the three active states. Records a pause entry with today as the start date, and stores the current state in estado_previo so it can be restored on resume.

​
Path Parameters

​
proyecto_id
integer
required
The numeric ID of the project to pause.

​
Response

Returns the full project object with estado set to pausa and estado_previo holding the previous active state.
Returns 400 if the project is not in an active state (iniciando, proceso, or acabando). A project that is already paused, finalized, or cancelled cannot be paused again.
curl -X POST http://localhost:8000/proyectos/42/pausar \
  --cookie cookies.txt \
  -H "X-CSRF-Token: <csrf>"

​
POST /proyectos/{proyecto_id}/reanudar

Resumes a paused project. Closes the open pause period (recording today as the end date) and restores the state stored in estado_previo. If estado_previo is missing for any reason, the project falls back to proceso.

​
Path Parameters

​
proyecto_id
integer
required
The numeric ID of the project to resume.

​
Response

Returns the full project object with estado restored to the previous active state and the pause period closed.
Returns 400 if the project is not currently in pausa state. Returns 404 if the project does not exist.
curl -X POST http://localhost:8000/proyectos/42/reanudar \
  --cookie cookies.txt \
  -H "X-CSRF-Token: <csrf>"

​
GET /proyectos/{proyecto_id}/pdf

Generates and streams the project closure PDF, produced by ReportLab. The file includes project details, all payment records, all expense records, and a financial summary.

​
Path Parameters

​
proyecto_id
integer
required
The numeric ID of the project for which to generate the PDF.

​
Response

Returns a binary application/pdf response with the header: 
Content-Disposition: attachment; filename="cierre_{nombre}.pdf"
The filename is the project name sanitized to ASCII characters (accents stripped, special characters replaced with underscores).
The PDF is generated on demand on every request — there is no cached file. For projects with many records, allow a short generation delay.
Returns 404 if no project with the given proyecto_id exists.
curl -X GET http://localhost:8000/proyectos/42/pdf \
  --cookie cookies.txt \
  --output cierre_proyecto.pdf

​
GET /proyectos/{proyecto_id}/comparacion

Returns a budget-versus-actual cost comparison for a project. This endpoint is only meaningful for projects that originated from a presupuesto (budget) via the /presupuestos/{id}/convertir workflow. When no budget is linked, the response simply signals that with tiene_presupuesto: false.

​
Path Parameters

​
proyecto_id
integer
required
The numeric ID of the project.

​
Response

​
tiene_presupuesto
boolean
true if this project has an associated presupuesto; false otherwise. When false, no other fields are returned.
​
presupuesto_id
integer
ID of the linked presupuesto record.
​
items
array
The individual line items (partidas) from the original presupuesto. Useful for populating the partida_id field when registering salidas.
​
resumen
object
Budget summary with fields: total_materiales, total_mano_obra, total_gastos, costo_total, utilidad_pct, precio_venta, utilidad_monto, margen_pct.
​
comparacion
object
Per-category deviation analysis. Each key (materiales, mano_obra, gastos, costo_total, utilidad) contains estimado, real, desviacion, and desviacion_pct. Also includes sin_categoria for expenses with no category.
Returns 404 if the project does not exist.

​
GET /catalogos

Returns the static application catalogs used to populate dropdowns and validate inputs throughout the UI. Call this once on application load and cache the result client-side.

​
Response

​
tipos
array of strings
Valid project types: ["Construcción", "Remodelación", "Muebles", "Mantenimiento", "Otro"].
​
estados_activos
array of strings
The three active (non-terminal) states: ["iniciando", "proceso", "acabando"].
​
categorias_presupuesto
object
Map of category key → array of subcategory labels. Keys are materiales, mano_obra, gastos.
​
nombre_categoria
object
Human-readable display name for each category key: {"materiales": "Materiales", "mano_obra": "Mano de obra", "gastos": "Gastos adicionales"}.
curl -X GET http://localhost:8000/catalogos \
  --cookie cookies.txt
Example response: 
{
  "tipos": ["Construcción", "Remodelación", "Muebles", "Mantenimiento", "Otro"],
  "estados_activos": ["iniciando", "proceso", "acabando"],
  "categorias_presupuesto": {
    "materiales": ["Madera", "Melamina", "Herrajes", "Pinturas", "Cerámica", "Vidrio", "Metal", "Otros materiales"],
    "mano_obra": ["Carpintería", "Soldadura", "Pintura", "Albañilería", "Electricidad", "Plomería", "Otros servicios"],
    "gastos": ["Transporte", "Combustible", "Hospedaje", "Alquiler de herramientas", "Permisos", "Imprevistos", "Otros gastos"]
  },
  "nombre_categoria": {
    "materiales": "Materiales",
    "mano_obra": "Mano de obra",
    "gastos": "Gastos adicionales"
  }
}

Build docs developers (and LLMs) love

Get started for freeTalk to us