Dimo Empresa - API Documentation

Base URLs

PreProducción: http://10.5.1.30:8084/apidimoempresa/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
            }
        ]
    }
}

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

asdasdasd

EjecutarAcreditacion

Endpoint: /acreditaciones/ejecutar
Método: POST
Descripción: Ejecutar una acreditación.
Headers:
- API-KEY: BMMyeLpIomvnnGwmN8IOydFCON4AQelKTIY4C44Fljg8AjFled

Request Body:

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

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

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

asdasdasd

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.
Version de la documentación: v1.0.0.0
Realizado por: Arturo Sosa Bagnoli para Cabal Paraguay.
Contacto: asosa@cabal.com.py
Nro. Teléfono: 0971-159618
Fecha: 06 jun 2024