En este tutorial aprenderás a conectar tuSoftware con Wechatia para enviar información de usuarios, contactos y campos personalizados mediante la API REST.
El objetivo es que, cuando se cree un usuario en tuSoftware, sus datos puedan enviarse automáticamente a Wechatia.
La estructura será:
tuSoftware
│
│ API REST
▼
Wechatia
│
▼
Contacto creado o actualizado
Antes de comenzar, necesitarás obtener algunos datos de tu cuenta de Wechatia.
Es el token que permitirá a tuSoftware autenticarse ante la API.
TU_PRIVATE_INTEGRATION_TOKEN
Identifica la cuenta de Wechatia donde se almacenará el contacto.
TU_LOCATION_ID
Identifica un campo personalizado de Wechatia.
TU_CUSTOM_FIELD_ID
El Contact ID identifica un contacto específico dentro de Wechatia.
Este ID será generado cuando crees el contacto mediante la API.
Si necesitas enviar información adicional además del nombre, correo o teléfono, primero debes crear los campos personalizados en Wechatia.
Ingresa a:
Configuración → Campos personalizados
Crea el campo que necesitas.
Por ejemplo:
Nombre:
ID de usuario de tuSoftware
Tipo:
Texto
También puedes crear otros campos como:
Fecha de nacimiento
Tipo de cliente
Número de cliente
Empresa
Cargo
Estado
ID externo
Cada campo personalizado tendrá un identificador propio.
Por ejemplo:
Custom Field ID:
6dvNaf7VhkQ9snc5vnjJ
Este ID será necesario cuando envíes el valor del campo mediante la API.
Para que tuSoftware pueda comunicarse con Wechatia, debes crear una integración privada.
Ingresa a:
Configuración → Integraciones privadas
Selecciona:
Crear nueva integración
Puedes utilizar como nombre:
Integración con tuSoftware
Agrega una descripción si lo deseas.
Por ejemplo:
Integración para enviar usuarios desde tuSoftware a Wechatia.
Durante la creación de la integración tendrás que seleccionar los permisos que utilizará tuSoftware.
Si solamente necesitas crear y actualizar contactos, selecciona los permisos relacionados con contactos.
Si además necesitas trabajar con campos personalizados u otros recursos, agrega los permisos correspondientes.
Utiliza únicamente los permisos que realmente necesite tuSoftware.
Una vez configurados los permisos, crea la integración.
Wechatia generará un:
Private Integration Token
Por ejemplo:
TU_PRIVATE_INTEGRATION_TOKEN
Guárdalo en un lugar seguro.
Este token será utilizado por tuSoftware para autenticarse en cada solicitud.
La autenticación se realiza mediante:
Authorization: Bearer TU_PRIVATE_INTEGRATION_TOKEN
Importante: no publiques este token ni lo incluyas directamente en código que pueda ser visible para los usuarios.
TuSoftware necesita indicar en qué cuenta de Wechatia debe crearse el contacto.
Para esto se utiliza el:
Location ID
Por ejemplo:
TU_LOCATION_ID
Para los ejemplos de este tutorial utilizaremos:
ve9EPM428h8vShlRW1KT
Este valor es únicamente un ejemplo.
Debes utilizar el Location ID real de la cuenta de Wechatia donde quieres almacenar los contactos.
Ahora debes configurar tuSoftware para realizar solicitudes a la API REST.
La URL base de la API es:
https://services.leadconnectorhq.com
Para crear un contacto, utilizaremos:
https://services.leadconnectorhq.com/contacts/
Por lo tanto, tuSoftware deberá tener configurados:
API Base URL:
https://services.leadconnectorhq.com
Endpoint:
https://services.leadconnectorhq.com/contacts/
Private Integration Token:
TU_PRIVATE_INTEGRATION_TOKEN
Location ID:
TU_LOCATION_ID
Supongamos que un nuevo usuario se registra en tuSoftware.
Por ejemplo:
Nombre:
Juan
Apellido:
Pérez
Correo:
juan@ejemplo.com
Teléfono:
+56912345678
ID de usuario:
123456
TuSoftware deberá tomar esta información y enviarla a Wechatia mediante una solicitud HTTP.
La solicitud será:
POST https://services.leadconnectorhq.com/contacts/
Los encabezados serán:
Authorization: Bearer TU_PRIVATE_INTEGRATION_TOKEN
Content-Type: application/json
Version: 2021-07-28
El cuerpo de la solicitud puede ser:
{
"firstName": "Juan",
"lastName": "Pérez",
"email": "juan@ejemplo.com",
"phone": "+56912345678",
"locationId": "TU_LOCATION_ID",
"customFields": [
{
"id": "TU_CUSTOM_FIELD_ID",
"fieldValue": "123456"
}
]
}
En este ejemplo:
firstName
corresponde al nombre.
lastName
corresponde al apellido.
email
corresponde al correo.
phone
corresponde al teléfono.
locationId
indica en qué cuenta de Wechatia se creará el contacto.
customFields
permite enviar información almacenada en campos personalizados.
Supongamos que tenemos los siguientes datos:
API:
https://services.leadconnectorhq.com
Endpoint:
https://services.leadconnectorhq.com/contacts/
Private Integration Token:
TU_PRIVATE_INTEGRATION_TOKEN
Location ID:
ve9EPM428h8vShlRW1KT
Custom Field ID:
6dvNaf7VhkQ9snc5vnjJ
La solicitud sería:
POST https://services.leadconnectorhq.com/contacts/
Authorization: Bearer TU_PRIVATE_INTEGRATION_TOKEN
Content-Type: application/json
Version: 2021-07-28
Y el contenido:
{
"firstName": "Juan",
"lastName": "Pérez",
"email": "juan@ejemplo.com",
"phone": "+56912345678",
"locationId": "ve9EPM428h8vShlRW1KT",
"customFields": [
{
"id": "6dvNaf7VhkQ9snc5vnjJ",
"fieldValue": "123456"
}
]
}
Cuando Wechatia cree correctamente el contacto, la API devolverá la información del contacto creado.
Por ejemplo:
{
"contact": {
"id": "abc123456789",
"name": "Juan Pérez",
"firstName": "Juan",
"lastName": "Pérez",
"email": "juan@ejemplo.com",
"phone": "+56912345678",
"locationId": "ve9EPM428h8vShlRW1KT"
}
}
El dato más importante será:
Contact ID:
abc123456789
TuSoftware debería guardar este identificador en su propia base de datos.
Por ejemplo:
Usuario tuSoftware:
123456
Contact ID Wechatia:
abc123456789
De esta forma, tuSoftware podrá saber qué contacto de Wechatia corresponde a cada uno de sus usuarios.
Si posteriormente necesitas modificar un contacto que ya existe en Wechatia, puedes utilizar el Contact ID.
El endpoint será:
PUT https://services.leadconnectorhq.com/contacts/{CONTACT_ID}
Por ejemplo:
PUT https://services.leadconnectorhq.com/contacts/abc123456789
Los encabezados:
Authorization: Bearer TU_PRIVATE_INTEGRATION_TOKEN
Content-Type: application/json
Version: 2021-07-28
Y puedes enviar los datos que quieras modificar:
{
"firstName": "Juan",
"lastName": "Pérez",
"phone": "+56987654321"
}
De esta manera, tuSoftware puede actualizar la información que ya existe en Wechatia.
También puedes enviar información adicional mediante campos personalizados.
Por ejemplo, si en Wechatia tienes:
Nombre:
ID de usuario de tuSoftware
Custom Field ID:
6dvNaf7VhkQ9snc5vnjJ
Y el usuario de tuSoftware tiene:
ID:
123456
Puedes enviar:
{
"customFields": [
{
"id": "6dvNaf7VhkQ9snc5vnjJ",
"fieldValue": "123456"
}
]
}
Wechatia almacenará:
ID de usuario de tuSoftware:
123456
Esto resulta especialmente útil para relacionar los registros de ambos sistemas.
Una integración básica funcionará de la siguiente manera:
1. Usuario se registra en tuSoftware
↓
2. tuSoftware obtiene sus datos
↓
3. tuSoftware realiza una solicitud POST
↓
4. API de Wechatia recibe la información
↓
5. Wechatia crea el contacto
↓
6. Wechatia devuelve el Contact ID
↓
7. tuSoftware guarda el Contact ID
Por ejemplo:
Usuario tuSoftware
ID: 123456
│
▼
POST /contacts/
│
▼
Wechatia
│
▼
Contact ID:
abc123456789
│
▼
tuSoftware guarda la relación
Antes de crear un contacto nuevo, es recomendable comprobar si ese usuario ya existe en Wechatia.
Una buena práctica es guardar en tuSoftware:
ID usuario tuSoftware
+
Contact ID Wechatia
Por ejemplo:
Usuario tuSoftware: 123456
Contact ID Wechatia: abc123456789
Cuando el usuario vuelva a modificar sus datos, tuSoftware puede utilizar el Contact ID existente para actualizar el contacto en lugar de crear uno nuevo.
El Private Integration Token debe mantenerse protegido.
No debes:
Lo recomendable es que las solicitudes a la API se realicen desde el servidor de tuSoftware.
La estructura debe ser:
Navegador del usuario
↓
tuSoftware
↓
Servidor de tuSoftware
↓
API de Wechatia
Y no:
Navegador del usuario
↓
API de Wechatia
↑
Token expuesto
Para realizar esta integración necesitarás:
https://services.leadconnectorhq.com
POST
https://services.leadconnectorhq.com/contacts/
PUT
https://services.leadconnectorhq.com/contacts/{CONTACT_ID}
Authorization: Bearer TU_PRIVATE_INTEGRATION_TOKEN
TU_LOCATION_ID
TU_CONTACT_ID
TU_CUSTOM_FIELD_ID
Una vez configurado todo, tuSoftware podrá enviar automáticamente usuarios a Wechatia.
Por ejemplo:
tuSoftware
│
├── Nombre
├── Apellido
├── Email
├── Teléfono
├── ID de usuario
└── Datos personalizados
│
▼
API REST de Wechatia
│
▼
Wechatia
│
▼
Contacto
De esta manera, cada vez que tuSoftware registre un nuevo usuario, podrá crear el contacto correspondiente en Wechatia y almacenar su Contact ID para futuras actualizaciones.
