Dimo Empresa - API Documentation

Base URLs

PreProducción: http://10.5.1.31:8103/rest

Authentication

API Key: Todos los endPoints necesitan un ApiKey en el header.
- Header: API-KEY
- Valor de ejemplo: BMMyeLpIomvnnGwmN8IOydFCON4AQelKTIY4C44Fljg8AjFled
- Descripción: Aparte de seguridad por esta clave se identifica a la Empresa.

Endpoints

AltaColaborador

Endpoint: /colaboradores/alta
Método: POST
Descripción: Crea un nuevo colaborador para la empresa
Headers:
- API-KEY: BMMyeLpIomvnnGwmN8IOydFCON4AQelKTIY4C44Fljg8AjFled
Request Body:
json
```
{
    "colaborador": {
        "nroDocumento": 4040440,
        "nombres": "Arturo",
        "apellidos": "Sosa Bagnoli",
        "nroTelefono": "0971159618",
        "correo": "asosa@cabal.com.py"
    }
}
```
Consideraciones del Request
"nroDocumento" => Debe ser numérico, contener el número de documento de la persona a quien se le va a asociar como colaborador de la empresa.
"nroTelefono" => Debe tener ese formato, no debe contener caracteres especiales ni espacios.
"correo" => Debe ser un correo valido.
Response:
json
```
{
    "header": {
        "codReturn": 3,
        "txtReturn": "WARNING"
    },
	"data": {
        "info": "El colaborador ya existe",
        "nroTarjeta": "",
        "tarjetaMask": ""
    }
}
```
Respuestas posibles
"codReturn": 0, "txtReturn": "SUCCESS", "info": "Registrado como colaborador, ya tiene cuenta Dimo" => Se agregó correctamente al colaborador y ese colaborador ya tiene una cuenta Dimo, por lo que se le creo la tarjeta prepaga asociada a la empresa.
"codReturn": 0, "txtReturn": "SUCCESS", "info": "Registrado como colaborador, aun no tiene cuenta DIMO" => Se agregó correctamente al colaborador y ese colaborador aún no tiene una cuenta dimo. Por lo tanto no se le creó la tarjeta prepaga de la empresa.
"codReturn": 1, "txtReturn": "ERROR", "info": "Hubo un problema al procesar la solicitud" => Hubo un problema interno por el cual no se pudo procesar la solicitud. Se notifico al equipo de Sistemas para su revisión.
"codReturn": 2, "txtReturn": "WARNING", "info": "Valores del request no validos" => No corresponde los valores del request. (telefono o correo).
"codReturn": 3, "txtReturn": "WARNING", "info": "El colaborador ya existe" => El colaborador ya se encuentra vinculado a la empresa y ya tiene su tarjeta prepaga creada.
"codReturn": 4, "txtReturn": "ERROR", "info": "Hubo un problema en el registro del colaborador" => Hubo un problema al crear al usuario, sistemas ya fue notificado.

ListarColaborador

Endpoint: /colaboradores/listar
Método: POST
Descripción: Lista uno o todos los colaboradores de la empresa, con información adicional de cada uno.
Headers:
- API-KEY: BMMyeLpIomvnnGwmN8IOydFCON4AQelKTIY4C44Fljg8AjFled
Request Body:
json
```
{
    "nroDocumento": 4040440
}
```
Consideraciones del Request
"nroDocumento" => Debe ser numérico, contener el número de documento de la persona a quien se le va a asociar como colaborador de la empresa.
"nroDocumento" => Debe tener el valor 0 para que el endpoint devuelva todos los colabores de la empresa.

Response Body:

json

{
    "header": {
        "codReturn": 0,
        "txtReturn": "SUCCESS"
    },
    "data": [
        {
            "apellidos": "Sosa",
            "correo": "asosa@cabal.com.py",
            "documento": "4040440",
            "estado": "Usuario registrado",
            "nombres": "Arturo",
            "nroTarjeta": "6043512000595678",
            "nroTelefono": "0986215487",
            "tarjetaMask": "6043-XXXX-XXXX-5678"
        }
    ]
}

Respuestas posibles

