Funciones

Ideal para: Dueños de negocio que necesitan integrar su sitio con servicios externos y programadores que requieren endpoints seguros.

1. ¿Qué son las funciones?

Las funciones permiten que cada cuenta exponga endpoints HTTP propios, hospedados dentro de la plataforma. Se comportan como “serverless functions” pero sin salir del ecosistema MGPanel.

• Si diriges el negocio: puedes delegar integraciones sin tocar el frontend y sin problemas de CORS.
• Si programas: obtienes un backend ligero para consumir APIs, enviar correos o procesar datos de tus sitios MGPanel.

2. Dónde encuentro el módulo

1. Ingresa al panel y ve a Sitio Web → Funciones (/functions).
2. Verás un tablero con todas las funciones de la cuenta y su estado.
3. Desde allí puedes crear nuevas funciones, editarlas, eliminarlas o revisar la última ejecución.

3. Crear o editar una función (paso a paso)

3.1 Accede al formulario

1. Pulsa “Nueva función” para crearla, o Editar en la función que quieras actualizar.
2. Se abrirá un formulario con pestañas “General”, “Configuración” y “Tokens”.

3.2 Completa la pestaña “General”

• Nombre público: cómo la reconocerás en el panel.
• Endpoint: un Único segmento de ruta (sin barras) que se agrega después de /api/functions/<tu-cuenta>/. Usa minúsculas y guiones — ej. contacto o consulta-clima. ⚠️ No pegues aquí la URL completa ni uses barras /: la invocación pública solo reconoce un segmento, así que un endpoint como consulta/clima o /api/functions/tu-cuenta/contacto quedaría inalcanzable aunque la función se guarde y se muestre “Activa”.
• Estado: “Activa” para habilitarla o “Inactiva” para pausarla sin borrarla.
• Handler: elige el tipo de lógica que ejecutará la función (eco, proxy-rest, email-ses).
• Descripción: texto breve que explique para qué sirve.

3.3 Handler proxy-rest

Reenvía la solicitud a un servicio externo inyectando credenciales del lado del servidor. Las API keys y tokens nunca viajan al navegador del cliente.

{
  "method": "GET",
  "baseUrl": "https://api.ejemplo.com/v1",
  "path": "endpoint",
  "headers": {
    "x-api-key": "TU_API_KEY"
  },
  "defaultParams": {
    "lang": "es"
  },
  "allowedClientQuery": ["lang", "city", "units"],
  "forceJson": true,
  "timeoutMs": 15000,
  "exposeHeaders": ["x-ratelimit-remaining"],
  "responseMessage": "Solicitud completada.",
  "dataKey": null,
  "includeFullResponse": false
}

Campo por campo:

• method: GET, POST, PUT, etc.
• baseUrl: URL del servicio externo sin barra final.
• path: recurso dentro del servicio sin barra inicial. El handler combina ambos para construir la URL destino.
• headers: pares clave/valor para autenticación o content-type. Se inyectan server-side; nunca llegan al navegador del cliente.
• defaultParams: query string que enviarás siempre, salvo que el cliente lo sobrescriba.
• allowedClientQuery: lista blanca de parámetros que tu sitio puede añadir dinámicamente.
• forceJson: si está en true, el handler envía el cuerpo como JSON cuando el método lo permita (defecto: true).
• timeoutMs: milisegundos antes de cancelar la llamada (defecto: 15 000).
• exposeHeaders: cabeceras de la respuesta del servicio externo que quieres devolver al cliente.
• responseMessage: (opcional) texto personalizado en el campo message de la respuesta.
• dataKey: (opcional) si la respuesta es un objeto y solo necesitas un campo específico, pon aquí su nombre (ej. "data") — el handler extraerá solo ese valor.
• includeFullResponse: (opcional) si true, incluye el JSON original en el campo raw de la respuesta.

3.3.a Rutas dinámicas (path params)

