Saltar al contenido principal

Apps de Zapier, Make y n8n

Una app por plataforma sobre la API pública y las suscripciones REST hook (/api/v1/hooks/subscriptions, webhooks). Código y pruebas: integrations/zapier (definición para Zapier Platform CLI, JavaScript simple, sin dependencias en ejecución), integrations/make (definición declarativa de la app app.json y un ejecutor de pruebas), integrations/n8n (paquete de nodo de la comunidad, TypeScript). make automation-apps-test ejecuta las tres suites (Node >= 22.18 o Docker node:lts). Las pruebas corren contra una API de PBX simulada (test/fake-pbx.js: autenticación Bearer, suscripciones, llamada con un clic, SMS, contactos, notas de llamada); nada llama a una plataforma ni a una PBX reales.

Conexión​

El cliente captura la dirección de la PBX y una llave de API (Consola > Admin > Llaves de API), enviada como Authorization: Bearer <key>. Dé a la llave integrations:write (suscripciones) más lo que usen los disparadores y acciones: el permiso de evento de cada disparador (vea "Quién recibe qué" en webhooks; una suscripción a un evento que la llave no puede recibir se rechaza con 400), self:read para la llamada con un clic, el envío de SMS y los contactos. El aislamiento entre tenants lo hace la API: una llave ve y cambia solo su propia empresa.

Disparadores (instantáneos, REST hook)​

DisparadorEventoNotas
Llamada iniciada / terminadacall.started, call.ended
Nuevo mensaje de vozvoicemail.message_left
SMS recibidosms.received
Nuevo mensaje de chatchat.message_created
Resumen de IA de la llamada listocall.summary_readydetail.summary trae el texto (campo solo de webhook)
Resumen de IA del buzón de voz listovoicemail.summary_ready

Activar un Zap/escenario/flujo llama a POST /api/v1/hooks/subscriptions ({target_url, event, source: "zapier"|"make"|"n8n"}); desactivarlo llama a DELETE /api/v1/hooks/subscriptions/{id} con el id que guardó la plataforma. La respuesta de la suscripción trae el secret de firma una sola vez. Cada entrega es el sobre del evento {id, type, occurred_at, data}: Zapier aplana data junto a id/type/occurred_at (id elimina duplicados); Make expone body.data; n8n emite el objeto aplanado y verifica la firma Standard Webhooks (webhook-id, -timestamp, -signature, ventana de 5 minutos, segura ante rotación) con el secreto que guardó. Zapier y Make no pueden verificar firmas; sus URL de destino son direcciones https imposibles de adivinar y la protección de salida de la PBX aplica como en todo webhook.

Acciones​

AcciónAPIEntrada
Originar llamadaPOST /api/v1/calls/click-to-calldestino, id de dispositivo opcional. Suena el dispositivo del dueño de la llave y luego marca como ese usuario (aplican el plan de marcación, los permisos y los límites contra fraude; los números de emergencia se rechazan).
Enviar SMSPOST /api/v1/sms/messagesde (un número SMS de la empresa), para, texto. Lleva un Idempotency-Key de la ejecución, así que un reintento de la plataforma envía un solo mensaje.
Crear contactoPOST /api/v1/me/contactsteléfono, nombres, empresa, correo, notas (los contactos personales del dueño de la llave).
Agregar nota de llamadaPUT /api/v1/cdr/{call_id}/noteid de llamada, texto, private o team.

Los campos opcionales vacíos se omiten de la solicitud. Un problema de la PBX (application/problem+json) se muestra con su detail y code, por ejemplo MPBX-CONTACT-NUMBER-TAKEN.

Ejemplos (resumen de IA de la llamada a nota de equipo)​

Cada uno es la misma automatización de dos pasos, y una prueba comprueba que nombra disparadores, módulos y campos reales:

  • Zapier: integrations/zapier/samples/zapier-call-summary-to-note.zap.json
  • Make: integrations/make/samples/make-call-summary-to-note.scenario.json
  • n8n: integrations/n8n/samples/n8n-call-summary-to-note.workflow.json

Listas de revisión (qué pide cada plataforma y dónde se cumple)​

Publicar y pasar la revisión es trabajo del propietario.

Zapier (revisión de integración pública). Autenticación con prueba de conexión: authentication.test llama a GET /me. Cada disparador es un REST hook con performSubscribe, performUnsubscribe, perform y una muestra performList: src/triggers.js, probado en los 7. Cada acción tiene campos de entrada con etiqueta y un sample: src/actions.js. Los mensajes de error son legibles: afterResponse en src/client.js. Sin acciones duplicadas al reintentar: Idempotency-Key en SMS. Los disparadores eliminan duplicados por id. Máximo una app por caso de uso, sin datos de prueba en la app, sin URL base fija (la captura el cliente). Pendiente del lado de Zapier: zapier validate, el zapier push, el formulario de revisión, un logotipo público y un contacto de soporte.

Make (app personalizada / revisión de Make Apps). Conexión con solicitud de prueba, un webhook por evento con attach y detach, módulos de disparador instantáneo, módulos de acción con parámetros tipados, plantilla de error legible, cuerpos con omitEmpty: integrations/make/app.json, ejecutado por test/runner.js. Pendiente en Make: importar la definición al editor de apps personalizadas (los componentes se crean con los mismos bloques), agregar descripciones de módulos e íconos, y enviar a revisión.

n8n (verificación de nodo de la comunidad). Palabra clave del paquete n8n-community-node-package, bloque n8n en package.json, credencial con solicitud de prueba, un nodo disparador con los métodos de webhook checkExists/create/delete y verificación de firma, un nodo de acción con cuatro operaciones, compatibilidad con continueOnFail. Las formas de la API de nodos se declaran localmente (lib/types.ts) porque n8n-workflow no tiene una licencia permitida para nuestros productos; el propietario decide si se compila contra él. Pendiente: npm run build, npm publish --provenance, la solicitud de verificación, un ícono monopbx.svg.

Límites​

Estas apps no tienen OAuth (una llave de API por conexión); OAuth 2.0 con las pantallas de consentimiento de Zapier/Make/n8n está planeado. Las acciones actúan como el dueño de la llave de API. No hay sondeo de respaldo: una plataforma que no pueda recibir webhooks no puede usar los disparadores.