"codReturn": 0, "txtReturn": "SUCCESS" => Cuando encuentra los datos. (El data puede ser de un colaborador o de todos los colabores de la empresa).
"codReturn": 1, "txtReturn": "ERROR" => Cuando el endpoint tuvo un problema al procesar la petición.
"codReturn": 2, "txtReturn": "No existe el colaborador" => Cuando no hay un colaborador registrado con el documento enviando en el request.

CrearAcreditacion

Endpoint: /acreditaciones/crear
Método: POST
Descripción: Crea una nueva orden de acreditación.
Headers:
- API-KEY: BMMyeLpIomvnnGwmN8IOydFCON4AQelKTIY4C44Fljg8AjFled
Request Body:
json
```
{
    "acreditacion": {
        "usuario": "test1",
        "descripcion":"prueba 1",
        "lista": [
            {
                "nroDocumento": 4040440,
                "monto": 1500000
            },
            {
                "nroDocumento": 4040440,
                "monto": 1200000
            },
            {
                "nroDocumento": 404011111,
                "monto": 1600000
            }
        ]
    }
}
```
Consideraciones del Request
"usuario" => Puede enviar el nombre del usuario que creo la acreditación para asociar esa información a la petición.
"descripcion" => Puede enviar alguna descripción para asociar a la petición. Ej.: 'Acreditación de Salario mes de Junio'.
"nroDocumento" => Debe ser numérico, contener el número de documento de la persona a quien se le va a asociar como colaborador de la empresa.
"monto" => Debe contener el valor a ser acreditado al colaborador sin separación de puntos ni decimales.

Response Body:

json

{
    "header": {
        "codReturn": 1,
        "txtReturn": "WARNING"
    },
    "data": {
        "estadoAcreditacion": "APROBADO",
        "idAcreditacion": "274",
        "acreditacionesValidas": [
            {
                "estado": "Usuario registrado",
                "monto": "1500000",
                "nroDocumento": "4040440"
            },
            {
                "estado": "Usuario registrado",
                "monto": "1200000",
                "nroDocumento": "4040440"
            }
        ],
        "acreditacionesNoValidas": [
            {
                "estado": "No esta registrado como colaborador",
                "monto": "1600000",
                "nroDocumento": "404011111"
            }
        ]
    }
}

Respuestas posibles

"codReturn": 0, "txtReturn": "SUCCESS", "estadoAcreditacion": "APROBADO" => Todos los colaboradores del Request pueden recibir su acreditación sin problemas.
"codReturn": 1, "txtReturn": "ERROR", "estadoAcreditacion": "Hubo un problema al procesar la peticion" => El endpoint tuvo un problema procesando la petición. Sistemas ya fue notificado.
"codReturn": 2, "txtReturn": "WARNING", "estadoAcreditacion": "APROBADO" => Hay usuarios que no pertenecen a la lista de colabores de la empresa, pero si se procesa la orden para el resto.
"codReturn": 3, "txtReturn": "ERROR", "estadoAcreditacion": "No existe ningun colaborador valido" => Todos los colabores del request, no pertenecen a la empresa.

EjecutarAcreditacion

Endpoint: /acreditaciones/ejecutar
Método: POST
Descripción: Ejecutar una acreditación.
Headers:
- API-KEY: BMMyeLpIomvnnGwmN8IOydFCON4AQelKTIY4C44Fljg8AjFled
Request Body:
json
```
{
    "acreditacion": {
        "usuario": "test1",
        "idAcreditacion":274
    }
}
```
Consideraciones del Request
"usuario" => Puede enviar el nombre del usuario que creo la acreditación para asociar esa información a la petición.
"idAcreditacion" => Debe enviar el ID de la orden de acreditación devuelta por el endpoint anterior.
Response Body:
json
```
{
    "header": {
        "codReturn": 0,
        "txtReturn": "SUCCESS"
    },
    "data": {
        "descripcion": "Se proceso correctamente"
    }
}
```
Respuestas posibles
"codReturn": 0, "txtReturn": "SUCCESS", "descripcion": "Se proceso correctamente" => Todos los colaboradores del Request pueden recibir su acreditación sin problemas.
"codReturn": 1, "txtReturn": "ERROR", "descripcion": "Hubo un problema al ejecutar la acreditacion" => El endpoint tuvo un problema procesando la petición. Sistemas ya fue notificado.
"codReturn": 2, "txtReturn": "ERROR", "descripcion": "No existe la orden de acreditacio" => Hay usuarios que no pertenecen a la lista de colabores de la empresa, pero si se procesa la orden para el resto.
"codReturn": 3, "txtReturn": "WARNING", "descripcion": "Esta orden de acreditacion ya fue ejecutada" => Todos los colabores del request, no pertenecen a la empresa.
"codReturn": 4, "txtReturn": "ERROR", "descripcion": "DINAMICO" => Se devuelve una descripción distinta dependiendo de la validación que rechazo la petición.