Desde esta actualización, path admite segmentos dinámicos con la sintaxis {nombre} — por ejemplo api/invoices/{invoice_id}/status. Un placeholder solo se sustituye si su nombre está declarado en allowedClientPath; opcionalmente puedes validar el formato del valor recibido con una expresión regular en pathParamPattern. Esto es lo que permite, por ejemplo, verificar el estado de una factura al volver del checkout sin poner tu API key en el navegador.

{
  "method": "GET",
  "baseUrl": "https://app.mgpanel.co",
  "path": "api/invoices/{invoice_id}/status",
  "allowedClientPath": ["invoice_id"],
  "pathParamPattern": {
    "invoice_id": "^[a-f0-9]{24}$"
  },
  "headers": {
    "Authorization": "Bearer TU_API_KEY",
    "X-Account-Nick": "tu-cuenta"
  }
}

Campo por campo:

• allowedClientPath: lista blanca de nombres de placeholder que el cliente puede rellenar (los que no estén aquí se rechazan, aunque aparezcan en path).
• pathParamPattern: (opcional) expresión regular por nombre de placeholder para validar el valor recibido antes de usarlo en la URL — por ejemplo, exigir que invoice_id sea un ObjectId de 24 caracteres hexadecimales.
• El valor se envía como un parámetro más del payload del cliente (query en GET, body en POST); si además está en allowedClientQuery, solo viaja como path param — no se duplica en la query.

Invocación: GET /api/functions/mi-cuenta/estado-factura?invoice_id=507f1f77bcf86cd799439011&token=TOKEN_PUBLICO

⚠️ Nota de seguridad: una función así responde a cualquiera que conozca (o adivine) un invoice_id válido de tu cuenta. Protege siempre el endpoint con un token de invocación (pestaña “Tokens”) y usa pathParamPattern para rechazar valores con formato inválido antes de reenviarlos.

3.3.b Handler email-ses

Envía correos electrónicos usando AWS SES desde el servidor. El remitente (from) siempre es fijo — nunca puede ser modificado por quien invoca la función. Las credenciales de SES viven en el servidor.

{
  "from": "\"Contacto\" <[email protected]>",
  "to": "[email protected]",
  "subject": "Nuevo mensaje desde la web",
  "html": "<p>Tienes un nuevo mensaje de contacto.</p>",
  "text": "Tienes un nuevo mensaje de contacto.",
  "replyTo": "[email protected]",
  "allowedClientFields": ["subject", "html", "text"],
  "responseMessage": "¡Gracias! Tu mensaje fue enviado."
}

Campo por campo:

• from: ✓ Requerido. Identidad SES verificada en la cuenta. Nunca modificable por el cliente.
• to: Destinatario(s) por defecto. Puede ser string o array.
• subject: Asunto del correo.
• html: Cuerpo HTML del correo.
• text: Cuerpo en texto plano (complemento o alternativa al HTML).
• replyTo: Dirección(es) de respuesta.
• allowedClientFields: Campos que el cliente puede sobrescribir desde el payload (to, subject, html, text). El campo from nunca puede incluirse.
• responseMessage: (opcional) Texto personalizado en el campo message de la respuesta.

Invocación desde el frontend:

fetch('https://dev.mgpanel.co/api/functions/mi-cuenta/contacto', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-MGPANEL-FUNCTIONS-KEY': 'TOKEN_PUBLICO'
  },
  body: JSON.stringify({
    subject: 'Consulta de Juan García',
    html: '<p>Hola, quisiera información sobre sus servicios.</p>'
  })
})

3.4 Tokens (opcional)

Registra tokens manuales (uno por línea) en la pestaña “Tokens”. La función solo responde si el cliente envía X-MGPANEL-FUNCTIONS-KEY con alguno de esos valores. Soporta validación por valor directo o HMAC.

3.5 Guarda y prueba

1. Haz clic en Guardar.
2. MGPanel crea o actualiza la función al instante, sin reiniciar servidores.
3. Usa Eliminar si ya no la necesitas.

4. Invocar la función desde tu sitio

1. Realiza un fetch a https://<tu-panel>/api/functions/<cuenta>/<endpoint>.
2. Envía el token en la cabecera X-MGPANEL-FUNCTIONS-KEY.
3. Añade parámetros en la URL (?lang=es&city=Panama) solo si están en allowedClientQuery.

