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:

  Code Block
  language py title json linenumbers true
  { "colaborador": { "nroDocumento": 4040440, "nombres": "Arturo", "apellidos": "Sosa Bagnoli", "nroTelefono": "0971159618", "correo": "asosa@cabal.com.py" } }

  Expand
  title 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:

  Code Block
  language py title json linenumbers true
  { "header": { "codReturn": 3, "txtReturn": "WARNING" }, "data": { "info": "El colaborador ya existe", "nroTarjeta": "", "tarjetaMask": "" } }

  Expand
  title 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:

  Code Block
  language py title json linenumbers true
  { "nroDocumento": 4040440 }

  Expand
  title 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:

  Code Block
  language py title json linenumbers true
  { "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" } ] }

  Expand
  title 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:

  Code Block
  language py title json linenumbers true
  { "acreditacion": { "usuario": "test1", "descripcion":"prueba 1", "lista": [ { "nroDocumento": 4040440, "monto": 1500000 }, { "nroDocumento": 4040440, "monto": 1200000 }, { "nroDocumento": 404011111, "monto": 1600000 } ] } }

  Expand
  title 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:

  Code Block
  language py title json linenumbers true
  { "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" } ] } }

  Expand
  title 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:

  Code Block
  language py title json linenumbers true
  { "acreditacion": { "usuario": "test1", "idAcreditacion":274 } }

  Expand
  title 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:

  Code Block
  language py title json linenumbers true
  { "header": { "codReturn": 0, "txtReturn": "SUCCESS" }, "data": { "descripcion": "Se proceso correctamente" } }

  Expand
  title 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.

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://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 -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 -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 -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
  }
}'