# Documentación API Interoperabilidad MITUR

## Descripción
Esta API permite la interacción con los servicios del MITUR. Los usuarios pueden crear solicitudes, subir documentos, agregar registros del grid, pagos, descarga de documentos, etc...

**Ultima actualizacion:** ==11/08/2024==
**Desarrollador:** ==Jossias Velazquez - [e-mail]==

## URL Base

https://Tu-servidor-xroad/r1/DO/GOB/[INSTITUCION]/[SUBSISTEMA]/SOFTEXPERT/api

## Headers

| Key | Value | Obligatorio | Descripción |
|----------------|--------|-------------|--------------------------------------|
|`x-road-client` | string | Si | Ejemplo: DO/GOB/MITUR/UCTT-TEST |
|`Athorization` | string | No | Ejemplo: Basic base64(email:password)|

## Autenticación
Esta API utiliza método de autenticación Basic, se le proveerá de un usuario y contraseña que deberá proveer vía heders en el siguiente formato:

**`Authorization: 'Basic ' + base64('email:password')`**

Todos los endpoints requieren de el usuario y password en formato base64 en los encabezados.

---

## Endpoints

### 1. Datos del servicio

#### GET /v2/services/{id}
Obtiene los datos del servicio, precios, formulario, pasos y toda la información necesaria para requerir el servicio desde una fuente externa
- **URL**: `/v2/services/{id}`
- **Método HTTP**: `GET`
- **Headers**:
- `x-road-client: DO/GOB/INSTITUCION/SUBSISTEMA`
- `Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=`

##### Ejemplo de Solicitud

GET /v2/services/11 HTTP/1.1
Host: tu-servidor-xroad
x-road-client: DO/GOB/INSTITUCION/SUBSISTEMA
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

##### Respuesta Exitosa
- **Código HTTP**: `200 OK`
- **Cuerpo**:

  {
    "success": true,
    "data": {
        "id": 11,
        "process_id": "DPP01EXT",
        "code_serv": "mitur-no-objecion-a-uso-de-suelo-1011",
        "name": "No Objeción a Uso de Suelo",
        "provider": "softexpert",
    }
  }

### 2. Workflows

#### POST /v2/workflows/create
Crea una instancia del workflow especificado

- **URL**: `/v2/workflows/create`
- **Método HTTP**: `POST`
- **Headers**:
- `x-road-client: DO/GOB/INSTITUCION/SUBSISTEMA`
- `Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=`

##### Cuerpo de la Solicitud
| Campo | Tipo | Obligatorio | Valor fijo | Descripción |
| -------------------------- | ------ | ----------- | ---------- | --------------------------------------------------------------------------------- |
| `workflow.processId` | string | Sí | Sí | ID del proceso que se desea instanciar |
| `workflow.workflowTitle` | string | Sí | No | Titulo con el que desea identificar la solicitud |
| `workflow.activityId` | string | Sí | Sí | ID de la actividad donde se adjuntarán los documentos |
| `workflow.source` | string | Sí | Sí | Origen desde donde se envía, uno de estos valores [PRO, VUC, UCTT] |
| `workflow.entityAttribute` | array | No | No | Arraglo de objetos del con datos del formulario |
| `payment.amount` | number | Si | No | Monto pagado |
| `payment.approvalNumber` | string | Si | No | Numero de aprobación de la transacción si fue pagado por SIRITE |
| `payment.documentReceipt` | object | No | No | Objeto que contiene los datos del archivo de comprobante de pago. |
| `payment.folder` | string | Si | Si | Categoria de asociacion de documento [DPPDE, CONFOTURDE, LICENCIASDE, MERCADEODE] |
| `payment.date` | string | No | No | Fecha en la que se aplicó el pago (SIRITE) |
| `payment.paymentMethod` | string | Si | No | Metodo de pago utilizado "DEPOSITO/SIRITE" |
| `children` | array | No | No | Array de objetos para registros de grid |
| `documents` | array | No | No | Array de objetos con datos de los documentos |

##### Objetos
###### document
###### child
|Campo | Tipo | Obligatorio | Valor fijo |Descripción |
|---------|---------|----------------|---------------|---------------|

###### documentReceipt

##### Ejemplo de Solicitud

POST /api/v2/workflows/create HTTP/1.1
Host: tu-servidor-xroad
x-road-client: DO/GOB/INSTITUCION/SUBSISTEMA
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Content-Type: application/json

