Hola, Humans. ¿En qué podemos ayudarte?

08. La API de la Base de contactos en Zenvia Customer Cloud
8 min
Creado por Larissa Aniceto en 28/02/2024 15:56
Actualizado por Larissa Aniceto en 08/03/2024 15:42

Zenvia Customer Cloud también permite el uso de la Base de contactos a través de su API. En este documento veremos el concepto básico y mostraremos las funcionalidades proporcionadas por la API de la base de contactos de Zenvia Customer Cloud.

¿Qué es una API y cómo usarla?

La sigla API significa Interfaz de Programación de Aplicaciones. En resumen, es un tipo de aplicación que proporciona un medio mediante el cual dos sistemas se conectan e interactúan intercambiando datos específicos. 

La API actúa enviando recursos proporcionados por el usuario a un servidor o sistema específico, y después de esta etapa, el extremo externo de esta comunicación responde con los datos necesarios para ofrecer un determinado servicio al usuario.


Ejemplo: A través de la comunicación de la API de Zenvia Customer Cloud con los servidores de Zenvia, un usuario puede crear o agregar destinatarios a una lista de contactos.


Por estas razones, cuando hablamos de API, tendemos a mencionar los puntos finales, que representan uno de los extremos de la comunicación entre la interfaz y el servidor externo. 


Gracias a esta característica, las APIs tienen el beneficio de ahorrar recursos al usuario, ya que no se ejecutan localmente en la máquina del usuario y solo utilizan la respuesta del servidor para proporcionar la información necesaria.


En resumen, una API es simplemente una aplicación que intercambia información entre un sistema externo y un usuario.

Beneficios de una API

A continuación, veamos algunos de los beneficios de una API:


Integración sencilla

Como la API no se ejecuta localmente en la máquina del usuario, los recursos necesarios para su funcionamiento también son menores, lo que permite un proceso de integración más sencillo y ágil.


Implementación rápida

La implementación ágil y la fácil personalización colaboran significativamente en simplificar también el proceso de desarrollo y permitir que se logren resultados prácticos en menos tiempo.


Datos encapsulados

Como la API solo proporciona un extremo de la comunicación para el usuario y funciona enviando y recibiendo una representación de los recursos necesarios para su funcionamiento, toda esta comunicación se encapsula, lo que mejora la seguridad y la confidencialidad de los datos.

API para la Base de contactos de Zenvia Customer Cloud

API ofrece las mismas funcionalidades que el panel de la base de contactos de Zenvia Customer Cloud, lo que permite agrupar sus contactos en una lista para utilizarlos como público objetivo para sus campañas.


⚠️ Atención: Esta funcionalidad está disponible solo para usuarios con el perfil de Administrador.


A continuación, detallaremos cómo utilizar la documentación de la API de ZenAPI para integrar la API de la base de contactos.


💡 Tip: Para obtener más información sobre la base de contactos, consulte el artículo Base de contactos en Zenvia Customer Cloud.


Cómo funciona ZenAPI

Primero, acceda a la documentación de ZenAPI y localice Contactos en el menú izquierdo; todas las documentaciones que están debajo de esta categoría se refieren a la API de la base de contactos de Zenvia Customer Cloud.


El siguiente paso para usar la API es autenticarse.

Cómo funciona la autenticación de la API

Para utilizar la API, será necesario pasar un token de autorización, que son:

  1. Token JWT utilizado por el servicio Front-End de Zenvia;

  2. X-API-Token pasado como parámetro del encabezado.


Entre estos dos, recomendamos especialmente X-API-Token por sus beneficios de seguridad, ya que en caso de ser necesario, puede revocar el acceso fácilmente a través del panel de Tokens y Webhooks en el menú Desarrolladores de la Plataforma Zenvia. 


Además, para crear un nuevo Token, simplemente haga clic en Crear nuevo.

Tenga en cuenta que, para realizar cualquiera de las acciones disponibles, es necesario enviar el token en el encabezado HTTP 'X-API-TOKEN'.


Ejemplo: X-API-TOKEN: hKp94crjv9OF3UGrCpSXUJw1-UYHhRvLKNLt

A continuación, hablaremos sobre los métodos y cómo hacer una solicitud en el cuerpo.

Cómo hacer una solicitud

Para crear un nuevo contacto, el desarrollador deberá usar el método de acción en la URL. En nuestro caso, sería el método POST.

Por lo tanto, necesitará hacer el método POST en la URL https://api.zenvia.com/v2/contacts y pasar en el cuerpo de la solicitud el payload siguiente:


{

  "canales": {

perl

Copy code

"correo electrónico": "[email protected]",

"móvil": "5510888883333",

"fijo": "551044443333"

  },

  "nombre": "Rafael",

  "apellido": "Souza",

  "datosPersonalizados": {

json

Copy code

"propiedad1": "2022-06-13",

"propiedad2": "2022-06-13"

  },

  "direcciones": [

Copy code

{

   "país": "Brasil",

   "código postal": "01310-300",

   "estado": "SP",

   "ciudad": "São Paulo",

   "dirección": "Av. Paulista",

   "número de calle": "2300",

   "barrio": "Bela Vista"

Copy code

}

  ],

  "listIds": [

arduino

Copy code

"list-id-01",

"list-id-02",

"list-id-03"

  ]

}


Para obtener más información sobre cada componente del Payload, consulte la descripción ubicada en Request body schema.


En esta sección, se enumera qué es cada campo, cómo deben pasarse y cómo debe pasarse el payload en esta estructura.


Ahora que ya sabe cómo trabajar con la API y cómo navegar por la documentación, a continuación se muestra una lista de todas las funcionalidades disponibles en la base de contactos y el enlace a la documentación que brinda más detalles al respecto.


Qué se puede hacer con la API

Usando la API de la base de contactos de Zenvia Customer Cloud, puede:

  • Crear contactos;

  • Listar todos los contactos disponibles;

  • Recuperar la información de un contacto;

  • Actualizar la información de un contacto;

  • Eliminar un contacto;

  • Crear listas de contactos;

  • Listar todas las listas de contactos disponibles;

  • Recuperar la información de una lista de contactos;

  • Actualizar la información de una lista de contactos;

  • Eliminar una lista de contactos (Solo se elimina la lista, no los contactos);

  • Listar los contactos de una lista de contactos;

  • Crear campos de datos personalizados para utilizar en la API de contactos;

  • Listar todos los campos de datos personalizados de contacto disponibles.

¡Listo! Ahora que conoces la API de la base de contactos de Zenvia Customer Cloud, consulta más información sobre la base de contactos.

¿Este artículo ha resuelto sus dudas?
Vistos recientemente