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:

{
    "colaborador": {
        "nroDocumento": 4040440,
        "nombres": "Arturo",
        "apellidos": "Sosa Bagnoli",
        "nroTelefono": "0971159618",
        "correo": "asosa@cabal.com.py"
    }
}

"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:

{
    "header": {
        "codReturn": 3,
        "txtReturn": "WARNING"
    },
	"data": {
        "info": "El colaborador ya existe",
        "nroTarjeta": "",
        "tarjetaMask": ""
    }
}

"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:

{
    "nroDocumento": 4040440
}

"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:

{
    "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"
        }
    ]
}

"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:

{
    "acreditacion": {
        "usuario": "test1",
        "descripcion":"prueba 1",
        "lista": [
            {
                "nroDocumento": 4040440,
                "monto": 1500000
            },
            {
                "nroDocumento": 4040440,
                "monto": 1200000
            },
            {
                "nroDocumento": 404011111,
                "monto": 1600000
            }
        ]
    }
}

"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:

{
    "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"
            }
        ]
    }
}

"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:

{
    "acreditacion": {
        "usuario": "test1",
        "idAcreditacion":274
    }
}

"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:

{
    "header": {
        "codReturn": 0,
        "txtReturn": "SUCCESS"
    },
    "data": {
        "descripcion": "Se proceso correctamente"
    }
}

"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.

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 -X POST "http://localhost:8080/ApiDimoEmpresaJavaEnvironment/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 -X POST "http://localhost:8080/ApiDimoEmpresaJavaEnvironment/rest/colaboradores/listar" \
-H "API-KEY: BMMyeLpIomvnnGwmN8IOydFCON4AQelKTIY4C44Fljg8AjFled" \
-H "Content-Type: application/json" \
-d '{
  "nroDocumento": 4040440
}'

CrearAcreditacion

curl -X POST "http://localhost:8080/ApiDimoEmpresaJavaEnvironment/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 -X POST "http://localhost:8080/ApiDimoEmpresaJavaEnvironment/rest/acreditaciones/ejecutar" \
-H "API-KEY: BMMyeLpIomvnnGwmN8IOydFCON4AQelKTIY4C44Fljg8AjFled" \
-H "Content-Type: application/json" \
-d '{
  "acreditacion": {
    "usuario": "test1",
    "idAcreditacion": 274
  }
}'

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.0.0 Autor: Arturo Sosa Bagnoli asosa@cabal.com.py - 0971-159618 06 jun 2024