fetch('https://app.mgpanel.co/api/functions/mi-cuenta/consulta-clima?city=Panama', {
  headers: { 'X-MGPANEL-FUNCTIONS-KEY': 'TOKEN_SEGURO_123' }
})
  .then(respuesta => respuesta.json())
  .then(datos => console.log(datos))
  .catch(console.error);

5. Ejemplos listos para usar

5.1 Consumir una API externa (proxy-rest)

• Cuándo usarlo: consumir una API de terceros (catálogos, subastas, precios…) sin exponer tu API key en el navegador.

{
  "method": "GET",
  "baseUrl": "https://api.ejemplo.com",
  "path": "cars",
  "headers": {
    "Authorization": "Bearer TU_API_KEY"
  },
  "allowedClientQuery": ["make", "model", "page", "size"]
}

• Reemplaza solo: Authorization por la credencial de tu proveedor (algunos usan x-api-key).
• Invocación: GET /api/functions/mi-cuenta/api-externa?make=Toyota&model=Camry

5.2 Crear una factura en tu CRM (proxy-rest)

• Cuándo usarlo: que tu sitio cree facturas (u otros recursos de tu cuenta) sin revelar tu API key.

{
  "method": "POST",
  "baseUrl": "https://app.mgpanel.co",
  "path": "api/invoices",
  "headers": {
    "Authorization": "Bearer TU_API_KEY",
    "X-Account-Nick": "tu-cuenta",
    "Content-Type": "application/json"
  }
}

• Reemplaza solo: Authorization (tu API key de Configuración → API Keys) y X-Account-Nick (el nick de tu cuenta).
• Invocación: POST /api/functions/mi-cuenta/api-mgpanel con body JSON { client: { name, email }, items: [{ description, quantity, price }] }.

Caso de uso: verificar el pago al volver del checkout

• Cuándo usarlo: tu sitio redirige al cliente de vuelta desde una pasarela de pago y necesitas confirmar, del lado del navegador, si la factura ya quedó pagada — sin exponer tu API key.

{
  "method": "GET",
  "baseUrl": "https://app.mgpanel.co",
  "path": "api/invoices/{invoice_id}/status",
  "allowedClientPath": ["invoice_id"],
  "pathParamPattern": { "invoice_id": "^[a-f0-9]{24}$" },
  "headers": {
    "Authorization": "Bearer TU_API_KEY",
    "X-Account-Nick": "tu-cuenta"
  }
}

fetch(`https://app.mgpanel.co/api/functions/mi-cuenta/estado-factura?invoice_id=${invoiceId}&token=TOKEN_PUBLICO`)
  .then(r => r.json())
  .then(({ data }) => {
    if (data.status === 'paid') mostrarConfirmacion();
  });

• Reemplaza solo: Authorization y X-Account-Nick con tus credenciales; invoiceId viene del checkout (por ejemplo, del parámetro que la pasarela devuelve en la URL de retorno).

5.3 Enviar un correo (email-ses)

• Cuándo usarlo: enviar correos desde el sitio sin exponer credenciales de AWS SES.

{
  "from": "\"Web\" <[email protected]>",
  "to": "[email protected]",
  "subject": "Nuevo contacto desde el sitio",
  "allowedClientFields": ["subject", "html"]
}

• Invocación: POST /api/functions/mi-cuenta/contacto con body JSON { subject, html } y header X-MGPANEL-FUNCTIONS-KEY.

5.4 Ejemplo completo: los 3 tipos en una página

Este ejemplo asume que ya creaste las tres funciones de 5.1–5.3 (cada una con su propio endpoint). El navegador solo envía el token público X-MGPANEL-FUNCTIONS-KEY. Las credenciales reales (Authorization y X-Account-Nick) viven en la configuración de cada función, del lado del servidor

<script>
const PANEL  = 'https://app.mgpanel.co';
const CUENTA = 'mi-cuenta';
const TOKEN  = 'TOKEN_PUBLICO'; // el valor que registraste en la pestaña "Tokens" (ver 3.4)

