Documentacion API-REST
Documentación API-REST
Autenticación
La autenticación es el proceso fundamental en el envío de mensajes a través de la aplicación Reach, y para poder realizarlo de forma exitosa se requiere un API Key (o Llave) la cual será entregada por Reach. Por lo delicada y sensitiva que es la información que maneja, La llave debe ser protegida del público y guardada de forma muy segura y confidencial.
La llave será provista únicamente por el departamento de Reach. Si aún no se posee, debe contactarse con el ejecutivo de cuenta corporativo o al centro de Soporte Reach.
Se recomienda que únicamente el personal autorizado por la empresa contratante del servicio para realizar la conexión, tenga acceso a la llave y en caso de necesitar soporte o asistencia en el proceso de conexión, podrá ser requerido al personal de Reach quien proveerá la asistencia técnica necesaria.
Proceso General:
El proceso de autenticación se divide en 3 simples pasos, que se detallan a continuación:
- Generar la Firma Electrónica
- Construir el Encabezado HTTP
- Realizar la Llamada
- URL
1. Generar la Firma Electrónica
La firma electrónica (o firma) será requerida siempre para poder determinar la autenticidad de las llamadas al API. Esta firma se encuentra basada en 2 componentes que son: la información solicitada y la llave publica del API KEY.
Para poder generar la firma de forma correcta se deben seguir los siguientes pasos:
Como primer paso se deben ordenar los parámetros solicitados en forma alfabética
- Luego se deben concatenar todos los parámetros con el formato <LLAVE>=<VALOR>. Si se utilizan los métodos POST o PUT con algún tipo de contenido, este se deberá agregar al momento de enviar la petición.
- Posteriormente se debe agregar la cadena de caracteres generado con el API Key de Reach, junto a la fecha de envío, de tal forma que la cadena de caracteres posea el siguiente formato <APIKEY><FECHA><PARAMETROS>. La fecha utilizada es la incluida en los encabezados HTTP.
- Luego se debe generar el código de autentificación de mensajes en clave-hash (HMAC-SHA1), utilizando para el efecto la cadena de caracteres construida y el API SECRET.
- Finalmente se debe codificar el hash resultante en una cadena de caracteres con formato de base64.
Como resultado se obtendrá una solicitud de firma con el siguiente formato, sin importar el lenguaje de programación que se desee utilizar:
BASE64 (HMA-SHA1 (<APIKEY> <FECHA> <LLAVE1 = VALOR1 LLAVE2 = VALOR2 LLAVE3=VALOR3> <POSTdata>))
2. Construir el Encabezado HTTP
El siguiente paso, consiste en construir el encabezado HTTP. Para poder realizar la llamada de autenticación de forma exitosa, se deben incluir, la fecha de envío y el mensaje dentro del encabezado HTTP de la petición.
Se debe tener en cuenta que, el parámetro de nombre del encabezado de la firma siempre debe de llamarse “Authorization” y el valor debe ser una cadena de caracteres con el siguiente formato:
IM <APIKEY>:<HASH>
Además el nombre del encabezado de la fecha siempre será DATE y el valor será la fecha de envío, Es importante tener en cuenta que se debe utilizar el formato especial de fecha “RFC 1123”. A continuación se muestra un ejemplo de este formato: Mon, 11 Jun 2014 7:33:23 GMT.
El encabezado resultante deberá de verse como el siguiente ejemplo:
Date: Mon, 11 Jun 2014 17:33:23 GMT.
Authorization: IM <APIKEY>:<signature>
3. Realizar la Llamada
El último paso del proceso de autenticación es realizar la llamada (Request) utilizando para el efecto, el encabezado HTTP que se ha generado anteriormente, incluyendo los parámetros correspondientes para construir la firma.
Diagrama del API:
Diagrama de Api cuando hay Error y está configurado la URL:
4. URL
- Para el consumo API-REST, la URL puede ser encontrada en la sección: Mi cuenta -> Configuración del API