# Acciones API propias: llama a tu API desde el chat

> Haz que tu agente intoCHAT llame a tu API HTTP durante el chat: petición y autenticación, importar cURL, datos tomados de la conversación y prueba.

Una acción API propia permite que el agente llame a un endpoint HTTP mientras conversa, por ejemplo para consultar existencias o precios actuales, y responda a partir del resultado. Las acciones se crean en la pestaña **Actions** (acciones) de tu agente. Para que el agente ofrezca un enlace en lugar de llamar a una API, consulta [Botones personalizados](/es/docs/custom-buttons).

## Crear una acción

Haz clic en **Add Action**, o en **Import a request** para empezar desde un comando cURL. El editor tiene cuatro pasos y se guarda una sola vez al final con **Create action**. La prueba es opcional pero recomendable.

### 1. The request (la petición)

- **Method**: GET, POST, PUT, PATCH o DELETE.
- **HTTPS URL**: el endpoint. Una cadena de consulta pegada en la URL pasa a la pestaña **Parameters**.
- **Parameters**, **Headers** y **Body** admiten pares de clave y valor. **Body** está disponible en todos los métodos salvo GET y se envía como JSON.
- **Collect data inputs for action (optional)**: valores que el agente obtiene de la conversación. Cada dato tiene un **Name** (letras, números y guiones bajos), un **Type** (Text, Number o Boolean), una **Description** y las opciones **Required** y **Array**. Hasta 25 datos por acción.

Usa un dato en cualquier parte de la petición como `{{name}}`: en la ruta de la URL, un parámetro, una cabecera o el cuerpo.

```text
GET https://api.example.com/products/{{productId}}/stock
```

El agente encuentra el valor en la conversación o se lo pide al visitante. Un dato **Required** impide que el agente llame a la acción antes de tener ese valor. Las variables que se usan pero no están declaradas como datos se eliminan de la petición; el editor te avisa y ofrece **Add them**.

### Autenticación

| Opción | Qué se envía |
| --- | --- |
| **No authentication** | Nada |
| **Bearer token / access token** | Una cabecera `Authorization: Bearer` con tu token |
| **API key in a header** | Tu clave en la cabecera que indiques, por ejemplo `X-API-Key` |
| **API key in the URL** | Tu clave como parámetro de consulta con el nombre que indiques, por ejemplo `api_key` |
| **Username and password** | Autenticación HTTP básica |
| **Custom — I'll set the headers myself** | Lo que añadas en la pestaña **Headers** |

### Importar una petición

Pega el ejemplo cURL de la documentación de tu API, o usa «Copy as cURL» sobre una petición en las herramientas de red del navegador. Se rellenan método, URL, parámetros, cabeceras y cuerpo, y la credencial pasa al selector **Authentication**. Importar sustituye la petición pero conserva el nombre y la descripción. Las subidas multipart (`-F`) se omiten y un cuerpo codificado como formulario se importa como campos JSON.

### 2. Try it (probar)

Introduce valores de prueba para los datos y haz clic en **Send test request**. La petición se construye exactamente como la construirá el agente. **Response Preview** muestra el estado, el cuerpo de la respuesta y la URL llamada.

### 3. When the AI should use it (cuándo usarla)

- **Action Name**: hasta 60 caracteres.
- **When to use**: qué hace la acción, qué datos devuelve y ejemplos de preguntas que deben activarla. El modelo lee los primeros 1.024 caracteres.
- **Server-side action** se ejecuta en los servidores de intoCHAT y es la opción predeterminada. **Client-side action** se ejecuta en el navegador del visitante; consulta [Acciones del lado del cliente](/es/docs/client-actions).
- **Enable this action**: desactiva una acción sin borrarla.

### 4. What the AI can see (qué ve la IA)

**Full data access** pasa toda la respuesta al modelo. **Limited data access** pasa solo los campos que marques en **Visible**; ejecuta antes una prueba para cargar la lista de campos. Si la respuesta es una lista, los campos se leen del primer elemento y el filtro se aplica a todos. Mientras no marques ningún campo, se pasa la respuesta completa.

## Límites y seguridad

- Hasta 25 acciones por agente, incluidos los [botones personalizados](/es/docs/custom-buttons) y las acciones que crea [Conecta tu tienda](/es/docs/connect-your-store).
- La URL debe apuntar a un host público. Se rechazan localhost, redes privadas, direcciones link-local y endpoints de metadatos de la nube, también cuando un nombre de host se resuelve en una de ellas. El editor muestra entonces «URL points to a blocked or internal host».
- No se siguen redirecciones. Si la prueba muestra «This address redirects somewhere else», haz clic en **Use this address**.
- Cada llamada caduca a los 30 segundos.
- Las respuestas de más de 40.000 caracteres se recortan. Con Limited data access se mantienen pequeñas.
- Las acciones del lado del servidor envían tus credenciales desde los servidores de intoCHAT, nunca a través del navegador del visitante.