Zenvia Attraction también te permite usar el gestor de contactos a través de su API. En este documento veremos el concepto básico y te mostraremos las funcionalidades que ofrece la API de gestión de contactos de Zenvia Attraction.
Qué es una API y cómo usarla
La sigla API significa Application Programming Interface. En resumen, se trata de un tipo de aplicación que brinda un medio a través del cual dos sistemas se conectan e interactúan intercambiando datos específicos. La API actúa enviando recursos pasados por el usuario a un determinado servidor o sistema, y después de esta etapa, la punta externa de esa comunicación responde con los datos necesarios para ofrecer determinado servicio al usuario.
Ejemplo: A través de la comunicación de la API de Zenvia Attraction con los servidores Zenvia, un usuario puede crear o colocar destinatarios en una lista de contactos.
Por estos factores, cuando hablamos de API tendemos a citar endpoints, que representan una de las puntas de comunicación entre la interfaz y el servidor externo. Gracias a esa característica, APIs tienen el beneficio de ahorrar recursos del usuario, ya que no se ejecutan localmente en la máquina del usuario y solo utilizan la respuesta del servidor para proveer las informaciones necesarias.
En suma, una API es simplemente una aplicación que intercambia informaciones entre un sistema externo y un usuario.
Beneficios de una API
Estos son 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 también permite un proceso de integración más sencillo y ágil.
Rápida implementación
La implementación ágil y fácil personalización terminan colaborando significativamente para simplificar también el proceso de desarrollo y permitir que resultados prácticos sean alcanzados en un menor tiempo hábil.
Datos encapsulados
Como la API ofrece tan solo una punta 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 termina siendo encapsulada, perfeccionando la seguridad y la confidencialidad de los datos.
La API para gestión de contactos de Zenvia Attraction
La API ofrece las mismas funcionalidades del panel de gestión de contactos de Zenvia Attraction, permitiéndote agrupar los contactos en una lista para utilizarlos como público objetivo para tus campañas.
💡 Sugerencia: Para más informaciones sobre el panel de gestión de contactos de Attraction, consulta el artículo Gestionar contactos en Zenvia Attraction.
A seguir te mostraremos cómo utilizar los documentos API de ZenAPI para integrar la API de gestión de contactos.
Cómo ZenAPI funciona
En primer lugar, abre los documentos de la ZenAPI y localiza Contacts en el menú a la izquierda, todos los documentos que están debajo de esta categoría son referentes a la API de gestión de contactos de Zenvia Attraction.
En este ejemplo, detallaremos la primera acción, el Create a new contact.
El próximo paso para usar la API es realizar la verificación.
Cómo funciona la verificación de la API
Para utilizar la API necesitarás pasar un token de autorización, que puede ser:
- Token JWT usado por el servicio Front-End de Zenvia;
- X-API-Token pasado en el parámetro del Header.
Es posible encontrarlos en este lugar del documento:
Entre estos dos, recomendamos principalmente el X-API-Token por sus beneficios para la seguridad, ya que en el caso de que sea necesario, puedes simplemente revocar el acceso fácilmente por medio del panel de Tokens y Webhooks en el menú Programadores de la Plataforma Zenvia. Además, para crear un nuevo Token solo necesitas hacer clic en Crear nuevo, en la misma pantalla:
Fíjate que para poder realizar cualquiera de las acciones disponibles, necesitas 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 requisición en el cuerpo.
Cómo realizar una requisición
Para crear un nuevo contacto, el programador necesitará usar el método de la acción en la URL. En nuestro caso, sería el método POST.
Necesitará, por lo tanto, emplear el método POST en la url https://api.zenvia.com/v2/contacts y pasar al cuerpo de la requisición el siguiente payload:
{
"channels": {
"email": "contact@domain.example",
"mobile": "5510888883333",
"landline": "551044443333"
},
"firstName": "Rafael",
"lastName": "Souza",
"customData": {
"property1": "2022-06-13",
"property2": "2022-06-13"
},
"addresses": [
{
"country": "Brazil",
"zipcode": "01310-300",
"state": "SP",
"city": "São Paulo",
"address": "Av. Paulista",
"streetNumber": "2300",
"neighborhood": "Bela Vista"
}
],
"listIds": [
"list-id-01",
"list-id-02",
"list-id-03"
]
}
Para tener más informaciones sobre cada componente del Payload, solo necesitas consultar la descripción localizada en Request body schema:
En esta sección, aparece lo que significa cada campo, cómo deben ser pasados y cómo el payload necesita ser pasado en esta estructura.
Ahora que ya sabes cómo trabajar con la API y cómo navegar en los documentos, abajo tienes una lista de todas las funcionalidades disponibles en el gestor de contactos de Zenvia Attraction.
Qué es lo que puedes hacer con la API
Utilizando la API de gestión de contactos de Zenvia Attraction, puedes:
- Crear contactos;
- Crear una lista con todos los contactos disponibles;
- Recuperar las informaciones de un contacto;
- Actualizar las informaciones de un contacto;
- Excluir un contacto;
- Crear listas de contactos;
- Mostrar todas las listas de contactos disponibles;
- Recuperar las informaciones de una lista de contactos;
- Actualizar las informaciones de una lista de contactos;
- Excluir una lista de contactos (solo la lista será excluida, no los contactos);
- Mostrar los contactos de una lista de contactos;
- Crear campos de datos personalizados para utilizarlos en la API de contactos;
- Mostrar todos los campos de datos personalizados de contacto disponibles.
¡Listo! Ahora que conoces la API de Zenvia Attraction, consulta más informaciones sobre el gestor de contactos.