API de ZeroChats — tus datos donde ya trabajas

Qué es

La API de ZeroChats te deja trabajar con los datos de tu negocio desde fuera de la plataforma. Generas una clave, la pones en la herramienta que ya usas y esa herramienta habla directamente con ZeroChats. Hoy cubre dos cosas:

• Estadísticas. Los mismos leads, las mismas conversiones y el mismo rendimiento por publicación que ves en la sección Estadísticas, listos para llevarlos a un panel o a una hoja de cálculo.
• Leads. Buscar un lead por usuario, email o teléfono, leer su ficha y cambiarle la etapa, las etiquetas o los datos de contacto desde otra herramienta.

Es la respuesta a un problema concreto: tus datos de ZeroChats viven en ZeroChats y el resto —inversión en anuncios, reservas, pagos, facturación— viven en otro sitio. Con la API los juntas sin exportar un CSV cada lunes, y cuando pasa algo en otra herramienta puedes reflejarlo en el lead sin entrar en el dashboard.

Looker Studio o Power BI

Un panel que mezcla tus leads de ZeroChats con la inversión publicitaria y calcula el coste real por cliente.

Google Sheets

Una hoja que se actualiza sola con los leads del mes y las conversiones por enlace de venta.

n8n, Make o Zapier

Un flujo que cada lunes publica el resumen de la semana en Slack, y otro que, cuando alguien reserva o paga en otra herramienta, etiqueta al lead y lo mueve de etapa.

Tu propio backend

Cualquier servicio que sepa hacer una petición HTTP con una cabecera puede consumirla.

La API no crea leads ni manda mensajes. Sí puede cambiar la etapa, las etiquetas y los datos de contacto de un lead a través de los endpoints de leads; todo lo demás sigue siendo de solo lectura.

Si lo que quieres es reaccionar a un evento, no es esto

Esta API la consultas tú cuando quieres. Si lo que necesitas es enterarte en el momento de que llega un lead o cambia de etapa, lo tuyo es el Webhook personalizado, que te avisa a ti. Las dos piezas se complementan: el webhook te dice que ha pasado algo y la API te deja consultarlo o actuar sobre ello.

Cómo conseguir tu clave

1. Entra en Configuración del negocio y abre la pestaña Integraciones. Las herramientas están en la sección CRM, webhooks y tracking, una tarjeta por integración.

2. Busca la tarjeta API de ZeroChats y pulsa Crear clave.

3. Pulsa Generar clave. La clave aparece en pantalla, empieza por zcst_ y es única de tu negocio.

4. Cópiala en ese momento. Es la única vez que se muestra completa. A partir de ahí solo verás una versión abreviada, tipo zcst_ab12…7yz9, suficiente para reconocerla pero no para usarla.

5. Guárdala en tu herramienta y haz la primera llamada para comprobar que responde.

Una vez creada, la tarjeta te dice si la clave se ha usado alguna vez y cuándo fue la última llamada. Es la forma rápida de comprobar que la integración del otro lado está realmente funcionando: si dice sin llamadas todavía, tu herramienta no ha llegado a conectar.

Desde ese mismo diálogo puedes Regenerar la clave (crea una nueva y anula la anterior al instante) o Revocarla (la borra; a partir de ese momento toda llamada recibe un error de autorización).

La clave solo se muestra una vez

No la guardamos en claro en ningún sitio: conservamos únicamente una huella cifrada que nos sirve para reconocerla, nunca la clave en sí. Por eso no podemos volver a enseñártela ni recuperarla para ti. Si la pierdes, entra y pulsa Regenerar: tendrás una nueva en dos segundos, y solo tienes que actualizarla donde la hayas puesto.

Seguridad

Léete esta sección entera antes de pegar la clave en ningún sitio.

• La clave solo alcanza tu negocio. El negocio no se indica en la petición: se deduce de la propia clave. Una clave no puede consultar los datos de otra cuenta ni aunque quien la tenga lo intente a propósito, sencillamente porque no hay ningún parámetro donde pedirlo. Cualquier lead que no sea tuyo responde 404, igual que uno que no existe.
• La clave también edita leads. Quien la tenga puede cambiar la etapa, las etiquetas y los datos de contacto de tus leads, no solo leer métricas. Trátala como una contraseña con permisos de escritura.
• Es de servidor a servidor. No la pongas en una página web, ni en una app móvil, ni en el JavaScript de tu landing. Cualquiera que abra esa página puede ver la clave en el código y, con ella, leer todas tus métricas y tocar tus leads.
• Guárdala donde se guardan las contraseñas. El almacén de credenciales de n8n, las variables de entorno de tu servidor, los custom values de GoHighLevel. No en un documento compartido ni en un export de flujo que luego circula por correo.
• Ante la duda, regenera. Si la clave ha acabado en un log, en una captura de pantalla o en un chat, regenérala. Es gratis e instantáneo; lo único que cuesta es actualizarla en tu herramienta.
• Una clave por negocio. Al generar una nueva se sustituye la anterior, así que si tienes varias integraciones apuntando a la misma clave, todas dejan de funcionar a la vez cuando la regeneras. Actualízalas todas.

Primera llamada

La URL base es:

https://app.zerochats.com/api/v1

