Especificaciones OpenAPI:

Puede encontrar toda la documentación y especificaciones bajo el estándar OpenAPI en nuestro portal de desarrolladores: https://dev.danaconnect.com

API REST – One time password OTP API

El API REST, es un servicio para generar códigos OTP, para claves multifactor de un solo uso.

El proceso de generación de claves de un solo uso tiene dos partes:

1. Generación del Código OTP – Servicio Send

Se genera y se envía el código a través de los diferentes canales de la plataforma DANAConnect. Es posible generar dos tipos de códigos: numérico y alfanuméricos.

2. Verificación del código OTP – Servicio Verify

Este es un código de un solo uso y tiene vencimiento, dependiendo del tiempo de expiración que se configure al momento de ser generado. Por defecto el usuario se podrá equivocar de código 5 veces, luego el código se inhabilita.

Se genera y se envía el código a través de los diferentes canales de la plataforma DANAConnect. Es posible generar dos tipos de códigos: numérico y alfanuméricos

URL Base:

Todos los URLs referentes a esta API tiene la siguiente base:

Protocolo: HTTP

URL:

Web Service https://api.danaconnect.com/otp/1.0/

Autenticación al API

EL API utiliza el mismo sistema de credenciales de usuarios DANAConnect.

Se utiliza el método de autenticación HTTP BASIC AUTH, el cual está basado en un login y password.

Credenciales:

Login : consiste en el nombre de usuario de DANAConnect concatenado con un @ y seguido del código de la compañía (IDCompany) en DANAConnect.
Password : es el que corresponde a ese usuario en DANAConnect


Ejemplo:

Nombre de usuario: jperez
Código de compañía: loremipsumcompany
Login para el API: jperez@loremipsumcompany

Autenticación:

El método HTTP Basic Auth es el más común para autenticarse desde clientes REST:

Consideraciones previas a utilizar el API:

La empresa que va utilizar el API debe contar con un usuario y contraseña válidos.
Por motivos de seguridad, el usuario que va a utilizar el API deber contar con un permiso especial. El administrador de su cuenta DANAConnect debe asegurarse de que este permiso esté habilitado.
Esta API funciona sobre Conversaciones que previamente se hayan creado y estén activas. Esto significa que debe tener el ID de Conversación (conversaciónID).

Número de identificación de la conversación (idConversation:) El número de identificación de la conversación en DANAConnect se puede encontrar en la página de reportes de la activación.



En la lista de contactos asociada a la conversación debe existir un campo tipo texto corto llamado que debe llamarse “OTP” y que debe estar obligatoriamente enmascarado por razones de seguridad.

Generación del Código OTP – Servicio SEND

Servicio para solicitud de generación del código de uso único. Descargar JSON de ejemplo aquí

URL:

https://api.danaconnect.com/otp/1.0/send

MÉTODO:

POST

Descripción de Parámetros de Entrada del servicio Send sendOTPJSON

Descripción de Parámetros de Salida del servicio Send resultOTPJSON

Ejemplos del servicio SEND

Descargar JSON de ejemplo aquí

Ejemplo de Request

{
"idConversation": 824541,
"values": [
{
"key": "COD1_EMAIL",
"value": "test@danaconnect.com"
},
{
"key": "COD1_NOMBRE",
"value": "Test DANAConnect"
}
],
"type": 1,
"length": 12,
"secondsExpiration": 3000,
"maximumTries": 5
}

Ejemplo de Response

{
"idRequest": 251,
"responseCode": "01",
"responseDescription": "Success",
"conversationRequestId": "87a9ab9b-5abf-4802-abfa-e7b891d2a042"
}

Verificación del código OTP – Servicio Verify

Servicio para la consulta y verificación de un código único generado previamente.

URL:

https://api.danaconnect.com/otp/1.0/verify

MÉTODO:

POST

Descripción de Parámetros de Entrada del servicio Verify – verifyOTPJSON

Descripción de Parámetros de Salida del servicio Verify – resultOTPJSON

Casos de respuesta del servicio SEND

01 – Success

Este mensaje ocurre cuando la petición es recibida con éxito para ser procesada. Sin ninguna alerta.

04 – Failed

Este mensaje ocurre cuando el servicio presenta un error interno no categorizado, no es posible replicarlo, lo cual se realiza una simulación.

05 – Maintenance Service

Este mensaje ocurre cuando el servicio está en proceso de mantenimiento el mismo es muy puntual, solo es reproducido en ambiente controlado.

06 – Error: Invalid credentials

Este mensaje ocurre cuando las credenciales son inválidas, tanto por el usuario o la clave introducida en la petición.

07 – Incorrect type, Enter 1 Number or 2 Alphanumeric

Este mensaje ocurre cuando el parámetro de entrada type no tiene el valor correcto que es 1 (para códigos OTP solo numéricos) o 2 (para códigos OTP alfanuméricos).

08 – Incorrect length, allowable range 3 to 12

Este mensaje ocurre cuando el parámetro de entrada length no tiene el valor correcto que es entre 3 a 12 (este es la longitud que requieren que se genere el código OTP).

09 – Incorrect expiration time, allowed range 1 to 3200

Este mensaje ocurre cuando el parámetro de entrada secondsExpiration no tiene el valor correcto que es entre 1 a 3200 (este es el tiempo de vigencia del código OTP generado).

10 – Incorrect IDConversation

Este mensaje ocurre cuando el id de la conversación es incorrecto.

15 – Incorrect Request

Este mensaje ocurre con cualquier petición con una excepción no categorizada.

Ejemplos del servicio de validación – Servicio Verify

Descargar JSON de ejemplo aquí

Ejemplo de Request

{

    "idRequest": 251,
    "otp": Rf24sG

}

Ejemplo de Response

{

"idRequest": 251,
"responseCode": "01",
"responseDescription": "Success",
"conversationRequestId": "87a9ab9b-5abf-4802-abfa-e7b891d2a042"

}

Casos de respuesta del servicio Verify

01 – Success

Este mensaje ocurre cuando el código es válido.

03 – Expired Code

Este mensaje ocurre cuando el código esta vencido.

04 – Incorrect code

Este mensaje ocurre cuando el código OTP proporcionado es incorrecto.

06 – Error: Invalid credentials

Este mensaje ocurre cuando las credenciales son inválidas, tanto por el usuario o la clave introducida en la petición.

14 – IdRequest has already been used

Este mensaje ocurre cuando el código ya fue usado.

16 – Maximum failed attempts allowed

Este mensaje ocurre cuando el código OTP ha sido proporcionado incorrectamente por el máximo permitido de intentos fallidos, por Default esta en 5 intentos.

Actualizado el: 14/12/2021