Projects API

# 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**: ```http GET /api/projects/companies?status=ACTIVE&limit=10 Authorization: Bearer ``` **Response 200**: ```json { "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**: ```json { "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**: ```json { "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**: ```json { "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): ```json { "title": "Nuevo título del proyecto", "description": "Nueva descripción actualizada", "amount": 175000, "status": "ACTIVE" } ``` **Response 200**: ```json { "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**: ```json { "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**: ```json { "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**: ```json { "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**: ```json { "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**: ```json { "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**: ```json { "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**: ```json { "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**: ```http GET /api/projects/search?q=IA&type=ID®ion=BIZKAIA&minAmount=50000&maxAmount=200000 Authorization: Bearer ``` **Response 200**: ```json { "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**: ```json { "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**: ```json { "expedienteType": "ZE", "expedienteNumber": "ZE-2025-12345", "validationDate": "2025-01-03" } ``` **Response 200**: ```json { "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**: ```json { "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**: ```json { "amount": 25000, "entity": "SPRI", "program": "Hazitek 2025", "grantedDate": "2025-01-01", "notes": "Subvención para desarrollo de módulo IA" } ``` **Response 201**: ```json { "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](/docs/api/offers) - Sistema de ofertas para proyectos - [Marketplace API](/docs/api/marketplace) - Buscar proyectos con AutoMatch - [Pagos API](/docs/api/payments) - Procesar pagos con Stripe --- **Última actualización**: 3 enero 2026 | **Tiempo de lectura**: 15 minutos