API externa del CRM

Que es la API externa del CRM

La API externa te permite integrar tu CRM con cualquier herramienta o servicio externo. Con ella puedes crear y actualizar contactos, y disparar eventos personalizados que activan automatizaciones, todo mediante peticiones HTTP simples autenticadas con una API key.

Casos de uso comunes:

• Zapier / n8n / Make — sincronizar contactos desde formularios, CRMs externos o tiendas online.
• WordPress — enviar leads de formularios de contacto a tu CRM.
• Webinars — registrar asistentes como contactos y disparar automatizaciones.
• Apps custom — cualquier backend que necesite comunicarse con tu CRM.

Generar tu API key

Cada academia tiene una API key unica. Para generarla:

• Ve a Admin > Ajustes y busca la seccion API.
• Haz clic en Generar API key.
• Copia la key que se muestra (empieza con dk_). Guardala en un lugar seguro — solo se muestra completa una vez.

Si necesitas revocar la key (por seguridad o rotacion), haz clic en Revocar. Esto invalida la key actual inmediatamente. Puedes generar una nueva despues.

Autenticacion

Todas las peticiones a la API deben incluir tu API key en el header x-api-key:

x-api-key: dk_tu-api-key-aqui

Las peticiones sin API key valida reciben un error 401 Unauthorized.

Endpoint: Crear o actualizar contacto

POST /api/tenant/contacts

Crea un contacto nuevo o actualiza uno existente si ya existe con el mismo email (upsert). Body JSON:

• email (obligatorio) — email del contacto.
• firstName — nombre.
• lastName — apellido.
• phone — telefono.
• company — empresa.
• tags — array de nombres de tags (se crean automaticamente si no existen). Ejemplo: ["vip", "webinar-abril"].
• metadata — objeto con valores para propiedades custom. Las claves deben coincidir con los identificadores de las propiedades. Ejemplo: { "ciudad": "Bogota", "nivel": "avanzado" }.

Ejemplo con curl

curl -X POST https://tu-academia.didia.io/api/tenant/contacts \

  -H "Content-Type: application/json" \

  -H "x-api-key: dk_tu-key" \

  -d '{ "email": "juan@ejemplo.com", "firstName": "Juan", "tags": ["lead", "webinar"], "metadata": { "ciudad": "CDMX" } }'

Comportamiento del upsert

• Si el email no existe, se crea un contacto nuevo con todos los datos proporcionados.
• Si el email ya existe, se actualizan los campos proporcionados. Los campos no incluidos en la peticion no se modifican.
• El metadata se hace merge: las claves nuevas se agregan, las existentes se actualizan, las no incluidas se mantienen.
• Los tags se agregan al contacto (no se eliminan los existentes). Si un tag no existe en el CRM, se crea automaticamente.

Respuesta exitosa

{ "success": true, "contactId": "uuid-del-contacto" }

Endpoint: Disparar evento personalizado

POST /api/tenant/events

Dispara un evento personalizado asociado a un contacto. El evento puede activar automatizaciones que tengan el trigger Evento personalizado con el mismo nombre de evento. Body JSON:

• email (obligatorio) — email del contacto que genera el evento.
• eventName (obligatorio) — nombre del evento (ej: webinar_attended, lead_qualified, form_submitted).
• metadata — datos adicionales del evento (opcionales).

Ejemplo con curl

curl -X POST https://tu-academia.didia.io/api/tenant/events \

  -H "Content-Type: application/json" \

  -H "x-api-key: dk_tu-key" \

  -d '{ "email": "juan@ejemplo.com", "eventName": "webinar_attended", "metadata": { "webinar": "Lanzamiento abril" } }'

Que sucede al disparar un evento

• Se registra en el timeline de actividad del contacto como Evento: [nombre].
• Se buscan automatizaciones con trigger Evento personalizado cuyo eventName coincida. Si existen y estan activas, se ejecutan automaticamente.
• Si el email no corresponde a un contacto existente, se devuelve un error.

Eventos custom en automatizaciones

Para que un evento dispare una automatizacion:

• Crea una automatizacion en Admin > CRM > Automatizaciones.
• En el nodo de trigger, selecciona Evento personalizado (grupo Custom).
• Escribe el nombre del evento exacto (ej: webinar_attended). Debe coincidir con lo que envias desde la API.
• Agrega las acciones que deseas ejecutar (enviar email, agregar tag, etc.).
• Activa la automatizacion.

Tambien puedes usar la accion Disparar evento en una automatizacion para que una automatizacion dispare otra, creando cadenas de automatizaciones.

Seguridad

• La API key tiene acceso completo al CRM de tu academia. Nunca la expongas en codigo frontend ni en repositorios publicos.
• Almacenala en variables de entorno de tu servidor o en la configuracion segura de Zapier/n8n.
• Si sospechas que tu key fue comprometida, revocala inmediatamente desde Admin > Ajustes > API y genera una nueva.
• Todas las peticiones deben usar HTTPS.

Preguntas frecuentes

• ¿Cuantas API keys puedo tener?

  Actualmente cada academia tiene una API key. Si necesitas revocar la actual, puedes generar una nueva. La key anterior deja de funcionar inmediatamente.

• ¿Hay limite de peticiones?

  La API externa comparte los rate limits de tu plan (60/min Trial, 300/min Pro, 1000/min Enterprise).

• ¿Puedo eliminar contactos via API?

  No. La API externa actualmente soporta crear/actualizar contactos y disparar eventos. La eliminacion de contactos se hace desde el panel de administracion.

• ¿Los tags se crean automaticamente si no existen?

  Si. Si envias un tag en el array tags que no existe en tu CRM, se crea automaticamente con ese nombre y se asigna al contacto.

• ¿Puedo disparar eventos para contactos que no existen?

  No. El endpoint de eventos requiere que el contacto ya exista (se busca por email). Si necesitas crear el contacto y disparar el evento, haz dos peticiones: primero al endpoint de contactos, luego al de eventos.

• ¿Como conecto Zapier con la API?

  En Zapier, usa la accion Webhooks by Zapier > POST. Configura la URL del endpoint, agrega el header x-api-key con tu key, y mapea los campos del trigger al body JSON. La misma logica aplica para n8n (nodo HTTP Request) y Make (modulo HTTP).