La clave viaja en la cabecera Authorization:

cURL

curl -H "Authorization: Bearer zcst_tu_clave" \
  https://app.zerochats.com/api/v1/me

n8n

Añade un nodo HTTP Request:

• Método GET, URL https://app.zerochats.com/api/v1/me.
• Authentication → Generic Credential Type → Header Auth.
• Nombre de la cabecera Authorization, valor Bearer zcst_tu_clave.

Guarda la credencial una vez y reutilízala en todos los nodos que llamen a la API.

Node.js

const respuesta = await fetch('https://app.zerochats.com/api/v1/me', {
  headers: { Authorization: `Bearer ${process.env.ZEROCHATS_API_KEY}` },
});

const { success, data, meta } = await respuesta.json();

Si tu herramienta no te deja tocar la cabecera Authorization, también aceptamos la clave en x-api-key con el mismo valor, sin el Bearer delante.

GET /me no devuelve métricas ni leads: solo te dice a qué negocio pertenece la clave y en qué zona horaria están expresados los días de las estadísticas. Es la llamada más barata para comprobar que la clave funciona antes de montar nada encima.

{
  "success": true,
  "data": { "id": "b7a2f1d9-5c34-4a61-8e2f-0d9c1b4a7e33", "name": "Mi negocio", "locale": "es" },
  "meta": { "timezone": "Europe/Madrid" }
}

La URL de estadísticas sigue funcionando

Los endpoints de estadísticas mantienen su base https://app.zerochats.com/api/statistics/v1, y /api/statistics/v1/me responde exactamente lo mismo que /api/v1/me. No tienes que cambiar nada de lo que ya tengas montado.

Qué te devuelve

Todas las respuestas tienen la misma forma. Si la llamada va bien:

{
  "success": true,
  "data": {},
  "meta": {}
}

data cambia según el endpoint. meta solo viaja en los endpoints que tienen algo que contarte: en los de estadísticas siempre, con el periodo y la zona horaria que han producido los números; en /me, con la zona horaria; en los de leads no viene.

Si algo falla:

{
  "success": false,
  "error": {
    "code": "invalid_request",
    "message": "provide exactly one of username, email or phone"
  }
}

Toma tus decisiones mirando error.code, que es estable. El message está pensado para que lo leas tú mientras montas la integración y puede cambiar de redacción.

Límite de peticiones

Puedes hacer 60 peticiones por minuto, contando todos los endpoints juntos. Es de sobra para un panel que se refresca cada hora, un informe diario o un flujo que actualiza leads según van llegando reservas; solo te lo encontrarás si montas un bucle que recorre muchos días o muchos leads de uno en uno.

Cada respuesta te dice cómo vas:

Cabecera	Qué es
X-RateLimit-Limit	Peticiones permitidas por minuto.
X-RateLimit-Remaining	Las que te quedan en este minuto.
X-RateLimit-Reset	Cuándo se renueva el cupo, en segundos Unix.
Retry-After	Segundos que tienes que esperar. Solo cuando te pasas.

Cuando te pasas recibes un 429 con error.code a rate_limited. La forma correcta de tratarlo es esperar los segundos que dice Retry-After y reintentar: cuando vuelvas tendrás el cupo entero. Reintentar antes solo consume intentos.

No reintentes en bucle sin esperar

Un flujo que reintenta inmediatamente ante un 429 se queda dando vueltas sin avanzar. Si tu herramienta no sabe esperar, mete un paso de espera explícito antes del reintento.

Errores

Código HTTP	error.code	Qué ha pasado
401	unauthorized	Falta la cabecera, o la clave está mal escrita, revocada o ya no existe.
400	invalid_request	Un parámetro o el cuerpo no es válido. El message te dice cuál.
404	not_found	El lead no existe o no es de tu negocio.
429	rate_limited	Has superado las 60 peticiones en el minuto en curso.
500	internal_error	Algo ha fallado por nuestra parte. Reintenta con espera y, si sigue, abre un ticket.

Un 401 después de que todo funcionara suele significar una de dos cosas: alguien ha regenerado la clave desde la app, o la ha revocado. Entra en el diálogo y comprueba la fecha de creación.

Buenas prácticas

• Usa id como clave, no name. Los nombres de etiquetas, contenidos y enlaces de venta se pueden cambiar desde la app; los identificadores no. Con los leads pasa lo mismo: el id que te da el webhook o la búsqueda es estable, el usuario puede cambiar.
• Guarda la respuesta cruda además de tu tabla procesada, al menos mientras montas la integración. Cuando un número no cuadre, tener el JSON original ahorra medio día.
• Refresca con cabeza. Los paneles de negocio se leen una vez al día; refrescar cada minuto no te da información nueva y te acerca al límite de peticiones.
• Deja que el webhook te avise y usa la API para actuar. Sondear la API cada pocos segundos para detectar cambios es la forma más rápida de gastar el cupo; el Webhook personalizado te lo cuenta gratis y al instante.

Endpoints

API · Estadísticas Totales, embudo, leads por día, conversiones por enlace, etiqueta y contenido, rendimiento por publicación.

API · Leads Busca un lead por usuario, email o teléfono, lee su ficha y cámbiale la etapa, las etiquetas o el contacto.