Saltar al contenido principal

API y MCP de Survey

imatic Survey se conecta con el resto de tu stack — enviando respuestas a tus propios sistemas, automatizando el trabajo con formularios y dejando que los agentes de IA trabajen con tus formularios. Esta página cubre la superficie para desarrolladores: claves de API, webhooks, la API REST, el servidor MCP y la entrega de correo. Estas funciones están activas hoy.

El área de integraciones y ajustes para desarrolladores El área de desarrolladores es donde gestionas claves de API, webhooks e integraciones.

Claves de API​

Las claves de API autentican tus propias apps y scripts contra la API REST de Survey. Créalas y gestiónalas en /developers/api-keys, donde puedes emitir una clave, darle un nombre, ver sus estadísticas de uso y revocarla si alguna vez se expone.

Una clave se muestra completa solo una vez, al crearla — cópiala entonces y guárdala en un lugar seguro. Después de eso solo verás su prefijo en la lista, junto a su nombre, ámbitos y hora de último uso.

La API está alojada en https://surveyapi.imatic.ai, y las claves llevan el prefijo sk_. Envía tu clave como token Bearer. Los endpoints son solicitudes POST con verbos personalizados — por ejemplo, para listar tus formularios:

curl -X POST https://surveyapi.imatic.ai/forms/list \
  -H "Authorization: Bearer sk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Mantén las claves en secreto

Trata una clave de API como una contraseña. No la confirmes en el control de versiones, y rótala si sospechas que se ha filtrado.

Webhooks​

Los webhooks envían eventos a una URL que controlas, para que tus sistemas reaccionen en el momento en que algo ocurre en lugar de hacer sondeo en busca de cambios. Configúralos en /developers/webhooks.

Eventos disponibles:

  • response.created — se dispara cuando se envía una nueva respuesta.
  • response.flagged (previsto — aún no se emite) — se disparará cuando se marque una respuesta (por ejemplo, por comprobaciones de fraude o spam).
  • response.updated (previsto — aún no se emite) — se disparará cuando se actualice o modere una respuesta.
  • form.published (previsto — aún no se emite) — se disparará cuando se publique un formulario.
  • form.closed (previsto — aún no se emite) — se disparará cuando se cierre un formulario.

Cada entrega está firmada con una firma HMAC-SHA256 (enviada en el encabezado X-Signature, junto a X-Timestamp, X-Event-Id y X-Event-Type) para que tu endpoint pueda verificar que la solicitud realmente provino de imatic Survey y no fue manipulada en tránsito. Las entregas fallidas se reintentan con retroceso exponencial antes de marcarse como fallidas.

API REST​

La API REST te permite gestionar formularios y respuestas mediante programación. Los endpoints usan solicitudes POST con verbos personalizados en lugar de un prefijo de ruta versionado — por ejemplo, POST /forms/list (listar formularios), POST /forms/get-for-edit (leer el esquema de un formulario), POST /forms/generate (generar un formulario con IA), POST /forms/duplicate y POST /forms/delete. Está alojada en https://surveyapi.imatic.ai y se autentica con una clave de API — un token Bearer con prefijo sk_.

Servidor MCP para agentes de IA​

El servidor MCP expone Survey a los agentes de IA mediante el Model Context Protocol, para que un asistente pueda trabajar con tus formularios y respuestas en tu nombre. Habla JSON-RPC 2.0 sobre POST /mcp y se autentica con tu JWT del portal (enviado como token Bearer), que limita cada llamada a tu organización.

Viene con 10 herramientas:

  • whoami — devuelve el contexto de la organización autenticada.
  • list_forms — lista tus formularios publicados.
  • get_form — lee el esquema y los campos de un formulario.
  • submit_response — envía una respuesta a un formulario.
  • list_responses — lista respuestas (paginadas).
  • get_response — lee una sola respuesta.
  • get_response_stats — lee estadísticas agregadas de respuesta.
  • create_poll — crea y publica una votación de una sola pregunta.
  • cast_vote — emite un voto en una votación.
  • live_poll_results — lee los recuentos de votación en vivo.
Dos credenciales diferentes

El servidor MCP y los webhooks usan tu JWT del portal (limitado a la org). La API REST usa una clave de API que creas en /developers/api-keys. Elige la credencial correcta para la superficie que estás llamando.

Entrega de correo​

La entrega de correo (por ejemplo, las notificaciones de respuesta) se configura en /settings en la pestaña de entrega de correo. Puedes conectar cualquiera de seis proveedores:

  • Gmail
  • Resend
  • SendGrid
  • Postmark
  • Amazon SES
  • SMTP personalizado

Próximos pasos​