Gestión de Obras y Proyectos

El recurso /projects gestiona las obras, proyectos y centros de coste en BaseGes ERP. Es el eje vertebrador donde se imputan horas de personal, materiales, presupuestos, partes de trabajo y compras asociadas a un cliente titular.

Seguridad

Requiere autorización mediante cabecera HTTP:

• X-Api-Key: {tu_clave_api} o Authorization: Bearer {tu_token_jwt}

---

Resumen de Operaciones

Método	Endpoint	Acción	Cuerpo de Petición	Código Éxito
GET	/projects	Listado paginado con filtros	Ninguno	200 OK
GET	/projects/{code}	Detalle completo de una obra	Ninguno	200 OK
POST	/projects	Alta de nueva obra vinculada a cliente	JSON (CreateProjectCommand)	201 Created
PATCH	/projects/{code}	Actualización de la obra	JSON (UpdateProjectCommand)	200 OK

---

1. Alta de una Nueva Obra (POST)

POST /projects

Crea una nueva obra o centro de coste en el ERP y la asocia al cliente correspondiente.

Reglas de Negocio y Normalización

1. Normalización del Código (Code):
   • Si se informa manualmente, el ERP lo normaliza a 8 caracteres añadiendo ceros a la izquierda (ejemplo: si envían "1234", se guardará como "00001234").
   • Si se omite o es null, se genera automáticamente con el siguiente contador disponible.
2. Validación de Cliente (CustomerCode):
   • Debe corresponder a un cliente que exista en la base de datos de BaseGes. De lo contrario, la petición fallará con un error 400 Bad Request.
3. Validación de Encargado (ManagerCode):
   • Si se especifica, debe coincidir con el código de un operario o empleado dado de alta en el apartado de Personal.

Parámetros del Payload JSON

Campo	Tipo	Obligatorio	Descripción
name	string	Sí	Denominación o título descriptivo de la obra.
customerCode	string	No	Código del cliente titular (debe existir en BaseGes).
code	string	No	Código manual (se normaliza a 8 caracteres). Si se omite, se autonumera.
address	string	No	Dirección o emplazamiento físico de la obra.
postalCode	string	No	Código postal del lugar de ejecución.
city	string	No	Población donde se realiza el proyecto.
province	string	No	Provincia.
countryCode	string	No	Código del país (ej. "ES").
status	number	No	Estado de la obra (ver tabla de valores más abajo). Predeterminado: 0 (Abierto).
startDate	date	No	Fecha de inicio prevista o real (YYYY-MM-DD).
endDate	date	No	Fecha estimada de finalización (YYYY-MM-DD).
managerCode	string	No	Código del encargado/jefe de obra (debe existir en /employees).
mainProject	string	No	Código de obra padre (si se trata de una sub-obra o fase).

Estados Permitidos de la Obra (status)

Valor Numérico	Nombre Enum	Significado Operativo
0	Abierto	Obra activa y disponible para imputar gastos, horas y compras.
1	Cerrado	Obra concluida temporalmente.
2	Histórico	Archivada para consultas históricas.
3	Anulada	Obra cancelada sin ejecución.
4	EnEstudio	Fase previa de licitación, estudio o presupuesto.
5	Liquidada	Finiquitada contable y financieramente.

Ejemplo de Petición POST

POST /projects HTTP/1.1
Host: localhost:5000
Content-Type: application/json
X-Api-Key: tu-api-key-secreta

{
  "name": "Instalación Eléctrica y Clima Nave Logística Sector 4",
  "customerCode": "CLI00120",
  "address": "Parque Empresarial Puerta de Madrid, C/ Logística, 10",
  "postalCode": "28830",
  "city": "San Fernando de Henares",
  "province": "Madrid",
  "status": 0,
  "startDate": "2026-11-01T00:00:00Z",
  "endDate": "2027-04-30T00:00:00Z",
  "managerCode": "EMP007"
}

Respuesta Exitosa (201 Created)

{
  "code": "00000412",
  "name": "Instalación Eléctrica y Clima Nave Logística Sector 4",
  "customerCode": "CLI00120"
}

---

2. Actualización de una Obra (PATCH)

PATCH /projects/{code}

Permite modificar los datos de una obra existente (cambiar estado a cerrado, actualizar fechas reales de fin, cambiar el encargado, etc.):

PATCH /projects/00000412 HTTP/1.1
Host: localhost:5000
Content-Type: application/json
X-Api-Key: tu-api-key-secreta

{
  "name": "Instalación Eléctrica y Clima Nave Logística Sector 4 (Fase 1 Finalizada)",
  "customerCode": "CLI00120",
  "status": 1,
  "endDate": "2027-05-15T00:00:00Z",
  "managerCode": "EMP007"
}

---

3. Consultas y Filtros (GET)

GET /projects

Permite obtener el listado con filtros especializados:

• CustomerCode: Todas las obras de un cliente concreto.
• Status: Filtrar solo obras abiertas (status=0) o en estudio (status=4).
• search: Búsqueda de texto en código de obra, nombre del proyecto, cliente, dirección, CP o provincia.
• updatedAfter: Sincronización incremental de obras modificadas recientemente.