Guía completa de integraciones y API
Integraciones y API a fondo, en 30 capítulos: claves API, llamadas reales, webhooks firmados, n8n, MCP y SDK, todo funcionando de verdad.
Capítulos del video
- 00:00 Introducción
- 00:43 Las formas de conectar Omnifox Leer este paso →
- 01:20 Requisitos: plan y permisos Leer este paso →
- 01:40 Crear una clave API Leer este paso →
- 02:22 Alcances: qué puede hacer la clave Leer este paso →
- 03:01 Copiar la clave una sola vez
- 03:22 La lista de claves: editar, regenerar y eliminar
- 03:48 La documentación de la API Leer este paso →
- 04:26 Tu primera llamada
- 04:55 Contactos por API Leer este paso →
- 05:23 Alcances en acción: el error 403 Leer este paso →
- 05:53 Conversaciones y mensajes por API Leer este paso →
- 06:31 CRM y calendario por API Leer este paso →
- 07:03 Paginación y límites Leer este paso →
- 07:26 Webhooks: crear una suscripción Leer este paso →
- 08:01 Secreto de firma, reintentos y encabezados Leer este paso →
- 08:41 Entrega de prueba
- 09:00 Un evento real
- 09:31 Verificar la firma en tu servidor Leer este paso →
- 10:00 Historial de entregas Leer este paso →
- 10:37 La página de integraciones Leer este paso →
- 11:06 Webhook personalizado: entrada y salida
- 11:40 n8n: instalar el nodo de Omnifox Leer este paso →
- 12:06 n8n: la credencial de Omnifox
- 12:30 n8n: responder solo cuando preguntan el precio
- 13:17 n8n: todas las operaciones
- 13:49 MCP: que una IA opere Omnifox Leer este paso →
- 14:20 Probar el servidor MCP con el Inspector Leer este paso →
- 15:02 SDK oficiales: Node, Python y PHP Leer este paso →
- 15:37 Buenas prácticas de seguridad Leer este paso →
- 16:03 Solución de problemas Leer este paso →
- 16:35 Cierre
Esta es la guía completa de integraciones y API, con 30 capítulos: claves API con alcances, la documentación, llamadas reales (contactos, conversaciones, CRM, calendario), errores y paginación, webhooks firmados con su historial, las tarjetas de integraciones, n8n, el servidor MCP y los SDK de Node, Python y PHP. El manual en PDF tiene los mismos capítulos con capturas y ejemplos.
1. Las formas de conectar Omnifox
Todo lo de desarrolladores está en Configuración, en la sección Desarrollo: Webhooks, Claves API e Integraciones.
La idea es simple. Con la API REST tu sistema le habla a Omnifox: crea contactos, responde conversaciones, agenda citas. Con los webhooks es al revés: Omnifox le avisa a tu sistema cada vez que pasa algo, por ejemplo cuando entra un mensaje.
Y encima de eso hay atajos: los nodos para n8n, el servidor MCP para que una IA opere Omnifox, y los SDK para Node, Python y PHP. Todos usan la misma clave API.
2. Requisitos: plan y permisos
La API y los webhooks vienen en los planes Crece, Escala y Enterprise. Con un plan sin API, la API responde que tu plan no la incluye.
Para crear claves API hace falta poder gestionar la configuración del espacio, y los webhooks solo los crea un administrador. Cada clave queda atada a un espacio de trabajo.
3. Crear una clave API
Vamos a Claves API. Todavía no hay ninguna. Pulsamos Nueva clave API.
Le ponemos un nombre que diga para qué es, en este caso Tienda en línea, y elegimos el espacio de trabajo. La clave solo podrá trabajar en ese espacio, y por eso casi nunca vas a tener que escribir el número del espacio en tus llamadas.
Expira el es opcional: si lo dejas vacío, la clave no vence. Para un proveedor externo o una prueba, conviene ponerle fecha.
Y Token de servicio, o bot, es para integraciones: lo que envíes con esta clave no se asigna a tu usuario, no cambia tu estado en línea ni te manda notificaciones al celular. Lo marcamos.
4. Alcances: qué puede hacer la clave
Ahora los permisos, que se llaman alcances. Están agrupados por módulo: contactos, mensajes, canales, CRM, proyectos, calendario y webhooks, cada uno con leer y escribir.
Si no marcas ninguno, la clave tiene acceso completo. Lo recomendable es darle solo lo que necesita. Para nuestra tienda marcamos leer y escribir contactos, leer y enviar mensajes, CRM y calendario, y gestionar webhooks. A propósito no le damos canales.
Escribir incluye leer en el mismo módulo. Y Admin equivale a todos los alcances, así que úsalo con cuidado.
5. Copiar la clave una sola vez
Pulsamos Crear clave y Omnifox la muestra una única vez. Cópiala y guárdala en un lugar seguro, como el gestor de secretos de tu servidor: después no se puede volver a ver. En este video la clave aparece difuminada por seguridad.
Si la pierdes, no pasa nada: se regenera y la anterior deja de funcionar.
6. La lista de claves: editar, regenerar y eliminar
En la lista ves cada clave con su tipo, usuario o bot, el espacio, sus alcances, cuándo se usó por última vez y cuándo vence. Arriba puedes filtrar por tipo.
Con el lápiz cambias el nombre, los alcances o el vencimiento sin romper la integración. Regenerar crea un token nuevo con los mismos permisos, ideal si sospechas que se filtró. Y eliminar la revoca en el acto: cualquier sistema que la use deja de entrar.
7. La documentación de la API
La documentación completa está en omnifox.io barra docs. Arriba tienes accesos a los nodos de n8n, al servidor MCP y a los SDK.
Debajo está la referencia de cada endpoint, agrupada por módulo: contactos, conversaciones, mensajes, CRM, calendario, webhooks y mucho más. Cada uno muestra sus parámetros, un ejemplo de respuesta y los errores posibles.
Con Authorize pegas tu clave y puedes probar cualquier llamada desde la misma página. Y si usas Postman o un generador de código, descarga el archivo openapi punto json.
8. Tu primera llamada
Pasemos a la terminal. Guardamos la clave en una variable de entorno, así nunca queda escrita en los comandos ni en el código.
Toda llamada lleva la cabecera Authorization con la palabra Bearer y tu clave. Preguntamos quién soy: la API responde con tu usuario y tu plan.
Todas las respuestas tienen la misma forma: success, message y data. Fíjate también en las cabeceras de límite de uso: cuántas llamadas por minuto te da tu plan y cuántas te quedan.
9. Contactos por API
Creamos un contacto con un POST a contacts: nombre, teléfono, correo y ciudad. La respuesta trae su identificador.
Lo buscamos por nombre con contacts search, y lo actualizamos con un PUT, por ejemplo para agregarle la empresa. Para no duplicar clientes, también existe upsert, que crea o actualiza según el teléfono o el correo.
Y aquí está, en Contactos de Omnifox, con los datos que mandamos desde la terminal.
10. Alcances en acción: el error 403
¿Qué pasa si la clave intenta algo que no tiene permitido? A nuestra clave no le dimos canales. Pedimos la lista de canales y la API responde 403, con el alcance que falta: read channels.
Los errores siempre te dicen qué pasó: 401 si la clave no existe, venció o fue revocada; 403 si falta un alcance o tu plan no incluye esa función; 422 si un dato no es válido, con el campo y el motivo; y 429 si superas el límite de llamadas por minuto.
11. Conversaciones y mensajes por API
Ahora, lo más útil: responder a un cliente desde tu sistema. Gabriela escribió en el chat de la web preguntando si hacen envíos a Quito. Listamos las conversaciones abiertas y ahí está la suya.
Leemos sus mensajes, y respondemos con un POST a conversations, su número, barra messages. Omnifox lo envía por el mismo canal por el que escribió el cliente.
Y en la bandeja de Omnifox aparece la respuesta, enviada a Gabriela por el chat de la web. Antes de escribir por WhatsApp, consulta window status: te dice si la ventana de veinticuatro horas está abierta o si hace falta una plantilla.
12. CRM y calendario por API
La API llega a toda la plataforma. En el CRM, creamos una oportunidad para Gabriela en el embudo de ventas mayoristas, con su valor.
En el calendario pedimos los horarios libres de la cata de cafés y reservamos uno. La cita aparece en el calendario de Omnifox como si la hubieran agendado a mano, y se puede reprogramar o cancelar también por API.
Lo mismo vale para proyectos, catálogo, pedidos, reportes, equipos, etiquetas y difusiones: todo está en la documentación.
13. Paginación y límites
Las listas vienen por páginas. Con per page eliges cuántos elementos y con page qué página. La respuesta te dice el total y la última página.
Recorre las páginas hasta el final y no pidas de más: si llegas al límite por minuto, la API responde 429; espera unos segundos y reintenta. Los SDK hacen las dos cosas solos.
14. Webhooks: crear una suscripción
Ahora, los webhooks. En Configuración, Webhooks, pulsamos Nuevo webhook.
Le damos un nombre y la URL de tu servidor, que debe ser https. Para esta guía usamos un pequeño servidor receptor de pruebas que muestra en pantalla todo lo que le llega.
Elegimos los eventos: mensaje recibido, mensaje enviado, conversación creada y cerrada, contacto creado y actualizado, difusión completada y los de citas, desde agendada hasta atendida. Marcamos mensaje recibido y conversación creada.
15. Secreto de firma, reintentos y encabezados
El secreto de firma es la clave con la que Omnifox firma cada envío. Cópialo a tu servidor para comprobar que el aviso viene de verdad de Omnifox. Con Regenerar obtienes uno nuevo.
En la política de reintentos eliges la estrategia: exponencial, que es la recomendada y espera dos, cuatro, ocho, dieciséis segundos y así hasta cinco minutos; lineal, cada sesenta segundos; o sin reintentos. Y el máximo de reintentos.
El circuit breaker protege tu servidor: tras tantos fallos seguidos, Omnifox deja de enviar por un rato y luego prueba de nuevo. También puedes agregar encabezados propios, por ejemplo una clave de tu lado.
16. Entrega de prueba
Antes de guardar, Enviar prueba manda un evento test punto ping a tu URL y muestra la respuesta de tu servidor, el código y el tiempo. No cuenta para las métricas ni para el circuit breaker.
Guardamos el webhook y vamos al receptor: ahí está el ping, firmado y con la firma válida.
17. Un evento real
Ahora un evento de verdad. Un cliente nuevo escribe en el chat de la web de Café Montañero.
Al instante, el receptor recibe message punto received: el texto, el contacto, la conversación y el canal, todo en JSON. Y como la conversación es nueva, también llega conversation punto created.
Cada envío trae cabeceras: el evento, un identificador único de la entrega, para que no proceses dos veces lo mismo, el número de intento, la marca de tiempo y la firma.
18. Verificar la firma en tu servidor
Verificar la firma toma diez líneas. Unes la marca de tiempo, un punto y el cuerpo exacto que recibiste, calculas un HMAC SHA doscientos cincuenta y seis con tu secreto, y lo comparas con la cabecera, que empieza con sha256 igual.
Con el envío real, la firma coincide. Si alguien cambia una sola letra del cuerpo, ya no coincide y tu servidor debe rechazarlo. Rechaza también las marcas de tiempo de más de cinco minutos, para evitar repeticiones.
19. Historial de entregas
En la lista de webhooks ves cada suscripción con su estado y sus eventos. Al abrirla, arriba tienes la tasa de éxito de las últimas veinticuatro horas y siete días, el tiempo promedio y los fallos seguidos.
Debajo, el estado del circuit breaker y el historial de cada entrega: fecha, evento, estado, intentos y código HTTP, con filtros. Ver payload te muestra exactamente lo que se envió y lo que respondió tu servidor.
Si tu servidor estuvo caído, las entregas fallidas se reintentan solas; y si el circuito quedó abierto, puedes cerrarlo a mano cuando lo arregles.
20. La página de integraciones
En Integraciones están los conectores listos. n8n, Make, Zapier y Webhook personalizado funcionan con webhooks en los dos sentidos. Azur conecta la facturación electrónica de Ecuador, y Cal.com tus reservas.
Las que dicen Próximamente, como HubSpot, Shopify, Google Sheets, Zoom o DocuSign, todavía no se pueden conectar. Mientras tanto, casi todo eso se resuelve con la API, los webhooks y n8n.
21. Webhook personalizado: entrada y salida
Abrimos Webhook personalizado. Arriba está tu URL entrante: tu sistema le manda un POST con una acción, como crear un contacto, etiquetarlo o enviar un mensaje, firmado con el secreto de abajo.
Debajo va tu URL saliente y los eventos que quieres recibir. Al guardar, Omnifox crea la suscripción y empieza a enviarte esos eventos, firmados con el mismo secreto.
Probémoslo: desde la terminal mandamos la acción create contact, firmada. Omnifox responde que lo creó, y el contacto ya está en la lista.
22. n8n: instalar el nodo de Omnifox
n8n es una herramienta de automatización que puedes usar en su nube o instalar gratis en tu servidor. Aquí tenemos una instalación propia.
En Settings, Community nodes, pulsamos Install, escribimos n8n nodes omnifox, aceptamos el aviso y lo instalamos. Quedan dos nodos: Omnifox, con las acciones, y Omnifox Trigger, que escucha los eventos.
23. n8n: la credencial de Omnifox
Creamos la credencial Omnifox API y pegamos una clave API de Omnifox. Aquí usamos la que creamos, que es de tipo bot; lo ideal es una clave propia para cada integración.
La URL base es la de Omnifox, y el espacio de trabajo puedes dejarlo en cero: se toma de la clave. Al guardar, n8n prueba la conexión y nos dice que funciona.
24. n8n: responder solo cuando preguntan el precio
Este flujo tiene tres nodos. El primero, Omnifox Trigger, escucha el evento mensaje recibido. Al activarlo, crea por su cuenta la suscripción de webhook en Omnifox y verifica la firma de cada aviso.
El segundo, un If, revisa si el texto del mensaje contiene la palabra precio. Y el tercero, Omnifox, con el recurso mensaje y la operación enviar, responde en la misma conversación con la lista de precios.
Lo activamos. Y en Omnifox, en Webhooks, ya aparece la suscripción que creó n8n.
Y la prueba de fuego: un cliente pregunta por el precio en el chat de la web. En un par de segundos llega la respuesta automática, y en n8n queda registrada la ejecución, paso por paso.
25. n8n: todas las operaciones
El nodo de Omnifox tiene ciento cuarenta operaciones: conversaciones, contactos, mensajes, etiquetas, campañas, canales, equipos, agentes de IA, CRM, tableros, calendario, catálogo y pedidos. Las listas, como canales o etiquetas, se cargan solas desde tu cuenta.
Dos errores típicos: una clave de otro espacio de trabajo, que te devuelve datos vacíos o un 403, y la URL base con barra api al final, que no hace falta: el nodo la agrega.
26. MCP: que una IA opere Omnifox
MCP, el Model Context Protocol, es el estándar para que asistentes de IA como Claude, Cursor o ChatGPT usen herramientas. El servidor MCP de Omnifox les da setenta y dos herramientas: contactos, conversaciones, calendario, catálogo, pedidos, flujos, difusiones y más.
Se instala con npx, y solo necesita dos variables: tu clave API y la URL de la API. La IA solo puede hacer lo que permitan los alcances de esa clave.
27. Probar el servidor MCP con el Inspector
Para ver qué hace sin conectar todavía un asistente, usamos MCP Inspector, la herramienta oficial de prueba. Conectamos y listamos las herramientas, cada una con su descripción y sus parámetros.
Elegimos search contacts, buscamos Gabriela y la respuesta trae su ficha real. Ahora create contact, con un cliente nuevo: lo ejecutamos y queda creado en Omnifox, igual que si lo hiciera un asistente.
Para conectarlo a Claude Desktop o a Cursor, pegas este bloque en su configuración de MCP: el comando npx, el paquete y las dos variables. Y para un servidor remoto, el MCP también funciona por HTTP.
28. SDK oficiales: Node, Python y PHP
Si programas, los SDK te ahorran el trabajo: manejan la autenticación, la paginación, los reintentos y los errores. Con Node, instalas arroba omnifox barra sdk.
Este script crea un cliente con la clave, recorre los contactos de Loja y le pone la etiqueta Cliente mayorista a uno. Lo ejecutamos y listo.
En Python es igual, con pip install omnifox, y también tiene versión asíncrona. Y en PHP, con composer require omnifox barra sdk. Los tres tienen los mismos recursos y nombres.
29. Buenas prácticas de seguridad
Unas buenas prácticas: una clave por integración, con el mínimo de alcances y de tipo bot. Guárdala en variables de entorno, nunca en el código ni en el navegador. Ponle vencimiento si es temporal, y regenérala si alguien que la conocía se va.
En tus webhooks: verifica siempre la firma, responde rápido con un 200 y procesa después en una cola, y usa el identificador de entrega para no procesar dos veces el mismo evento.
30. Solución de problemas
¿Un 401? La clave está mal copiada, venció o se regeneró. ¿Un 403? Revisa los alcances de la clave y que tu plan incluya la API. ¿Datos vacíos? Probablemente la clave es de otro espacio de trabajo.
¿El webhook no llega? Mira el historial de entregas: si hay errores, el código HTTP te dice qué respondió tu servidor; si el circuito está abierto, ciérralo cuando lo arregles; y confirma que la URL sea https y pública.
Artículos relacionados
-
Cómo conectar integraciones y apps externas
Conecta Omnifox con tus herramientas favoritas desde el catálogo de integraciones en pocos pasos.
-
Integrar Omnifox con Azur, Siigo, Alegra, QuickBooks u otro sistema contable o ERP
Omnifox no tiene hoy un conector nativo con sistemas contables o ERP. Te explicamos cómo conectarlos igual con workflows, el nodo HTTP, n8n, Make, Zapier o la API, con ejemplos.
-
Generar y usar API keys y webhooks
Crea claves de API para acceder a Omnifox por código y configura webhooks para recibir eventos en tiempo real.
-
Introducción a las integraciones (webhook / OAuth / API key)
Conecta Omnifox con tus otras herramientas: qué está disponible hoy, qué llega pronto y cuándo usar un webhook, una conexión OAuth o una clave de API.
-
La API REST de Omnifox: introducción y requisitos de plan
Qué es la API REST de Omnifox, qué plan necesitas (desde Crece), cómo autenticar con la cabecera X-API-Key y dónde está la documentación.