API Request

API Request conecta tu flujo con cualquier servicio que tenga una dirección web pública para consultar o enviar datos: un CRM, un ERP, una tienda online o una herramienta interna de tu empresa. Le indicas la dirección, el tipo de operación y, si hace falta, los datos que quieres enviar. El componente hace la llamada y te devuelve lo que contesta el servicio.

Úsalo cuando NappAI no tiene un componente propio para el servicio que necesitas, o cuando quieres hacer una operación concreta que ese componente no cubre.

Cuándo usarlo

• Consultar el estado de un pedido en el sistema de tu proveedor logístico a partir de su número.
• Dar de alta un contacto en tu CRM cada vez que alguien rellena un formulario.
• Traer los precios o el stock actualizados desde el ERP antes de que un agente responda a un cliente.
• Avisar a una herramienta interna de que un proceso ha terminado.
• Consultar varias direcciones a la vez y reunir sus respuestas en un solo resultado.

Configuración

Campo	Qué hace
URLs (obligatorio)	La dirección o direcciones a las que llamar. Si pones varias, sepáralas con comas: el componente llama a todas con la misma configuración.
Method (obligatorio)	El tipo de operación: GET para consultar, POST para crear o enviar, PATCH para modificar una parte y PUT para reemplazar. Por defecto, GET.
Headers Mode	Cómo escribes las cabeceras: JSON, todas juntas en el campo Headers, o Create Manually, una a una. Por defecto, JSON.
Headers	Las cabeceras de la llamada, por ejemplo la clave de acceso que te da el servicio. Se ve con Headers Mode en JSON.
Number of Headers	Cuántas cabeceras quieres añadir una a una. Aparece con Headers Mode en Create Manually y crea un par de campos Header 1 Key / Header 1 Value por cada una.
Body Mode	Cómo escribes los datos que envías: JSON, Create Manually (JSON), campo a campo, o x-www-form-urlencoded, el formato de un formulario web. Solo aparece con los métodos POST, PATCH y PUT. Por defecto, JSON.
Body	Los datos que envías al servicio. Se ve con Body Mode en JSON o x-www-form-urlencoded.
Number of Body Fields	Cuántos campos quieres añadir uno a uno. Aparece con Body Mode en Create Manually (JSON) y crea los campos Body Field 1 Key / Body Field 1 Value, y así sucesivamente.
Query Parameters Mode	Cómo escribes los filtros que van en la propia dirección: JSON o Create Manually. Por defecto, JSON.
Query Parameters	Los filtros que se añaden a la dirección, por ejemplo una búsqueda o un número de página.
Number of Query Parameters	Cuántos filtros quieres añadir uno a uno. Aparece con Query Parameters Mode en Create Manually.

Opciones avanzadas

Campo	Qué hace
Curl	Si la documentación del servicio te da un ejemplo de llamada en formato curl, pégalo aquí: el componente rellena la dirección, el método, las cabeceras, los datos y los filtros por ti.
Timeout	Segundos que espera la respuesta antes de darla por perdida. Por defecto, 5.

Con Body Mode en x-www-form-urlencoded puedes enviar archivos: si un campo recibe un archivo de otro componente, se adjunta a la llamada como lo haría un formulario web.

En la pestaña Batch Mode puedes conectar una lista en Batch Input para que el componente haga una llamada por cada elemento y reúna todas las respuestas. Consulta Batch Mode.

Resultado

La salida Data devuelve un resultado por cada dirección llamada, con:

• source: la dirección a la que se llamó.
• status_code: el código con el que respondió el servicio, por ejemplo 200 si todo fue bien o 404 si no encontró lo que pedías.
• result: lo que devolvió el servicio.
• headers: las cabeceras que se enviaron.

Si el servicio no contesta a tiempo, el resultado lleva status_code 408 y un campo error. Si la llamada no se puede hacer, lleva status_code 500 y la descripción del problema en error.

Puedes conectar la salida a componentes que leen datos, como JQ Query (Parse JSON) o Get Value By Key, o dársela a un agente. El componente también puede usarse como herramienta de un agente con Tool Mode.

Ejemplo

Una tienda online quiere que su asistente informe del estado de un envío.

1. Añade API Request al flujo.
2. En URLs, escribe la dirección de consulta de envíos que te da tu empresa de transporte.
3. Deja Method en GET.
4. En Headers, añade la clave de acceso que te dio la empresa de transporte, tal como indica su documentación.
5. En Query Parameters, añade el número de seguimiento del pedido.
6. Conecta la salida Data al agente que atiende a los clientes, para que conteste con el estado real del envío.

Buenas prácticas

• Comprueba status_code antes de usar la respuesta. Una llamada que falla no detiene el flujo: devuelve el código y el error para que decidas qué hacer.
• Guarda las claves de acceso como variables secretas del entorno en lugar de escribirlas a mano en cada flujo.
• Si el servicio tarda en responder, sube Timeout.
• Empieza pegando el ejemplo curl de la documentación del servicio en Curl: te ahorra errores de escritura.

Componentes relacionados

• URL: para leer el contenido de una página web.
• Webhook Input: para el caso contrario, cuando es el otro servicio el que llama a tu flujo.
• JQ Query (Parse JSON): para quedarte con la parte de la respuesta que necesitas.