// fn(ep) arma la URL de invocación: PANEL/api/functions/CUENTA/ep
// "ep" es el endpoint que definiste en la pestaña "General" de esa función (ver 3.2)
const fn   = ep => `${PANEL}/api/functions/${CUENTA}/${ep}`;
const auth = { 'X-MGPANEL-FUNCTIONS-KEY': TOKEN };

// 1) Enviar correo — función con endpoint "contacto" y handler email-ses (ver 5.3)
async function enviarCorreo() {
  const r = await fetch(fn('contacto'), {
    method: 'POST',
    headers: { ...auth, 'Content-Type': 'application/json' },
    body: JSON.stringify({ subject: 'Hola', html: '<p>Mensaje de prueba</p>' })
  });
  return r.json();
}

// 2) Crear una factura en tu CRM — función con endpoint "api-mgpanel" y handler proxy-rest hacia POST /api/invoices (ver 5.2)
async function crearFactura() {
  const r = await fetch(fn('api-mgpanel'), {
    method: 'POST',
    headers: { ...auth, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      client: { name: 'Juan García', email: '[email protected]' },
      items: [{ description: 'Servicio de consultoría', quantity: 1, price: 100 }]
    })
  });
  return r.json();
}

// 3) API externa — función con endpoint "api-externa" y handler proxy-rest (ver 5.1)
async function buscarAutos(make, model) {
  const r = await fetch(`${fn('api-externa')}?make=${make}&model=${model}&size=5`, { headers: auth });
  return r.json();
}
</script>

• Para usarlo: ajusta PANEL, CUENTA y TOKEN; cada función responde solo si el token coincide con alguno de los registrados en la pestaña “Tokens”.
• Los nombres contacto, api-mgpanel y api-externa dentro de fn('...') son los endpoints de las tres funciones ya creadas en 5.1–5.3 — sustitúyelos por los que tú hayas definido para las tuyas.

6. Seguridad y monitoreo

• Tokens y cabeceras: compártelos solo por canales seguros.
• Logs automáticos: cada ejecución registra métricas en mg_logs; los errores aparecen en systemlog.
• CORS dinámico: si usarás la función desde un dominio nuevo, agrégalo en la configuración de la cuenta.
• Hosts permitidos: el handler proxy-rest rechaza direcciones IP privadas o de red interna (127.0.0.1, 10.x, 192.168.x, 169.254.x…) tanto al guardar baseUrl como al ejecutar la función, para evitar que se use como puente hacia servicios internos.
• Automatización con IA (MCP): puedes listar, crear, editar, ejecutar y revisar logs de tus funciones desde un agente conectado por MCP — asigna el scope functions a la API Key en Configuración → API Keys. Las credenciales (headers y tokens) siempre viajan enmascaradas como *** hacia el agente.

7. Buenas prácticas

1. Empieza con “eco”: valida tu token y endpoint antes de usar proxy-rest o email-ses.
2. Documenta parámetros: anota qué query strings o campos acepta cada función.
3. Controla tiempos: ajusta timeoutMs; evita llamadas superiores a 15 segundos.
4. Revisa logs periódicamente: detecta errores tempranos y ajusta cabeceras o parámetros.
5. Rota tokens sensibles: trátalos como cualquier credencial crítica.

8. Ayuda y soporte

• Pregunta a Emyi dentro del panel para obtener guías rápidas o respuestas a preguntas frecuentes.
• Si necesitas soporte avanzado, escribe a [email protected] o abre un ticket desde el mismo panel.

📌 Resumen express:

1. Entra a Sitio Web → Funciones.
2. Elige el handler: proxy-rest (APIs externas), email-ses (correo) o eco (pruebas).
3. Completa el JSON con las claves correctas (method, baseUrl, path, headers para proxy-rest; from, to, allowedClientFields para email-ses).
4. Guarda y prueba con tu token.
5. Consúmela desde tu sitio con fetch o cualquier cliente HTTP.