> For the complete documentation index, see [llms.txt](https://boundaryai.gitbook.io/boundaryai-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://boundaryai.gitbook.io/boundaryai-docs/boundaryai-docs-es/api-y-webhooks/getting-started.md). # Primeros pasos con la API Envíe su primer comentario a través de la API en cinco minutos. La API de BAI Analytics hace bien una sola cosa: mueve feedback entre tus sistemas y tus grupos de feedback. Envías el feedback, la plataforma lo analiza exactamente como si hubiera llegado mediante una encuesta o una carga, y lees los resultados de vuelta (o dejas que un webhook te avise cuando estén listos). Todo funciona sobre HTTPS contra el host público de ingesta: ``` https://boundaryai-ingest-279197672085.europe-west9.run.app ``` {% hint style="warning" %} Usa este host, no la dirección del panel. El host del panel (`app.*`) sirve la aplicación web y responde a cada `/api/...` ruta con una página HTML y HTTP 200, que un cliente generado interpretará felizmente como un cuerpo de éxito. La referencia de API publicada lleva el mismo host en cada operación. {% endhint %} Este recorrido va desde cero hasta feedback analizado. Usa la terminología recomendada (`grupo_de_feedback` / `fuente` / `campo`); consulta [Conceptos y nomenclatura](/boundaryai-docs/boundaryai-docs-es/api-y-webhooks/concepts-and-naming.md) para ver cómo eso se corresponde con lo que ves en la app. *** ### Paso 1: Crea una clave de API En el panel, abre **Integraciones**, ve a **Herramientas de desarrollo → Claves de API** (solo administradores), y crea una clave. Elige un ámbito de permiso y copia el secreto: tiene este aspecto `inpk_live_...` y se muestra una sola vez. Pásalo en cada llamada: ``` Authorization: Bearer inpk_live_... ``` Verifica que funciona: ```bash curl https://boundaryai-ingest-279197672085.europe-west9.run.app/api/input/me \\ -H "Authorization: Bearer $BAI_API_KEY" ``` `GET /me` devuelve los permisos de tu clave, la organización a la que pertenece (`org_name`), tus límites de velocidad efectivos, el estado de uso de la organización y los eventos de webhook a los que puedes suscribirte. Detalles en [Autenticación y claves de API](/boundaryai-docs/boundaryai-docs-es/api-y-webhooks/authentication.md). ### Paso 2: Crea un grupo de feedback y una fuente Un **grupo de feedback** es el contenedor del proyecto; una **fuente** es un flujo de feedback dentro de él, con **campos**. Crear un grupo de feedback necesita una clave `all` ; crear y publicar fuentes necesita `create` o `all`. Si tu grupo ya existe, omite la primera llamada y usa su id. ```bash curl -X POST https://boundaryai-ingest-279197672085.europe-west9.run.app/api/input/feedback_groups/create \\ -H "Authorization: Bearer $BAI_API_KEY" -H "Content-Type: application/json" \\ -d '{"name": "Atención al cliente UE"}' curl -X POST https://boundaryai-ingest-279197672085.europe-west9.run.app/api/input/sources/create \\ -H "Authorization: Bearer $BAI_API_KEY" -H "Content-Type: application/json" \\ -d '{ "feedback_group_id": "1842", "source_title": "Tickets de soporte (sincronización CRM)", "feedback_type": "support_ticket", "fields": [ {"field_title": "¿Cuál fue el problema?", "field_type": "DEPTH_TEXT"}, {"field_title": "¿Qué probabilidades hay de que nos recomiendes?", "field_type": "NPS"} ] }' ``` Las fuentes se crean en modo borrador. Publica para empezar a enviar: ```bash curl -X POST https://boundaryai-ingest-279197672085.europe-west9.run.app/api/input/sources/publish \\ -H "Authorization: Bearer $BAI_API_KEY" -H "Content-Type: application/json" \\ -d '{"source_id": 9021, "feedback_group_id": 1842}' ``` ### Paso 3: Envía feedback ```bash curl -X POST https://boundaryai-ingest-279197672085.europe-west9.run.app/api/input/feedback/push \\ -H "Authorization: Bearer $BAI_API_KEY" -H "Content-Type: application/json" \\ -H "Idempotency-Key: 2c1f7c9e-batch-0712" \\ -d '{ "feedback_group_id": "1842", "source_id": "9021", "field": { "field_id": "31245", "content": [ "El nuevo panel es genial, pero las exportaciones son lentas.", {"text": "Soporte resolvió mi problema en una sola llamada.", "external_id": "ticket-58121", "rating": 5, "occurred_at": "2026-07-12T09:30:00Z"} ] } }' ``` Los elementos pueden ser cadenas simples u objetos estructurados. Hay tres campos que merece la pena usar desde el primer día: * **`external_id`**: tu ID estable para el elemento. Se omite un envío reintentado con un `external_id` que el campo ya contiene en lugar de escribirlo dos veces; la respuesta lo informa en `skipped_duplicates`. * **`occurred_at`**: cuándo ocurrió realmente el feedback. Retrotrae temporalmente el elemento para que los grupos con seguimiento temporal lo coloquen en el periodo correcto. * **`Idempotency-Key`** cabecera: hace que toda la solicitud sea segura para reintentar durante 24 horas. Para cargas retrospectivas, usa `POST /feedback/push/bulk` (muchos campos en una llamada; asíncrono por defecto, con un modo síncrono para lotes pequeños) o `POST /feedback/upload` con un archivo CSV/XLSX. Consulta [Envío de feedback](/boundaryai-docs/boundaryai-docs-es/api-y-webhooks/pushing-feedback.md). ### Paso 4: Lee el análisis (o deja que un webhook te avise) El análisis se ejecuta automáticamente después de que llegue el contenido. Léelo de vuelta: ```bash curl https://boundaryai-ingest-279197672085.europe-west9.run.app/api/input/sources/9021/analysis \\ -H "Authorization: Bearer $BAI_API_KEY" ``` Obtienes la distribución de sentimiento, los temas y las coincidencias de Custom Monitoring. En lugar de hacer polling, suscríbete al `analysis.completed` evento; consulta [Webhooks](/boundaryai-docs/boundaryai-docs-es/api-y-webhooks/webhooks.md). *** ### Convenciones que debes conocer * **Respuestas de éxito**: hoy una respuesta 2xx lleva la carga útil directamente, como se muestra en cada ejemplo. Cada 2xx también lleva `Deprecation` y `Sunset` cabeceras: anuncian que, después de la fecha de retirada, las cargas útiles de éxito se encapsularán como `{"data": {...}}`, exactamente como ya declaran los esquemas de la referencia. No deprecian ningún endpoint. Leer la carga útil desde `datos` cuando esa clave está presente, y desde la raíz en caso contrario, mantiene a un cliente correcto a ambos lados del cambio. * **Envoltorio de error**: los fallos devuelven `{"error": {"code": "...", "message": "..."}}` (más un `details` opcional) con un `code`. * **Límites de velocidad**: 60 solicitudes/minuto por clave y 300/minuto por organización por defecto, en ventanas fijas de 60 segundos; las respuestas 429 llevan una cabecera `Retry-After` . Los límites exactos de tu clave están en `GET /me`. * **Paginación**: `GET /feedback` usa cursores (devuelve `next_cursor` hasta que `has_more` sea falso); `GET /sources/list` toma `limit` (50 por defecto, máximo 200) y `offset` y devuelve un objeto de `paginación` objeto. * **Claves de prueba**: `inpk_test_...` las claves se comportan igual, pero están pensadas para integraciones de staging; mantenlas fuera del tráfico de producción. {% hint style="success" %} Todo lo que envías participa plenamente en el producto: los monitores de grupo con auto-coverage vigilan automáticamente las fuentes de API ([Monitorización personalizada](/boundaryai-docs/boundaryai-docs-es/analizando-sus-comentarios/custom-monitoring.md)), y los datos de API llegan a Temas agrupados, periodos de Evolución e informes como cualquier otra fuente. {% endhint %} *** ### Profundizando más * [Envío de feedback](/boundaryai-docs/boundaryai-docs-es/api-y-webhooks/pushing-feedback.md): cargas retrospectivas masivas, ingesta de archivos, deduplicación, retrodatación, borrado. * [Envío de invitaciones (API de correo)](/boundaryai-docs/boundaryai-docs-es/api-y-webhooks/sending-invites.md): activa invitaciones personalizadas a encuestas desde tu propio flujo de trabajo. * [Webhooks](/boundaryai-docs/boundaryai-docs-es/api-y-webhooks/webhooks.md): actúa sobre eventos en lugar de hacer polling. * [Conecta asistentes de IA (MCP)](/boundaryai-docs/boundaryai-docs-es/api-y-webhooks/mcp.md): permite que un asistente consulte los resultados. ### Lo que deliberadamente no está en la API Algunas cosas son solo del panel a propósito, así que si buscas un endpoint que no existe, probablemente sea por esto: * **Creación de encuestas y plantillas**: lo que ven los encuestados y los invitados se diseña, previsualiza y revisa en la plataforma; la API lo activa, pero no puede reescribirlo. Una clave filtrada nunca puede cambiar lo que reciben tus clientes. * **Gestión de suscripciones a webhooks**: crear suscripciones y leer secretos de firma ocurre en el panel, así que una clave de API no puede redirigir tu flujo de eventos a una URL nueva. * **Configuración de envío de correo electrónico**: los dominios del remitente y los niveles de envío son ajustes de la organización ([Configuración](/boundaryai-docs/boundaryai-docs-es/cuenta-y-administracion/updating-settings.md#email-sending)); la API envía *a través de* ellos, pero no puede modificarlos. * **Miembros y ajustes de la organización**: las acciones de administración siguen siendo de los administradores. Si de verdad tu caso de uso necesita una de estas funciones de forma programática, cuéntanoslo en ; preferimos conocer el caso antes que ver que lo construyes por tu cuenta.