HistoricoAcreditaciones

Endpoint: /acreditaciones/historico
Método: POST
Descripción: Devuelve los datos del histórico.
Headers:
- API-KEY: BMMyeLpIomvnnGwmN8IOydFCON4AQelKTIY4C44Fljg8AjFled
Request Body:
json
```
{
    "filtros": {
        "fechaInicio": "01/09/2024",
        "fechaFinal": "11/09/2024",
        "estado": "APROBADO"
    }
}
```
Consideraciones del Request
"fechaInicio" => Debe tener el formato de "dd/mm/yyyy"
"fechaFinal" => Debe tener el formato de "dd/mm/yyyy"
"estado" => Valores posibles: APROBADO, APROBADO-EJECUTADO y PENDIENTE.

Se puede enviar uno o todos los campos vacios => "" Esto devolverá todos los registros.

Response Body:

json

{
    "header": {
        "codReturn": 0,
        "txtReturn": "SUCCESS"
    },
    "data": [
        {
            "descripcion": "Orden para Joel",
            "estado": "APROBADO",
            "fechaAprob": "03/09/2024 09:30:22",
            "fechaEjec": "03/09/24 09:30",
            "fechaInsert": "03/09/2024 09:30:22",
            "glosa": "ACREDITACION DE SALARIOS",
            "idAcreditacion": "570",
            "montoTotal": "1000000",
            "usuarioAprob": "test1",
            "usuarioEjec": "test1",
            "usuarioInsert": "test1"
        },
        {
            "descripcion": "Orden Nro. 5500",
            "estado": "APROBADO",
            "fechaAprob": "02/09/2024 10:53:40",
            "fechaEjec": "02/09/24 10:53",
            "fechaInsert": "02/09/2024 10:53:40",
            "glosa": "ACREDITACION DE SALARIOS",
            "idAcreditacion": "568",
            "montoTotal": "1000000",
            "usuarioAprob": "test1",
            "usuarioEjec": "test1",
            "usuarioInsert": "test1"
        },
        {
            "descripcion": "Joel acreditación",
            "estado": "APROBADO",
            "fechaAprob": "02/09/2024 10:52:23",
            "fechaEjec": "02/09/24 10:52",
            "fechaInsert": "02/09/2024 10:52:23",
            "glosa": "ACREDITACION DE SALARIOS",
            "idAcreditacion": "567",
            "montoTotal": "1000000",
            "usuarioAprob": "test1",
            "usuarioEjec": "test1",
            "usuarioInsert": "test1"
        },
        {
            "descripcion": "Acreditación Joel",
            "estado": "APROBADO",
            "fechaAprob": "02/09/2024 10:51:10",
            "fechaEjec": "02/09/24 10:51",
            "fechaInsert": "02/09/2024 10:51:10",
            "glosa": "ACREDITACION DE SALARIOS",
            "idAcreditacion": "566",
            "montoTotal": "1000000",
            "usuarioAprob": "test1",
            "usuarioEjec": "test1",
            "usuarioInsert": "test1"
        }
    ]
}

DisponibleCuentaEmpresa

Endpoint: /acreditaciones/disponible
Método: POST
Descripción: Devuelve los datos de la cuenta.
Headers:
- API-KEY: BMMyeLpIomvnnGwmN8IOydFCON4AQelKTIY4C44Fljg8AjFled
Request Body: (SIN REQUEST, SOLO POST)

Response Body:

json

{
    "data": {
        "disponible": "45075000",
        "estado": "Operativa",
        "nroCuenta": "",
        "nroTarjeta": "2C382210F8FE550D",
        "nroTarjetaCripto": "6043-XXXX-XXXX-6775"
    },
    "header": {
        "codReturn": 0,
        "txtReturn": "SUCCESS"
    }
}

