Projects API

Gestión completa de proyectos I+D+i: creación, edición, búsqueda, documentos, ITC, y exportación.

---

Visión General

Base Path: /api/projects

Autenticación: Todos los endpoints requieren JWT válido

Project Types:

• ID - Investigación y Desarrollo (I+D)
• IT - Innovación Tecnológica (IT)
• INNOVACION - Otros proyectos de innovación

Project Status:

• DRAFT - Borrador
• ACTIVE - Activo en marketplace
• FUNDED - Financiado completamente
• CLOSED - Cerrado

---

Endpoints Principales

GET /api/projects/companies

Obtiene todos los proyectos de las empresas del usuario autenticado.

Autenticación: Requerida (JWT)

Query Parameters:

• status (opcional): Filtrar por estado (DRAFT, ACTIVE, FUNDED, CLOSED)
• type (opcional): Filtrar por tipo (ID, IT, INNOVACION)
• page (opcional): Número de página (default: 1)
• limit (opcional): Resultados por página (default: 20)

Request:

GET /api/projects/companies?status=ACTIVE&limit=10
Authorization: Bearer <token>

Response 200:

{
  "success": true,
  "data": [
    {
      "id": "proj_123",
      "title": "Sistema IA para diagnóstico médico",
      "description": "Plataforma de IA para asistir en diagnósticos médicos",
      "type": "ID",
      "status": "ACTIVE",
      "amount": 150000,
      "fundedAmount": 75000,
      "fundingProgress": 50,
      "region": "BIZKAIA",
      "sector": "Biotecnología / Salud",
      "company": {
        "id": "comp_456",
        "name": "MedTech Innovations SL",
        "nif": "B12345678"
      },
      "deduction": {
        "baseImponible": 200000,
        "deduccionID": 140000,
        "deduccionIT": 0,
        "totalDeduccion": 140000,
        "porcentaje": 70
      },
      "createdAt": "2025-01-01T00:00:00Z",
      "updatedAt": "2025-01-03T10:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 25,
    "pages": 3
  }
}

---

POST /api/projects

Crea un nuevo proyecto.

Autenticación: Requerida (JWT)

Request Body:

{
  "companyId": "comp_456",
  "title": "Sistema IA para diagnóstico médico",
  "description": "Plataforma de IA que asiste a médicos en diagnósticos precisos mediante análisis de imágenes médicas y datos clínicos",
  "type": "ID",
  "amount": 150000,
  "region": "BIZKAIA",
  "sector": "Biotecnología / Salud",
  "deduction": {
    "baseImponible": 200000,
    "deduccionID": 140000,
    "deduccionIT": 0,
    "porcentajeID": 70,
    "porcentajeIT": 0
  },
  "startDate": "2025-01-01",
  "endDate": "2025-12-31",
  "teamSize": 8
}

Validación:

• title: 5-200 caracteres
• description: 20-2000 caracteres
• amount: Número positivo
• type: ID, IT, INNOVACION
• region: BIZKAIA, GIPUZKOA, ARABA, NAVARRA
• companyId: Debe pertenecer al usuario autenticado

Response 201:

{
  "success": true,
  "data": {
    "id": "proj_789",
    "title": "Sistema IA para diagnóstico médico",
    "status": "DRAFT",
    "createdAt": "2025-01-03T10:30:00Z"
  }
}

Errors:

• 400 - Validación fallida
• 403 - No tienes acceso a esta empresa
• 404 - Empresa no encontrada

---

GET /api/projects/{projectId}

Obtiene detalles completos de un proyecto específico.

Autenticación: Requerida (JWT)

Path Parameters:

• projectId: ID del proyecto

Response 200:

{
  "success": true,
  "data": {
    "id": "proj_123",
    "title": "Sistema IA para diagnóstico médico",
    "description": "Plataforma de IA para asistir en diagnósticos médicos",
    "type": "ID",
    "status": "ACTIVE",
    "amount": 150000,
    "fundedAmount": 75000,
    "fundingProgress": 50,
    "region": "BIZKAIA",
    "sector": "Biotecnología / Salud",
    "startDate": "2025-01-01",
    "endDate": "2025-12-31",
    "teamSize": 8,
    "company": {
      "id": "comp_456",
      "name": "MedTech Innovations SL",
      "nif": "B12345678",
      "logo": "https://cdn.64bis.eus/logos/comp_456.png"
    },
    "deduction": {
      "baseImponible": 200000,
      "deduccionID": 140000,
      "deduccionIT": 0,
      "totalDeduccion": 140000,
      "porcentajeID": 70,
      "porcentajeIT": 0
    },
    "documents": [
      {
        "id": "doc_123",
        "name": "Memoria Técnica.pdf",
        "type": "MEMORIA_TECNICA",
        "url": "https://cdn.64bis.eus/docs/doc_123.pdf",
        "uploadedAt": "2025-01-02T14:20:00Z"
      }
    ],
    "offers": [
      {
        "id": "off_789",
        "amount": 50000,
        "status": "PENDING",
        "investor": {
          "id": "inv_999",
          "name": "Capital Ventures SL"
        },
        "createdAt": "2025-01-03T09:00:00Z"
      }
    ],
    "createdAt": "2025-01-01T00:00:00Z",
    "updatedAt": "2025-01-03T10:30:00Z"
  }
}

---

PUT /api/projects/{projectId}

Actualiza un proyecto existente.

Autenticación: Requerida (JWT)

Path Parameters:

• projectId: ID del proyecto

Request Body (todos los campos opcionales):

{
  "title": "Nuevo título del proyecto",
  "description": "Nueva descripción actualizada",
  "amount": 175000,
  "status": "ACTIVE"
}

Response 200:

{
  "success": true,
  "data": {
    "id": "proj_123",
    "title": "Nuevo título del proyecto",
    "updatedAt": "2025-01-03T11:00:00Z"
  }
}

Errors:

• 403 - No tienes permisos para editar este proyecto
• 404 - Proyecto no encontrado

---

DELETE /api/projects/{projectId}

Elimina un proyecto (solo si está en estado DRAFT).

Autenticación: Requerida (JWT)

Path Parameters:

• projectId: ID del proyecto

Response 200:

{
  "success": true,
  "data": {
    "message": "Proyecto eliminado correctamente"
  }
}

Errors:

• 400 - No se puede eliminar proyecto ACTIVE/FUNDED
• 403 - No tienes permisos
• 404 - Proyecto no encontrado

---

Documentos

POST /api/projects/{projectId}/documents

Sube un documento al proyecto.

Autenticación: Requerida (JWT)

Content-Type: multipart/form-data

Form Data:

• file: Archivo (PDF, max 10MB)
• type: Tipo de documento (MEMORIA_TECNICA, PRESUPUESTO, INFORME, OTRO)
• name: Nombre descriptivo del documento

Response 201:

{
  "success": true,
  "data": {
    "id": "doc_456",
    "name": "Memoria Técnica 2025.pdf",
    "type": "MEMORIA_TECNICA",
    "url": "https://cdn.64bis.eus/docs/doc_456.pdf",
    "size": 2048576,
    "uploadedAt": "2025-01-03T12:00:00Z"
  }
}

Errors:

• 400 - Archivo demasiado grande o formato inválido
• 403 - No tienes permisos
• 404 - Proyecto no encontrado

---

GET /api/projects/{projectId}/documents

Lista todos los documentos de un proyecto.

Autenticación: Requerida (JWT)

Response 200:

{
  "success": true,
  "data": [
    {
      "id": "doc_123",
      "name": "Memoria Técnica.pdf",
      "type": "MEMORIA_TECNICA",
      "url": "https://cdn.64bis.eus/docs/doc_123.pdf",
      "size": 1048576,
      "uploadedAt": "2025-01-02T14:20:00Z"
    },
    {
      "id": "doc_124",
      "name": "Presupuesto 2025.xlsx",
      "type": "PRESUPUESTO",
      "url": "https://cdn.64bis.eus/docs/doc_124.xlsx",
      "size": 524288,
      "uploadedAt": "2025-01-02T15:30:00Z"
    }
  ]
}

---

DELETE /api/projects/{projectId}/documents/{documentId}

Elimina un documento del proyecto.

Autenticación: Requerida (JWT)

Response 200:

{
  "success": true,
  "data": {
    "message": "Documento eliminado correctamente"
  }
}

---

ITC (Informe Técnico de Certificación)

POST /api/projects/{projectId}/itc

Crea un nuevo ITC para el proyecto.

Autenticación: Requerida (JWT)

Request Body:

{
  "consultant": {
    "name": "Juan Pérez",
    "nif": "12345678A",
    "colegio": "COITPV"
  },
  "analysis": {
    "tecnologias": ["IA", "Machine Learning", "Visión por computador"],
    "novedadTecnologica": "Alto",
    "riesgoTecnico": "Medio",
    "conclusion": "Proyecto cumple requisitos I+D según Art. 35 LIS"
  }
}

Response 201:

{
  "success": true,
  "data": {
    "id": "itc_789",
    "projectId": "proj_123",
    "status": "DRAFT",
    "createdAt": "2025-01-03T13:00:00Z"
  }
}

---

GET /api/projects/{projectId}/itc

Obtiene el ITC del proyecto.

Autenticación: Requerida (JWT)

Response 200:

{
  "success": true,
  "data": {
    "id": "itc_789",
    "projectId": "proj_123",
    "status": "APPROVED",
    "consultant": {
      "name": "Juan Pérez",
      "nif": "12345678A",
      "colegio": "COITPV"
    },
    "analysis": {
      "tecnologias": ["IA", "Machine Learning", "Visión por computador"],
      "novedadTecnologica": "Alto",
      "riesgoTecnico": "Medio",
      "conclusion": "Proyecto cumple requisitos I+D según Art. 35 LIS"
    },
    "createdAt": "2025-01-03T13:00:00Z",
    "approvedAt": "2025-01-03T14:00:00Z"
  }
}

---

Búsqueda y Filtrado

GET /api/projects/search

Busca proyectos con filtros avanzados.

Autenticación: Requerida (JWT)

Query Parameters:

• q (opcional): Búsqueda de texto libre
• type (opcional): Tipo de proyecto (ID, IT, INNOVACION)
• region (opcional): Región (BIZKAIA, GIPUZKOA, ARABA, NAVARRA)
• sector (opcional): Sector
• minAmount (opcional): Importe mínimo
• maxAmount (opcional): Importe máximo
• status (opcional): Estado del proyecto
• page (opcional): Página (default: 1)
• limit (opcional): Resultados por página (default: 20)

Request:

GET /api/projects/search?q=IA&type=ID&region=BIZKAIA&minAmount=50000&maxAmount=200000
Authorization: Bearer <token>

Response 200:

{
  "success": true,
  "data": [
    {
      "id": "proj_123",
      "title": "Sistema IA para diagnóstico médico",
      "type": "ID",
      "amount": 150000,
      "region": "BIZKAIA",
      "matchScore": 95
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 12,
    "pages": 1
  }
}

---

Exportación

GET /api/projects/export

Exporta proyectos en formato Excel.

Autenticación: Requerida (JWT)

Query Parameters:

• format (opcional): Formato (xlsx, csv) - default: xlsx
• status (opcional): Filtrar por estado
• companyId (opcional): Filtrar por empresa

Response 200:

• Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
• Headers: Content-Disposition: attachment; filename="proyectos_2025-01-03.xlsx"

Columnas del Excel:

• ID del Proyecto
• Título
• Empresa
• Tipo
• Estado
• Importe Solicitado
• Importe Financiado
• Progreso (%)
• Región
• Sector
• Fecha Creación
• Deducción I+D
• Deducción IT
• Deducción Total

---

Proyectos Anónimos (Marketplace)

GET /api/projects/anonymous

Obtiene proyectos públicos (datos anonimizados para marketplace).

Autenticación: Requerida (JWT)

Query Parameters:

• status (opcional): Filtrar por estado (solo ACTIVE por defecto)
• type (opcional): Tipo de proyecto
• region (opcional): Región
• page (opcional): Página
• limit (opcional): Resultados por página

Response 200:

{
  "success": true,
  "data": [
    {
      "id": "proj_123",
      "title": "Sistema IA para sector salud",
      "description": "Plataforma de IA para aplicaciones médicas",
      "type": "ID",
      "amount": 150000,
      "fundedAmount": 75000,
      "fundingProgress": 50,
      "region": "BIZKAIA",
      "sector": "Biotecnología / Salud",
      "daysRemaining": 15,
      "featured": true,
      "urgent": false,
      "deduction": {
        "totalDeduccion": 140000,
        "porcentaje": 70
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 45,
    "pages": 3
  }
}

Nota: Los datos de la empresa están anonimizados para proteger privacidad.

---

Compliance y Validación

POST /api/projects/{projectId}/compliance

Valida compliance del proyecto (expediente ZE/ZL/QB).

Autenticación: Requerida (JWT)

Request Body:

{
  "expedienteType": "ZE",
  "expedienteNumber": "ZE-2025-12345",
  "validationDate": "2025-01-03"
}

Response 200:

{
  "success": true,
  "data": {
    "valid": true,
    "expediente": {
      "type": "ZE",
      "number": "ZE-2025-12345",
      "status": "APPROVED",
      "validatedAt": "2025-01-03T15:00:00Z"
    },
    "warnings": [],
    "errors": []
  }
}

Validaciones:

• Formato de expediente correcto (ZE-YYYY-NNNNN)
• Fecha de validación válida
• Documentación requerida adjunta

---

Subsidios y Subvenciones

POST /api/projects/{projectId}/subsidies/upload

Sube documentación de subvención recibida.

Autenticación: Requerida (JWT)

Content-Type: multipart/form-data

Form Data:

• file: PDF de resolución de subvención
• amount: Importe de la subvención
• entity: Entidad que otorga (ej: "SPRI")
• program: Nombre del programa

Response 201:

{
  "success": true,
  "data": {
    "id": "sub_123",
    "amount": 25000,
    "entity": "SPRI",
    "program": "Hazitek 2025",
    "documentUrl": "https://cdn.64bis.eus/subsidies/sub_123.pdf",
    "uploadedAt": "2025-01-03T16:00:00Z"
  }
}

---

POST /api/projects/{projectId}/subsidies/manual

Registra subvención manualmente (sin documento).

Autenticación: Requerida (JWT)

Request Body:

{
  "amount": 25000,
  "entity": "SPRI",
  "program": "Hazitek 2025",
  "grantedDate": "2025-01-01",
  "notes": "Subvención para desarrollo de módulo IA"
}

Response 201:

{
  "success": true,
  "data": {
    "id": "sub_124",
    "amount": 25000,
    "entity": "SPRI",
    "program": "Hazitek 2025",
    "grantedDate": "2025-01-01",
    "createdAt": "2025-01-03T16:30:00Z"
  }
}

Nota: Las subvenciones se descuentan automáticamente de la base imponible para deducciones.

---

Errores Comunes

403 Forbidden - "No tienes acceso a esta empresa"

Causa: Intentas crear/editar proyecto de empresa que no te pertenece

Solución: Verifica que el companyId en el request body pertenece al usuario autenticado

400 Bad Request - "Proyecto ya está ACTIVE"

Causa: Intentas editar campos que no se pueden modificar en proyectos activos

Solución: Solo ciertos campos (descripción, documentos) se pueden editar en proyectos ACTIVE

400 Bad Request - "Importe supera el límite permitido"

Causa: El importe solicitado es demasiado alto para el tipo de proyecto

Solución: Revisar límites por tipo de proyecto y región foral

---

Próximos Pasos

• Ofertas API - Sistema de ofertas para proyectos
• Marketplace API - Buscar proyectos con AutoMatch
• Pagos API - Procesar pagos con Stripe

---

Última actualización: 3 enero 2026 | Tiempo de lectura: 15 minutos