Nombre de la Categoría: > APIs y Webservices

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 URL
HTTPS
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:

  1. La empresa que va utilizar el API debe contar con un usuario y contraseña válidos.
  2. 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.
  3. 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.

 

4. 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í

 

URI https://api.danaconnect.com/otp/1.0/send
METODO POST

 

Parámetros de entrada Descripción Tipo
Authorization Basic Username String
Password String
sendOTPJSON Request Json json
 

 

Parámetros Salida Descripción Tipo
resultOTPJSON Response Json json

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

Propiedad Descripción Tipo
idConversation Número de identificador único de la conversación en la plataforma DANAConnect. integer
parameters Parámetros adicionales de la conversación en la plataforma DANAConnect. StringMap
type Tipo de código OTP (ver abajo tipos de códigos). integer
length Longitud del código OTP en cantidad de caracteres integer
secondsExpiration Tiempo en segundos que dura el password antes de expirar integer
maximumTries Cantidad máxima de intentos fallidos permitidos por parte del usuario final. El default es 5 integer
key El contenido de esta clave es usado para identificar el campo de la lista de contacto relacionada a la conversación en la plataforma DANAConnect. string
value Valor que será insertado en el campo seleccionado en el key de la lista de contacto string

 


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

Propiedad Descripción Tipo
idRequest Identificador único de la solicitud de la OTP integer
responseCode Código del mensaje String
responseDescription Descripción del código del mensaje String
conversationRequestId Código de la conversación en la plataforma DANAConnect para poder realizar el tracking de la transacción. hash

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. Descargar JSON de ejemplo aquí

 

URI https://api.danaconnect.com/otp/1.0/verify
METODO POST

 

Parámetros de entrada Descripción Tipo
Authorization Basic Username String
Password String
verifyOTPJSON Request Json json
 

 

Parámetros Salida Descripción Tipo
resultOTPJSON Response Json json

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

 

Propiedad Descripción Tipo
idRequest Identificador único de la solicitud de la OTP que fue entregado en la solicitud de generación de la OTP integer
otp Código OTP para entregar al usuario. String

 


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

 

Propiedad Descripción Tipo
idRequest Identificador único de la solicitud de la OTP integer
responseCode Código del mensaje String
responseDescription Descripción del código del mensaje String

 

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.

 


Ver Tambien:
« | »