API REST
Con API REST conviertes cualquier endpoint HTTP en una herramienta que tu agente puede invocar durante una conversación. A diferencia de los MCPs (que conectan un servidor completo), aquí defines una sola request y le dices a la IA qué datos debe entregar para ejecutarla.
Cada API combina dos cosas:
- Un schema — los campos que la IA debe rellenar (por ejemplo, el ID de un pedido).
- Una request HTTP completa — método, URL, parámetros, headers, cuerpo y opciones de respuesta.
Para empezar, haz clic en "Crear API". El asistente tiene tres pasos: Identidad → Definir → Revisar y crear. La API se crea como borrador; podrás habilitarla cuando esté lista.
Paso 1: Identidad
Dale un nombre técnico y una descripción que le permitan a la IA saber cuándo usar la herramienta.
| Campo | Descripción |
|---|---|
| Nombre técnico | Identificador único en el workspace. Solo admite letras minúsculas, dígitos y guion bajo (_). La IA verá la herramienta como api_<nombre> (por ejemplo, api_get_order_details). |
| Descripción | El texto que la IA lee para decidir cuándo invocar la herramienta. Sé específico: explica qué hace y en qué situación usarla (por ejemplo: "Obtiene los datos completos de un pedido por su ID. Úsala cuando el usuario pregunte por el estado de un pedido específico."). Mínimo 10 caracteres, máximo 1024. |
Una buena descripción es clave: es lo único que la IA usa para elegir esta herramienta entre todas las disponibles. Si no estás seguro de cómo redactarla, usa el botón "Autocompletar" para generar una propuesta.
Paso 2: Definir la request
Aquí construyes la llamada HTTP real. Elige el método (GET, POST, etc.) y escribe la URL del endpoint.
La request se organiza en pestañas:
| Pestaña | Para qué sirve |
|---|---|
| Params | Parámetros de query que se agregan a la URL (?clave=valor). Hasta 25. |
| Authorization | Cómo se autentica la request (token, API key, etc.). |
| Headers | Encabezados HTTP adicionales. |
| Body | El cuerpo de la request (para POST, PUT, etc.). |
| Configuración | Opciones generales de la llamada. |
Si ya tienes la llamada en formato cURL, usa "Importar desde cURL" para precargar método, URL, headers y cuerpo automáticamente.
Variables
Las variables son la parte dinámica de la request. Escribe {{ }} en cualquier campo (URL, params, headers o body) y aparecerá un selector para insertar una.
Variables de contexto (ctx) — Datos que Platica conoce de la conversación y rellena automáticamente. Aparecen en el selector con la etiqueta CTX:
| Variable | Qué contiene |
|---|---|
{{ctx.phoneNumber}} | Número del cliente. |
{{ctx.workspaceId}} | ID del workspace. |
{{ctx.conversationId}} | ID de la conversación. |
{{ctx.agentId}} | ID del agente activo. |
{{ctx.agentName}} | Nombre del agente activo. |
{{ctx.channelId}} | ID del canal. |
Variables propias — Si escribes un nombre que no existe (por ejemplo {{orderId}}), el selector ofrece "Crear como nueva variable". Cada variable aparece en la tabla de Variables, con estas columnas:
| Columna | Descripción |
|---|---|
| Variable | El nombre que usaste entre {{ }}. |
| Modo | De dónde sale el valor (ver abajo). |
| Tipo | El tipo de dato: string, number, integer, boolean, array u object. |
| Descripción / Valor | En modo IA, la descripción que la IA lee para saber qué representa el campo; en modo Fija, el valor constante. |
| Usada en | Dónde aparece la variable dentro de la request (URL, query, header o body). |
| Req. | Si el campo es obligatorio. |
El Modo define el origen del valor de cada variable:
| Modo | De dónde sale el valor |
|---|---|
| IA | La IA rellena el valor al invocar la herramienta. Estas variables forman el schema de la herramienta. |
| Fija | Un valor constante que defines tú y nunca cambia. |
| Contexto | Se mapea a un dato de la conversación (un valor ctx, como el número del cliente). |
"Ver JSON Schema" abre el esquema exacto que verá el LLM. Solo incluye las variables en modo IA; las Fijas y de Contexto se conservan al guardar pero no aparecen en el schema (son constantes u ocultas para la IA). Desde ese modal puedes regenerar el schema desde las variables o editarlo a mano y pulsar "Aplicar".
Paso 3: Revisar y crear
El último paso muestra un resumen de la herramienta: nombre (tool name), método, URL, número de variables y descripción.
Desde aquí tienes dos opciones:
- Crear como borrador — guarda la API para seguir editándola más tarde. No queda activa.
- Crear y habilitar — crea la herramienta y la deja activa de inmediato.
Administrar la API
Tras crearla, se abre la vista de detalle de la API. Si la guardaste como borrador, aparece con la etiqueta BORRADOR y un botón "Publicar" para activarla (te lleva a esta misma vista, ya con la API activa).
La vista de detalle tiene varias pestañas:
| Pestaña | Para qué sirve |
|---|---|
| Resumen | Vista general de la herramienta. |
| Editor | Edita la request y las variables (lo mismo que el Paso 2). |
| Respuesta | Define qué parte de la respuesta verá la IA. |
| Avanzado | Opciones avanzadas de la herramienta. |
| Logs | Registro de invocaciones de la API. |
| Stats | Estadísticas de uso. |
Pestaña Resumen
Muestra y permite editar la identidad de la herramienta (nombre técnico y descripción, con "Autocompletar"), junto con metadatos de seguimiento:
| Dato | Descripción |
|---|---|
| Versión | Número de versión de la herramienta. |
| Última edición | Fecha y hora del último cambio. |
| Última prueba | Cuándo se probó por última vez (— si nunca se ha probado). |
Pestaña Editor
Es el mismo constructor del Paso 2: ahí editas el método, la URL, las pestañas (Params, Authorization, Headers, Body, Configuración) y las variables de la request. También incluye el botón "Probar API".
Probar la API
Desde el Editor o la pestaña Respuesta puedes abrir "Probar API" para ejecutar una llamada real sin salir de Platica.
| Elemento | Descripción |
|---|---|
| Input simulado | El JSON que la IA pasaría como argumentos al invocar la herramienta. Usa "Auto-rellenar" para generar valores de ejemplo. |
| Dry run | Simula la llamada sin enviarla realmente. |
| Ejecutar | Envía la request de verdad. |
Tras ejecutar, verás el resultado (success + tiempo de respuesta) y el detalle de la request enviada: método, URL final, headers y método de autenticación.
Pestaña Respuesta
Aquí decides qué parte de la respuesta de tu API verá la IA. Para eso Platica necesita un ejemplo real: si aún no has probado la API, la pestaña te pedirá ejecutar "Probar API" primero; con la respuesta de ejemplo en mano, podrás mapearla.
¿Qué parte de la respuesta usa la IA? — Elige un sub-camino (path) si la respuesta trae más de lo necesario. Platica te sugiere paths detectados en la respuesta de ejemplo (por ejemplo [0].name, [0].email) como chips de un clic, o puedes dejar "Respuesta completa". Dos paneles lado a lado muestran la respuesta cruda y lo que recibirá la IA, así ves el efecto de cada cambio al instante.
Filtrar campos — Limita qué propiedades ve la IA dentro del path seleccionado:
| Modo | Qué hace |
|---|---|
| Todos los campos | La IA recibe todo (comportamiento por defecto). |
| Sólo estos | La IA solo ve los campos que marques. |
| Todos menos | La IA ve todo excepto los campos que excluyas. |
Úsalo para reducir ruido (campos irrelevantes que confunden al agente) o para esconder datos sensibles que no quieres exponer a la IA.
Fallar si el path no existe — Activado por defecto. Si defines un path y la respuesta de la API ya no lo contiene, la IA recibe un error claro en lugar de la respuesta completa. Desactivarlo puede esconder bugs (por ejemplo, que la API cambió su estructura sin avisar); se recomienda dejarlo activo.
Límite de tamaño — Tope de caracteres que la IA verá del JSON ya filtrado. Si la respuesta lo excede, se trunca con la marca [truncated …] para que la IA sepa que faltan datos. El default es 32,000 caracteres (≈ 8,000 tokens).
Mientras más enfocada sea la respuesta (un path concreto + solo los campos útiles), mejores y más baratas serán las respuestas del agente: menos tokens de entrada y menos ruido que interpretar.
Pestaña Avanzado
Opciones para casos especiales, desactivadas por defecto:
Auth periódica — Inyecta automáticamente un token que renueva un cron job de tipo auth. Al activarla configuras:
| Campo | Descripción |
|---|---|
| Cron job | El cron de tipo auth que genera el token. Si no tienes ninguno, créalo primero en Cron jobs y regresa. |
| Inyectar en | Dónde se coloca el token (por ejemplo, en un Header). |
| Nombre | El nombre del header (por ejemplo, Authorization). |
| Prefix / Suffix | Texto que se antepone o agrega al token (por ejemplo, el prefijo Bearer). |
El campo "Valor enviado" muestra una vista previa de cómo quedará el encabezado con el token.
Encrypt payload (JWT) — Firma el cuerpo de la request con HS256 + exp y lo envía como jdata form-urlencoded. Pensado para integraciones legacy específicas. Configuras el Secret HS256 y el TTL (segundos) del token.
Las opciones de Avanzado son para integraciones técnicas específicas. Si no sabes si las necesitas, déjalas desactivadas.
Pestaña Logs
Registra cada invocación de la API (reales y de prueba) con su historial completo. Arriba verás métricas agregadas: Total, Éxitos, Errores, Tasa de error y latencias P50 / P95 (hasta los últimos 30 días).
Puedes filtrar por Todos / Éxitos / Errores, buscar y Exportar el registro. Al desplegar una llamada ves su estado, método, latencia y la metadata completa (trigger, toolName, inputArgs, requestUrl, requestHeaders, sentBody) y, si falló, el mensaje de error.
Pestaña Stats
Resume la actividad de la API en una ventana de 24 h, 7 días o 30 días: número de llamadas, éxitos, errores (con su tasa) y latencia (p50 y p95).
Publicar, pausar y administrar
Desde la barra superior de la API gestionas su estado:
- Publicar — activa la API (sale del estado borrador) para que los agentes puedan usarla.
- Pausar — una vez publicada, puedes pausarla para desactivarla temporalmente sin eliminarla.
- Menú (⋮) — desde los tres puntos puedes clonar la API (para crear una variante) o eliminarla por completo.