{
    "workflow": {
        "processId": "DPP01EXT",
        "workflowTitle": "Solicitud desde Prodominicana",
        "entityId": "mitur01",
        "source": "PRO",
        "activityId": "MITUR001",
        "entityAttribute": [
            {
                "entityAttributeId": "numsolvuc",
                "entityAttributeValue": "PROD-02"
            }
        ]
    },
    "payment": {
        "amount": 20000,
        "approvalNumber": "",
        "documentReceipt": {
            "data": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAgAAAAIAQMAAAD+wSzIAAAABlBMVEX///+/v7+jQ3Y5AAAADklEQVQI12P4AIX8EAgALgAD/aNpbtEAAAAASUVORK5CYII",
            "filename": "comprobante-de-pago-mitur-2023-12-21-042549.png"
        },
        "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 1"
        }
    ]
}

##### Respuesta Exitosa
- **Código HTTP**: `200 OK`
- **Cuerpo**:

    {
        "valid": true,
        "data": {
            "status": "SUCCESS",
            "code": 1,
            "detail": "Workflow iniciado con éxito",
            "recordKey": "2784",
            "recordId": "DPP01-PRO-0060"
        }
    }

##### Errores Comunes
| Código HTTP | Código de Error | Mensaje |
|-------------|-----------------|-------------------------------|
| 401 | `UNAUTHORIZED` | Token no válido o expirado |
| 403 | `FORBIDDEN` | No tienes permisos suficientes|
| 500 | `INTERNAL SERVER ERROR` | Error en la ejecución de la webservice|

#### PUT /v2/workflows/actions/resolve
Responde una acción requerida a un workflow en específico

- **URL**: `/v2/workflows/actions/resolve`
- **Método HTTP**: `PUT`
- **Headers**:
- `x-road-client: DO/GOB/INSTITUCION/SUBSISTEMA`
- `Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=`
##### Cuerpo de la Solicitud
| Campo | Tipo | Obligatorio | Descripción |
|-------------|--------|-------------|---------------------------------------------|
| `workflowID`| string | Sí | ID del workflow |
| `activityId`| string | Sí | Actividad donde se encuentra la solicitud |
| `documents` | array | Sí | Arreglo de documentos a subir |

##### Ejemplo de Solicitud

PUT /v2/workflows/actions/resolve HTTP/1.1
Host: tu-servidor-xroad
x-road-client: DO/GOB/INSTITUCION/SUBSISTEMA
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Content-Type: application/json

{
    "workflowId" : "DPP01-PRO-0060",
    "activityId" : "MITUR02312",
    "documents": [
         {
            "attributes": [
               {
                "AttributeId": "NumeroSolicitud",
                "AttributeValue" : "DPP01-PRO-0060"
                }
            ],
            "categoryId": "DPPDE",
            "data": "https://www.antennahouse.com/hubfs/xsl-fo-sample/pdf/basic-link-1.pdf",
            "filename": "Registro Mercantil.pdf",
            "title": "Registro Mercantil 2"
        }
    ]
}

---
### 2. Documentos
#### GET /v1/documents/{id}/download
Obtiene el documento en formato bas64

- **URL**: `/v1/documents/{id}/download`
- **Método HTTP**: `GET`
- **Headers**:
- `x-road-client: DO/GOB/INSTITUCION/SUBSISTEMA`
- `Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=`

##### Parámetros de consulta
| Parámetro | Tipo | Obligatorio | Descripción |
|-----------------|--------|-------------|------------------------------------------------------------------------------------------|
| `asLink` | int | No | Enviar valor `1` si se requiere el documento en una url en vez del base64 |

##### Ejemplo de Solicitud

GET /v1/documents/DPPPLANOSDEFINITIVOS000016/download HTTP/1.1
Host: tu-servidor-xroad
x-road-client: DO/GOB/INSTITUCION/SUBSISTEMA
Authorization: Basic <token>

##### Respuesta Exitosa
- **Código HTTP**: `200 OK`
- **Cuerpo**:

  {
   "valid": true,
   "data": [
        {
            "filename": "RESOLUCION OCEAN BLUE & SANDS.pdf",
            "data": "https://dev.softexpert.mitur.gob.do/se/v34014/temp/2a4a426d-577b-4ed4-b5f7-c9f27263cc49843507717620365617.pdf"
        }
    ]
  }

##### Errores Comunes
| Código HTTP | Código de Error | Mensaje |
|-------------|-----------------|-------------------------------|
| 401 | `UNAUTHORIZED` | Datos de usuarios inválidos |
| 403 | `FORBIDDEN` | No tienes permisos suficientes|
| 404 | `NOT FOUND` | Documento no encontrado

## Notas adicionales
- Asegurate de usar la versión correcta (en la url) al consumir un endpoint.
- Esta documentación está en desarrollo y puede ser actualizada en cualquier momento.
- Para solicitar un usuario de pruebas contactar al desarrollador.