API de leads
Cómo enviar a Qubilia los contactos de tu sitio web, tus campañas, un portal o cualquier sistema, para que lleguen solos como prospectos.
En corto: cada origen de contactos tiene en Qubilia una «entrada de leads» con una dirección propia. Tu formulario o tu sistema hace un POST a esa dirección con el nombre, el correo o el teléfono, y el contacto aparece como prospecto con su canal, su campaña y su ejecutivo.
Qué se puede conectar hoy
- Sitio web y WordPress: un formulario propio o un plugin con acción «Webhook» (Contact Form 7, WPForms, Elementor, Gravity Forms, Fluent Forms).
- Meta Lead Ads (Facebook e Instagram) y Google Ads (formularios de clientes potenciales).
- Portales inmobiliarios y otros servicios que avisan por webhook, o a través de Zapier o Make.
Esta API es de entrada: recibe contactos. Todavía no hay una API para consultar stock, precios o ventas desde otro sistema; esos datos se descargan desde el panel, en «Exportar datos».
La dirección de recepción
La crea el administrador de la cuenta en Configuración → Integraciones → Nueva entrada. Tiene esta forma:
POST https://qubilia.com/leads/in/TOKEN_DE_LA_ENTRADA - El token de la dirección identifica la entrada y la empresa: no se envía una clave aparte. Trátalo como una contraseña.
- Si se filtra, «Cambiar dirección» genera una nueva y la anterior deja de recibir.
- Siempre por HTTPS. Acepta envíos desde el navegador de cualquier sitio (CORS abierto).
- Crea una entrada por cada origen (el formulario del sitio, cada campaña, cada portal): así los reportes distinguen qué canal trae visitas y cuál trae promesas.
Formatos
El cuerpo puede ir como formulario (application/x-www-form-urlencoded o multipart/form-data) o como JSON (application/json).
Campos
Los nombres se leen sin distinguir mayúsculas, acentos, guiones ni espacios: Teléfono, telefono y phone_number sirven igual. Lo mínimo es un correo o un teléfono válido.
| Dato | Nombres que entiende | Notas |
|---|---|---|
| Nombre completo | nombre, name, full_name, nombre_completo | Si no viene, se usa la parte inicial del correo. |
| Nombre y apellido por separado | nombres, first_name · apellido, apellidos, last_name | Alternativa al nombre completo. |
| Correo | correo, email, mail | Obligatorio si no hay teléfono. |
| Teléfono | telefono, phone, celular, whatsapp, fono | Obligatorio si no hay correo. |
| Mensaje | mensaje, message, comentario, consulta | Queda en el historial del prospecto. |
| Proyecto | proyecto, project | La sigla o el nombre del proyecto. No hace falta si la entrada es de un solo proyecto. |
| Campaña | campana, campaign, utm_campaign, campaign_name | Se usa en los reportes por campaña. utm_source y utm_medium también se guardan. |
| RUT | rut, tax_id | Opcional. |
| Identificador propio | lead_id, external_id, id | Si se repite en la misma entrada, el envío se descarta como repetido. |
| Página de gracias | redirect | Solo en formularios: una dirección http(s) a la que se envía a la persona después de registrar el contacto. |
| Prueba | is_test, test | Con cualquier valor, el envío se anota como «Prueba» y no crea un prospecto. |
| Campo trampa | website, url, homepage | Debe ir vacío: un campo oculto que las personas no llenan y los robots sí. Si trae algo, el envío se descarta. |
Ejemplos
JSON desde un servidor
curl -X POST 'https://qubilia.com/leads/in/TOKEN_DE_LA_ENTRADA' \
-H 'Content-Type: application/json' \
-d '{
"nombre": "Camila Rojas",
"correo": "camila@correo.example",
"telefono": "+56 9 5555 0100",
"mensaje": "Quiero visitar el piloto el sábado",
"proyecto": "Edificio Parque",
"utm_campaign": "lanzamiento"
}' Formulario en una página
<form method="post" action="https://qubilia.com/leads/in/TOKEN_DE_LA_ENTRADA">
<input name="nombre" required>
<input name="correo" type="email" required>
<input name="telefono">
<textarea name="mensaje"></textarea>
<input name="website" tabindex="-1" autocomplete="off" style="display:none">
<input type="hidden" name="redirect" value="https://tu-sitio.example/gracias">
<button>Enviar</button>
</form> Desde JavaScript
const respuesta = await fetch('https://qubilia.com/leads/in/TOKEN_DE_LA_ENTRADA', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ nombre, correo, telefono, mensaje })
});
const datos = await respuesta.json(); // { ok: true, result: "received" }
Respuestas
| Código | Cuerpo | Qué significa |
|---|---|---|
| 200 | {"ok":true,"result":"received"} | El envío se recibió. Qué se hizo con él (prospecto nuevo, ya existía, repetido o descartado) se ve en la bitácora de la entrada. |
| 303 | Redirección | Formulario con redirect: el navegador va a la página de gracias. |
| 403 | {"ok":false,"result":"rejected"} | Google Ads: la clave del webhook no coincide con la de la entrada. |
| 404 | {"ok":false,"error":"…"} | La dirección no existe o fue cambiada. |
| 429 | {"ok":false,"error":"…"} | Más de 60 envíos en 10 minutos desde una misma conexión a una misma entrada. |
| 500 | {"ok":false,"error":"…"} | No se pudo registrar. Reintenta más tarde. |
La respuesta 200 no detalla el resultado a propósito, para no dar pistas a envíos automáticos. Mientras pruebas, mira la bitácora de la entrada: muestra cada recepción y su motivo.
Qué pasa con cada contacto
- Se crea un prospecto con el canal de la entrada, su campaña, su proyecto y el ejecutivo que defina la entrada (ninguno, siempre la misma persona o el que tenga menos prospectos abiertos).
- Si la persona ya es un prospecto abierto (mismo correo o mismos últimos 8 dígitos del teléfono), no se duplica: el envío se anota en su historial.
- Una entrada desactivada no crea prospectos, pero anota lo que llega.
Meta y Google
Google Ads
En el formulario de clientes potenciales, en «Opciones de exportación → Webhook», se pega la dirección de recepción y, como clave, la clave de verificación de la entrada. Google envía su propio formato (user_column_data con google_key) y Qubilia lo entiende sin configuración adicional. El botón «Enviar datos de prueba» de Google aparece en la bitácora como «Prueba».
Meta Lead Ads
La dirección de recepción se registra como webhook de una app de Meta suscrita al campo leadgen de la página. Meta la verifica con un GET (hub.verify_token debe ser la clave de verificación de la entrada) y después avisa cada lead con un POST. Qubilia pide los datos del lead a la Graph API con el token de acceso de la página (permiso leads_retrieval), que se guarda cifrado en la entrada. Si la entrada tiene la clave secreta de la app, se comprueba la firma X-Hub-Signature-256 de cada aviso.
Los pasos, uno a uno y con los datos de tu entrada, están en el panel, dentro de cada entrada, en «Cómo conectarla».
Ayuda
Si una conexión no funciona, envíanos la hora del intento y lo que muestra la bitácora de la entrada desde Soporte o a soporte@qubits.cl.