# API de Integración con SoftExpert Esta API proporciona una capa de integración con el sistema SoftExpert, permitiendo la gestión de workflows y documentos. La misma puede ser utilizada por cualquier institución que requiera interoperar con alguno de nuestros procesos de Softxpert. ## Versiones de la API La API está disponible en dos versiones: - v1: API base (requiere autenticación básica) - v2: API mejorada (requiere autenticación básica) ## Autenticación ### v1 Utiliza autenticación básica HTTP (Basic Auth). ### v2 Utiliza autenticación básica HTTP (Basic Auth). ## Endpoints ### Workflows #### v1 ##### Crea un nuevo workflow ``` POST /v1/workflows/create ``` ```json { "processId": "DPP01EXT", "userId": "spmws01", "workflowTitle": "Certificación Planos Electricos", "entityId": "mitur01", "source": "VUC", "entityAttribute": [ { "entityAttributeId": "numsolvuc", "entityAttributeValue": "VUC0032-2023" } ] } ``` ##### Asocia un documento a un workflow. ``` POST /v1/workflows/associate/document ``` ```json { "workflowId": "DPP01VUC000929", "activityId": "MITUR001", "documentId": "DPPDE006412" } ``` ##### Ejecuta una actividad en un workflow. ``` POST /v1/workflows/executeActivity ``` ```json { "workflowId": "DPP01VUC000929", "activityId": "MITUR001", "ActionSequence": "1" } ``` ##### Agrega registros hijos a una entidad del workflow. ``` POST /v1/workflows/addchilds ``` ```json { "childRelationshipId": "datoscopropieta", "mainEntityId": "mitur01", "rows": [ { "entityAttributes": [ { "entityAttributeId": "nombrecopropiet" }, { "entityAttributeId": "apellidoscoprop", "entityAttributeValue": "hola" } ] } ], "workflowId": "DPP01VUC000953" } ``` ##### Actualiza la información de pago en el workflow. ``` POST /v1/workflows/updatePayment ``` ```json { "action": "MITUR0001VUC", "amount": 20000, "approvalNumber": "", "documentReceipt": { "data": "base64 file or document url", "filename": "comprobante-de-pago-mitur-2023-12-21-042549.jpg" }, "folder": "DPPDE", "paymentDate": "", "paymentMethod": "DEPOSITO", "workflowId": "DPP01-VUC-0004" } ``` ##### Cancela un workflow. ``` PATCH /v1/workflows/cancel ``` ```json { "workflowId": "DPP01VUC000007", "explanation": "porque si", "userId": "spmws01" } ``` #### v2 ##### Crea un nuevo workflow. ``` POST /v2/workflows/create ``` ```json { "workflow": { "processId": "DPP01EXT", "workflowTitle": "Solicitud desde Prodominicana", "entityId": "mitur01", "source": "PRO", "documentsAssociationActivity": "MITUR002", "entityAttribute": [ { "entityAttributeId": "numsolvuc", "entityAttributeValue": "PROD-02" }, { "entityAttributeId": "origensolicitud", "entityAttributeValue": "PRO" } ] }, "payment": { "activityId": "MITUR002", "amount": 20000, "approvalNumber": "", "documentReceipt": { "data": "https://www.antennahouse.com/hubfs/xsl-fo-sample/pdf/basic-link-1.pdf", "filename": "comprobante-de-pago-mitur-2023-12-21-042549.jpg" }, "folder": "DPPDE",//fijo "paymentDate": "", "paymentMethod": "DEPOSITO" }, "children": [ { "childRelationshipId": "datoscopropieta", "mainEntityId": "mitur01", "rows": [ { "entityAttributes": [ { "entityAttributeId": "nombrecopropiet", "entityAttributeValue": "pedo" }, { "entityAttributeId": "apellidoscoprop", "entityAttributeValue": "soto" } ] } ] } ], "documents": [ { "attributes": null, "categoryId": "DPPDE", "data": "https://www.antennahouse.com/hubfs/xsl-fo-sample/pdf/basic-link-1.pdf", "filename": "Registro Mercantil.pdf", "title": "Registro Mercantil" } ] } ``` ##### Asocia un documento a un workflow. ``` POST /v2/workflows/associate/document ``` ```json { "workflowId": "DPP01VUC000929", "activityId": "MITUR001", "documentId": "DPPDE006412" } ``` ##### Ejecuta una actividad en un workflow. ``` POST /v2/workflows/executeActivity ``` ```json { "workflowId": "DPP01VUC000929", "activityId": "MITUR001", "ActionSequence": "1" } ``` ##### Actualiza la información de pago. ``` POST /v2/workflows/updatePayment ``` ```json { "action": "MITUR0001VUC", "amount": 20000, "approvalNumber": "", "documentReceipt": { "data": "base64 file or document url", "filename": "comprobante-de-pago-mitur-2023-12-21-042549.jpg" }, "folder": "DPPDE", "paymentDate": "", "paymentMethod": "DEPOSITO", "workflowId": "DPP01-VUC-0004" } ``` ##### Cancela un workflow. ``` PUT /v2/workflows/cancel ``` ```json { "workflowId": "DPP01VUC000007", "explanation": "porque si", "userId": "spmws01" } ``` ##### Resuelve una acción del workflow. ``` PUT /v2/workflows/actions/resolve ``` ```json { "workflowId" : "", "activityId" : "", "documents": [ { "attributes": null, "categoryId": "DPPDE", "data": "https://www.antennahouse.com/hubfs/xsl-fo-sample/pdf/basic-link-1.pdf", "filename": "Registro Mercantil.pdf", "title": "Registro Mercantil 2" } ] } ``` ##### Obtiene los documentos asociados a un workflow. ``` GET /v2/workflows/{workflowId}/documents ``` ### Documentos ##### Crea un nuevo documento. ``` POST /v1/documents/create ``` ```json { "categoryId": "DPPDE", "title": "TituloEjemplo", "userId": "spmws01", "filename": "Carta de solicitud.pdf", "data": "base64 file or document url", "attributes": [ { "AttributeId": "NumeroSolicitud", "AttributeValue": "DPP01VUC000885" } ] } ``` ##### Descarga un documento específico. ``` GET /v1/documents/{documentId}/download ``` ### Servicios Obtiene la ficha de un servicio publicado en la plataforma UCTT. ``` GET /v2/services/{id} ``` Obtiene información de un servicio específico. ## Configuración La API requiere las siguientes variables de entorno: ```env SE_USER=usuario_softexpert SE_PASSWORD=contraseña_softexpert SE_WORKFLOW_URL=url_softexpert_workflow ``` ## Respuestas La API utiliza respuestas JSON con los siguientes formatos: ### Éxito ```json { "success": true, "data": { ... } } ``` ### Error ```json { "success": false, "error": "Mensaje de error", "details": { ... } } ``` ## Manejo de Errores La API utiliza códigos de estado HTTP estándar: - 200: Éxito - 400: Error en la solicitud - 401: No autorizado - 404: Recurso no encontrado - 500: Error interno del servidor ## Notas - La API utiliza SOAP para comunicarse con SoftExpert - Todos los endpoints que manejan documentos soportan archivos multipart/form-data - Las respuestas de workflow incluyen el estado de la operación (FAILURE/SUCCESS)