Manejo de errores

Common HTTP Status Codes:
- 200 OK: The request was successful.
- 400 Bad Request: The request could not be understood or was missing required parameters.
- 401 Unauthorized: Authentication failed or user does not have permissions for the desired action.
- 404 Not Found: The requested resource could not be found.
- 500 Internal Server Error: An error occurred on the server.

Ejemplos de uso

Ejemplos de como consumir por curl:

AltaColaborador

curl

curl -X POST "http://10.5.1.31:8103/rest/colaboradores/alta" \
-H "API-KEY: BMMyeLpIomvnnGwmN8IOydFCON4AQelKTIY4C44Fljg8AjFled" \
-H "Content-Type: application/json" \
-d '{
  "data": {
    "nroDocumento": 4040440,
    "nombres": "Arturo",
    "apellidos": "Sosa Bagnoli",
    "nroTelefono": "0971159618",
    "correo": "asosa@cabal.com.py"
  }
}'

ListarColaborador

curl

curl -X POST "http://10.5.1.31:8103/rest/colaboradores/listar" \
-H "API-KEY: BMMyeLpIomvnnGwmN8IOydFCON4AQelKTIY4C44Fljg8AjFled" \
-H "Content-Type: application/json" \
-d '{
  "nroDocumento": 4040440
}'

CrearAcreditacion

curl

curl -X POST "http://10.5.1.31:8103/rest/acreditaciones/crear" \
-H "API-KEY: BMMyeLpIomvnnGwmN8IOydFCON4AQelKTIY4C44Fljg8AjFled" \
-H "Content-Type: application/json" \
-d '{
  "acreditacion": {
    "usuario": "test1",
    "descripcion": "prueba 1",
    "lista": [
      {
        "nroDocumento": 4040440,
        "monto": 1500000
      },
      {
        "nroDocumento": 4040440,
        "monto": 1200000
      },
      {
        "nroDocumento": 404011111,
        "monto": 1600000
      }
    ]
  }
}'

EjecutarAcreditacion

curl

curl -X POST "http://10.5.1.31:8103/rest/acreditaciones/ejecutar" \
-H "API-KEY: BMMyeLpIomvnnGwmN8IOydFCON4AQelKTIY4C44Fljg8AjFled" \
-H "Content-Type: application/json" \
-d '{
  "acreditacion": {
    "usuario": "test1",
    "idAcreditacion": 274
  }
}'

HistoricoAcreditacion

curl

curl -X POST "http://10.5.1.31:8103/rest/acreditaciones/historico" \
-H "API-KEY: BMMyeLpIomvnnGwmN8IOydFCON4AQelKTIY4C44Fljg8AjFled" \
-H "Content-Type: application/json" \
-d '{
    "filtros": {
        "fechaInicio": "01/09/2024",
        "fechaFinal": "11/09/2024",
        "estado": "APROBADO"
    }
}'

ConsultarDisponible

curl

curl -X POST "http://10.5.1.31:8103/rest/acreditaciones/disponible" \
-H "API-KEY: BMMyeLpIomvnnGwmN8IOydFCON4AQelKTIY4C44Fljg8AjFled" \
-H "Content-Type: application/json" \
-d ''

Este documento proporciona una guía completa para la integración y uso de la API de Dimo Empresa. Asegúrate de seguir las mejores prácticas de seguridad y yo me comprometo a mantener actualizada la documentación para reflejar cualquier cambio en la API.	Cabal Paraguay Ltda. Caballero 728, Asunción Paraguay.	Versión de la doc: v1.0.1.0 Autor: Arturo Sosa Bagnoli asosa@cabal.com.py - 0971-159618 06 jun 2024

Page tree

ADE - Implementación

Dimo Empresa - API Documentation

Base URLs

Authentication

Endpoints

AltaColaborador

ListarColaborador

CrearAcreditacion

EjecutarAcreditacion

HistoricoAcreditaciones

DisponibleCuentaEmpresa

Manejo de errores

Ejemplos de uso

AltaColaborador

ListarColaborador

CrearAcreditacion

EjecutarAcreditacion

HistoricoAcreditacion

ConsultarDisponible