# API y MCP de Survey


# 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](/img/screenshots/survey/integrations.png)
*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:

```bash
curl -X POST https://surveyapi.imatic.ai/forms/list \
  -H "Authorization: Bearer sk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

:::tip[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](#claves-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.

:::info[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

- [Publica y comparte un formulario](./publishing-sharing)
- [Visualiza las respuestas](./responses)
- [Abre la analítica](./analytics)
- [Genera un formulario con IA](./ai-generation)