Endpoints
Los endpoints son las URLs específicas donde tu frontend envía peticiones para realizar acciones o recuperar datos.
Tipos de Petición
HeroMate soporta todos los métodos HTTP estándar para gestionar diferentes tipos de operaciones:
- GET (Lectura): Se usa para recuperar datos de tu base de datos (ej. listar productos u obtener el perfil de un usuario).
- POST (Creación/Acción): Se usa para guardar nueva información o disparar un proceso (ej. crear un pedido o iniciar una tarea de IA).
- PATCH/PUT (Actualización): Se usa para modificar registros existentes (ej. cambiar el estado de un usuario).
- DELETE (Eliminación): Se usa para borrar información de forma segura.
Gestión de Endpoints
En la sección de Constructor de API, puedes ver una lista de todos tus endpoints. Desde aquí, puedes:
Editar con el Canvas
Haz clic en cualquier endpoint para abrir el Canvas Visual. Aquí es donde puedes:
- Revisar el flujo de la lógica.
- Modificar nodos existentes o añadir nuevos.
- Cambiar la estructura de entrada y salida.
Probar en Tiempo Real
Usa el panel de Pruebas para verificar que tu endpoint funciona como esperas. Puedes simular diferentes escenarios y ver exactamente qué devuelve la API.
Start, Triggers y Webhooks
Cada endpoint en HeroMate empieza desde un unico nodo Start. Ese nodo Start define como se activa el workflow.
Tipos de Trigger Disponibles
| Trigger | Mejor para | Que ocurre |
|---|---|---|
HTTP API | Peticiones desde frontend o backend | HeroMate expone un endpoint API normal que tu app puede llamar directamente |
Webhook | Servicios externos como Stripe, GitHub o pasarelas de pago | HeroMate expone una URL de webhook que terceros pueden llamar |
Schedule | Tareas recurrentes y automatizaciones | HeroMate ejecuta el workflow automaticamente segun una regla de tiempo |
Telegram | Workflows activados por bots | HeroMate inicia el workflow cuando tu bot de Telegram recibe un mensaje |
Twilio | SMS / WhatsApp / voz vía Twilio | HeroMate inicia el workflow cuando Twilio entrega un mensaje entrante o un callback de estado |
Cuando Usar un Webhook
Usa un Webhook cuando un servicio externo necesite notificar un evento a tu proyecto.
Ejemplos comunes:
- Pago exitoso en Stripe
- Evento de push en GitHub
- Envio de formulario desde una herramienta externa
- Callback de estado de entrega desde un proveedor de mensajeria
A diferencia de un endpoint HTTP API normal, un webhook esta pensado para ser llamado por otra plataforma, no por tu propia interfaz frontend.
Cómo Funcionan los Webhooks en HeroMate
Cuando configuras el nodo Start como webhook:
- HeroMate expone una URL de webhook única para ese endpoint
- el workflow se inicia automáticamente cuando esa URL recibe una petición
- puedes proteger el webhook con el método de autenticación configurado (secreto del sistema, token en cabecera, HMAC o auth básica)
- puedes revisar el estado del webhook y sus ejecuciones recientes desde el detalle del endpoint
Esto facilita conectar workflows de HeroMate con sistemas de eventos de terceros sin tener que construir un backend receptor aparte.
Modos de Autenticación HTTP API
Al usar el trigger HTTP API, debes seleccionar un Modo de Autenticación:
jwt: El endpoint requiere una sesión de usuario válida. Puedes restringir el acceso aún más usando Roles Permitidos.api_key: El endpoint requiere la API Key del proyecto en la cabeceraX-API-KEY. Esto salta las verificaciones de roles y es ideal para comunicación servidor a servidor.
No se soportan endpoints públicos (sin autenticación). Cada petición debe estar identificada ya sea por un usuario o por la clave del proyecto.
Para la mayoria de pantallas y acciones de usuario, usa HTTP API. Usa Webhook cuando el llamador sea un sistema externo como Stripe, GitHub u otro backend.
Construyendo con IA
Recuerda que no tienes que construir todo esto manualmente. Puedes usar MCP para gestionar tus endpoints usando lenguaje natural:
- "Lista todos mis endpoints actuales."
- "Explícame la lógica del endpoint 'procesar-pago'."
- "Actualiza el endpoint 'obtener-usuario' para que también devuelva el rol del usuario."
Contrato de Placeholders (workflow_code)
Para evitar ambiguedades, usa un formato unico en los workflows:
${input.campo}: datos de entrada del endpoint${vars.<variable>.campo}: salida de un nodo previo por su aliasvariable(recomendado)${nodes.<node_id>.campo}: salida de un nodo previo por suidtecnico (tambien soportado)${current_user.campo}y${current_user_id}: contexto de usuario autenticado
No uses placeholders planos como ${name}, ${email}, ${id}.
El validador del engine rechaza placeholders ambiguos. Si el workflow no cumple este contrato, fallara en validacion antes de ejecutarse.
Preflight antes de crear/actualizar workflows con MCP
Antes de generar un workflow_code con IA:
- Usa
list_node_catalogpara descubrir los nodos disponibles. - Si necesitas detalle tecnico, llama a
list_node_catalogpara el nodo concreto. - Construye el workflow solo con
node_typeexistentes. - Ejecuta validacion de workflow antes de guardar.
Credenciales en nodos de integracion
Para nodos que requieren proveedores externos (IA, mensajeria, email, sheets, pagos), incluye credential_id dentro de parameters. HeroMate incluye 26 tipos de credenciales tipadas repartidas entre ~24 proveedores (Stripe, Telegram, WhatsApp, Slack, Notion, Google Sheets, GitHub y más) — consulta Credenciales para la lista completa.
Recomendado:
credential_id: "${input.<provider>_credential_id}"
No hardcodees secretos dentro del JSON del workflow.
El nodo javascript_code funciona distinto: no usa el selector de credenciales tipadas. Lee las env_vars en texto plano que defines en el nodo como ctx.env.X. No pongas secretos reales ahí — usa una Credencial tipada en un nodo de integración, o guarda secretos de runtime como Backend Secrets (ctx.secrets.X).
Regla de datos para inserts
En el nodo dypai_database con operation = insert:
input_mode: "explicit"(recomendado): requieredatacon columnas definidas.input_mode: "passthrough": sidataesta vacio, usa el body de entrada del endpoint.
Esto permite un flujo rapido de prototipado sin perder control en produccion.
Custom Query (SQL)
En el nodo dypai_database con operation = custom_query, el campo query usa la misma sintaxis oficial que el resto del workflow:
- Formato:
${variable} - Variables disponibles:
${input.campo},${params.campo},${current_user_id},${record_id},${limit},${offset} - Sin comillas: No envuelvas placeholders en comillas. El engine los convierte en bind params seguros ($1, $2...).
Incorrecto: WHERE user_id = '${current_user_id}' — las comillas fuerzan un literal y rompen los bind params (y puedes tener errores de tipo).
Correcto (propiedad por usuario): WHERE user_id = ${current_user_id} sin comillas ni ::uuid. En HeroMate el JWT sub es TEXT; las columnas user_id deben ser TEXT. Reserva ::uuid solo para placeholders que correspondan a columnas UUID (por ejemplo WHERE id = ${input.id}::uuid), no para current_user_id.