Cómo enviar solicitudes a la Voxy Partner API

  • 1. ¿Qué es una solicitud HTTP?

 

La Voxy Partner API es una API de REST que acepta solicitudes HTTP y envía respuestas en formato JSON.

 

Para utilizar la Voxy Partner API, necesitarás poder realizar solicitudes HTTP. HTTP es un protocolo de solicitud/respuesta que permite que tu sistema envíe una solicitud a la Voxy Partner API y que la API envíe una respuesta (por ejemplo, “User successfully created” o “Here is the data you requested”).

 

Todos los lenguajes de programación estandarizados tienen bibliotecas nativas o de terceros que permiten enviar las solicitudes HTTP.

 

Si estás realizando la integración con la API, tendrás que configurar tu sitio web, tu sistema de administración de aprendizaje (LMS) o de contenidos (CMS) o cualquier otro sistema que utilices para que envíe solicitudes HTTP a la Voxy Partner API para ejecutar ciertas tareas o acceder a datos específicos. Para definir qué tareas necesitas incluir en la implementación de tu organización, contacta a tu Customer Success Manager.

 

Por ejemplo, la Voxy Partner API tiene el siguiente punto de conexión: https://app.voxy.com/partner_api/partners/segments. Si envías una solicitud HTTP GET a ese punto de conexión, recibirás un objeto de datos que contiene una lista de segmentos personalizados creados en tu organización.

 

  • 2. Tipos de solicitudes HTTP de la API

 

Cuando utilizas una API, puedes enviar diversos tipos de solicitudes HTTP según lo que quieras lograr. La Voxy Partner API admite cuatro tipo de solicitudes: GET, POST, PUT y DELETE.

 

  • GET se utiliza para recuperar datos
  • POST se utiliza para crear o insertar datos
  • PUT se utiliza para actualizar o editar datos
  • DELETE se utiliza para eliminar datos

 

Todos los lenguajes de programación estandarizados tienen bibliotecas nativas o de terceros que permiten enviar las solicitudes HTTP, y en cada uno podrás especificar qué tipo de solicitud quieres hacer.

 

Por ejemplo, la Voxy Partner API tiene el siguiente punto de conexión: https://partners/users/{external_user_id}. Si envías una solicitud HTTP GET a ese punto de conexión, recibirás información del perfil del usuario. En cambio, si envías una solicitud HTTP POST con los parámetros mínimos necesarios, podrás registrar un nuevo usuario.

 

  • 3. Ejemplo de solicitud GET

 

GET es el tipo de solicitud HTTP más usada en Internet. Cuando uno escribe una dirección URL en el navegador, en realidad está enviando una solicitud HTTP GET a un servidor que responde con una página HTML que, en consecuencia, se abre en la ventana del navegador.

 

Sin embargo, cuando se utiliza una API de REST, como la Voxy Partner API, en lugar de una página HTML, la respuesta será un objeto de datos en formato JSON.

 

Por ejemplo, la Voxy Partner API tiene el siguiente punto de conexión: https://partners/users/{external_user_id}. Si envías una solicitud HTTP GET a ese punto de conexión, la API enviará un objeto de datos en formato JSON que contiene la información del perfil de un usuario.

 

  • 4. Ejemplo de solicitud POST

 

Una solicitud POST se utiliza para insertar datos; por ejemplo, para crear un nuevo usuario o un nuevo segmento personalizado.

 

Cuando uno envía una solicitud POST, por lo general, también debe enviar un objeto de datos que contiene la información necesaria para ejecutar la solicitud, también conocida como parámetros. Algunos parámetros POST son necesarios para procesar la solicitud, mientras que otros son opcionales.

 

Por ejemplo, cuando se crea un nuevo usuario a través de la Voxy Partner API, es necesario incluir en el cuerpo de la solicitud los parámetros first_name, email, y native_language. También se pueden incluir parámetros opcionales, como expiration_date.

 

  • 5. Cómo generar el encabezado de autorización necesario

 

Para garantizar la seguridad y la privacidad, todas las solicitudes a la Voxy Partner API deben tener un encabezado de autorización HTTP válido; de lo contrario, serán rechazadas.

 

Para generar el encabezado requerido, necesitarás una clave y el secreto de la API, que puedes solicitar a tu Customer Success Manager de Voxy.

 

El formato del encabezado de autorización es "Voxy {{API_KEY}}:{{REQUEST_SIGNATURE}}", donde:

  1. {{API_KEY}} es tu API_KEY,
  2. {{REQUEST_SIGNATURE}} es el hash SHA-256 de tu API_SECRET, concatenado con los parámetros codificados de la URL ordenados alfabéticamente.

 

Uno de los errores más comunes es utilizar una REQUEST_SIGNATURE mal generada. Para generar la firma correctamente, tu código debería pasar por las siguientes etapas:

  1. Obtener todos los parámetros incluidos en la solicitud y ordenarlos alfabéticamente.
  2. Utilizar códigos URL en los parámetros ordenados alfabéticamente.
  3. Crear una cadena de texto que incluya la concatenación de tu firma API y los parámetros con codificación URL del paso 2 (por ejemplo, {{API_SECRET}}+{{URL_ENCODED_PARAMETERS}}).
  4. Encriptar la cadena utilizando el algoritmo de hash SHA-256.

 

Como puedes ver, si tu solicitud de API incluye parámetros, deberás utilizarlos para generar tu {{REQUEST_SIGNATURE}}.

 

Si no logras generar el encabezado de autorización tal como se describe anteriormente, la Voxy Partner API rechazará tu solicitud y recibirás una respuesta 401 - Unauthorized (401-No autorizado), que indica que no pudimos verificar que la solicitud provino de una fuente confiable.

 

Estos son ejemplos de códigos para generar los encabezados de autorización.

 

Para acceder a más ejemplos de códigos para generar el encabezado de autorización, visita el repositorio de ejemplos de la Partner API en Github (contacta a tu Customer Success Manager para solicitar acceso a la plataforma). El repositorio incluye ejemplos de códigos para realizar solicitudes en los siguientes lenguajes:

  • PHP
  • Ruby
  • Python
  • Java
¿Fue útil este artículo?
Usuarios a los que les pareció útil: 0 de 0
¿Tiene más preguntas? Enviar una solicitud

Comentarios

0 comentarios

Inicie sesión para dejar un comentario.