Paso: Solicitud HTTPS (HTTP Request)
Conecta el flujo de trabajo con sistemas externos, envía una solicitud HTTP y guarda valores de la respuesta como variables.
HTTP Request permite que un flujo de trabajo consulte o envíe datos a un sistema externo, como un CRM, una mesa de ayuda, un sistema de pedidos o una API interna. En términos prácticos, es un paso que pregunta o informa algo a otra herramienta y guarda la respuesta para decidir qué hacer después.
Cuándo usarlo
- Consultar un CRM para saber si un contacto ya existe.
- Crear un ticket en una mesa de ayuda.
- Enviar un lead a una herramienta comercial.
- Consultar estado de pedido antes de responder al cliente.
- Guardar un identificador externo para usarlo en pasos posteriores.
Configuración básica
| Campo | Qué hace | Ejemplo |
|---|---|---|
| Método | Tipo de operación que enviarás. | `GET` para consultar, `POST` para crear, `PUT` o `PATCH` para actualizar, `DELETE` para eliminar, `HEAD` para revisar metadata. |
| URL | Endpoint del sistema externo. | `https://api.crm.com/contacts/$contact.phone`. |
| Parameters | Pares clave/valor que Autochat agrega a la URL como query string. | `phone=${contact.phone}`, `source=whatsapp`. |
| Body | Contenido que se envía a la API. | JSON con nombre, teléfono, etapa o variables del flujo de trabajo. |
| Content-Type | Formato del body. | `application/json`, `application/x-www-form-urlencoded` o `text/plain`. |
| Headers | Datos adicionales de la solicitud, como autenticación. | `Authorization: Bearer $secret.crmToken`. |
| Response Mapping | Guarda partes de la respuesta JSON como variables. | `$.data.id` → `crmContactId`. |
| Guardar status como variable | Guarda el código HTTP devuelto por la API. | `apiStatus` con valor `200`, `404` o `500`. |
| Secrets | Guarda tokens o API keys fuera del texto visible del nodo. | `$secret.crmToken`. |
Métodos HTTP
| Método | Uso típico | Body |
|---|---|---|
| GET | Consultar información. | No envía body. |
| POST | Crear un registro o enviar datos. | Sí puede enviar body. |
| PUT | Reemplazar o actualizar un registro. | Sí puede enviar body. |
| PATCH | Actualizar parte de un registro. | Sí puede enviar body. |
| DELETE | Eliminar o cancelar algo en una API. | Puede enviar body si la API lo acepta. |
| HEAD | Consultar metadata sin leer cuerpo de respuesta. | No envía body y no usa response mapping. |
Parameters
Parameters son pares de `Key` y `Valor` que Autochat agrega a la URL antes de enviar la solicitud. Se usan normalmente en consultas `GET` para filtrar, buscar, paginar o pasar datos simples sin escribirlos manualmente dentro de la URL.
| Parte | Qué escribir | Ejemplo |
|---|---|---|
| Key | Nombre exacto del parámetro que espera la API externa. | `phone`, `source`, `limit`, `status`. |
| Valor | Dato fijo, variable del flujo o secret escrito como referencia. | `$contact.phone`, `whatsapp`, `$secret.apiKey`. |
| Resultado | Autochat combina la URL y los parameters al ejecutar la solicitud. | `https://api.crm.com/contacts?phone=573001112233&source=whatsapp`. |
Buscar contacto por teléfono
La API del CRM espera el teléfono como parámetro de consulta.
- Método: `GET`.
- URL: `https://api.crm.com/contacts`.
- Parameter `phone`: `${contact.phone}`.
- Parameter `source`: `whatsapp`.
- Response Mapping: `$.data.id` → `crmContactId`.
La URL queda limpia en el builder y el teléfono se agrega automáticamente cuando el workflow se ejecuta.
- Puedes configurar hasta 20 parameters.
- Si escribes un valor, el `Key` no puede estar vacío.
- Usa parameters para filtros simples, búsqueda, paginación o identificadores que la API espera en la URL.
- Usa body para datos más grandes o estructuras JSON.
- Si una API pide una credencial en la URL, puedes referenciar un secret, pero normalmente es mejor enviar credenciales en un header como `Authorization`.
Variables y secrets
Puedes insertar variables en URL, parameters, headers y body. El builder reconoce formatos como `$contact.id`, `${contact.name}` y `{{contact.phone}}`. Usa variables para enviar datos del contacto, respuestas de preguntas, resultados de WhatsApp Flow o valores guardados por pasos anteriores.
| Tipo | Uso | Ejemplo |
|---|---|---|
| Variable de contacto | Datos conocidos del contacto. | `$contact.phone`, `${contact.name}`. |
| Variable del flujo de trabajo | Dato guardado por un paso anterior. | `$correo`, `${flow.direccion}`. |
| Variable en parameter | Enviar un valor simple como filtro de consulta. | Key `phone`, valor `${contact.phone}`. |
| Variable en body | Enviar una estructura más completa al sistema externo. | `{"phone":"${contact.phone}","reason":"$motivo"}`. |
| Secret | Token, API key o valor sensible guardado fuera del nodo. | `$secret.crmToken`. |
| Scope flujo de trabajo | Secret disponible solo para este flujo de trabajo. | Token dedicado de un CRM para ese proceso. |
| Scope workspace | Secret reutilizable en varios flujos de trabajo. | API key compartida por varias integraciones. |
Los secrets también se pueden referenciar donde la API los exija: URL, parameters, headers o body. Aun así, para tokens y API keys la práctica más común es guardarlos como secret y enviarlos en un header, por ejemplo `Authorization: Bearer $secret.crmToken`.
Body
El body es la información que envías al sistema externo. Normalmente se usa con `POST`, `PUT`, `PATCH` o `DELETE`. Para `GET` y `HEAD`, Autochat no enviará body aunque lo escribas.
Body JSON de ejemplo
{
"name": "${contact.name}",
"phone": "${contact.phone}",
"source": "whatsapp",
"budget": "$presupuesto"
}Headers
Los headers son pares de nombre y valor que acompañan la solicitud. Muchas APIs los usan para autenticación o para indicar cómo interpretar el contenido.
| Header | Uso | Ejemplo |
|---|---|---|
| Authorization | Enviar token o API key. | `Bearer $secret.crmToken`. |
| Content-Type | Indicar formato del body. | `application/json`. |
| X-Request-Source | Identificar de dónde viene la llamada. | `autochat-workflow`. |
- Puedes configurar hasta 10 headers.
- El nombre del header no puede estar vacío.
- No repitas el mismo header con diferente mayúscula/minúscula.
- Autochat no permite controlar headers reservados como `Host`, `Content-Length`, `Connection`, `Transfer-Encoding`, `Accept-Encoding`, ni headers que empiezan por `sec-` o `proxy-`.
- Usa el botón `Secret` para insertar `$secret.nombre` en headers con credenciales o valores sensibles.
Response Mapping
Response Mapping toma una respuesta JSON y guarda partes específicas como variables del flujo de trabajo. Después puedes usar esas variables en mensajes, ramas, campos de contacto o pasos posteriores.
| Respuesta JSON | JSON Key | Variable |
|---|---|---|
| `{"id":"123"}` | `$.id` | `crmId` |
| `{"data":{"status":"active"}}` | `$.data.status` | `crmStatus` |
| `{"contacts":[{"name":"Ana"}]}` | `$.contacts[0].name` | `firstContactName` |
| `{"custom":{"phone":"123"}}` | `$.custom["phone"]` | `crmPhone` |
- El JSON Key debe empezar con `$`.
- Puedes usar propiedades con punto, como `$.data.id`.
- Puedes usar índices de listas, como `$.items[0].name`.
- Puedes usar propiedades entre comillas, como `$["order-id"]`.
- Puedes crear hasta 10 mappings.
- El método `HEAD` no puede usar Response Mapping porque no lee cuerpo de respuesta.
Status y ramas
El status HTTP indica cómo respondió la API. Guardarlo como variable te permite decidir el siguiente camino con `Ramas`: éxito, no encontrado, error temporal o revisión manual.
| Status | Qué suele significar | Qué podrías hacer |
|---|---|---|
| 200 / 201 | La solicitud fue exitosa. | Continuar al siguiente paso. |
| 400 | La API rechazó datos enviados. | Asignar a revisión o enviar a rama de error. |
| 401 / 403 | Autenticación o permisos incorrectos. | Revisar secret o credenciales. |
| 404 | No se encontró el recurso. | Crear contacto o usar camino alternativo. |
| 429 | Demasiadas solicitudes. | Esperar y reintentar con límite. |
| 500+ | Error del sistema externo. | Esperar, reintentar o asignar a una persona. |
Rama por status
Guardar el status y decidir qué hacer.
- Activa `Guardar status como variable`.
- Nombre: `apiStatus`.
- Paso siguiente: `Ramas`.
- Rama `OK`: variable `apiStatus` es igual a `200`.
- Rama `No encontrado`: variable `apiStatus` es igual a `404`.
- Sino: enviar a revisión manual o reintento.
El flujo de trabajo no depende de una sola respuesta; maneja estados distintos de forma explícita.
Ejemplos
Consultar CRM antes de asignar
Identificar si el contacto ya es cliente.
- Método: `GET`.
- URL: `https://api.crm.com/contacts`.
- Parameter `phone`: `${contact.phone}`.
- Header: `Authorization: Bearer $secret.crmToken`.
- Response Mapping: `$.data.status` → `crmStatus`.
- Guardar status como `apiStatus`.
- Paso siguiente: `Ramas` por `crmStatus` y `apiStatus`.
El flujo de trabajo puede tratar diferente a clientes activos, prospectos o errores de integración.
Crear ticket de soporte
Enviar el motivo del cliente a una mesa de ayuda.
- Paso anterior: `Hacer una pregunta` guarda `motivo`.
- Método: `POST`.
- URL: `https://support.example.com/api/tickets`.
- Body JSON con nombre, teléfono y motivo.
- Response Mapping: `$.ticket.id` → `ticketId`.
- Paso siguiente: `Enviar mensaje` con el número de ticket.
El cliente recibe confirmación y el equipo ve el ticket creado en su herramienta.
Límites y validaciones
- La URL es obligatoria y debe empezar por `http://` o `https://`.
- Solo se soportan protocolos HTTP y HTTPS.
- La URL no puede incluir usuario o contraseña.
- HTTPS es recomendado; HTTP sin cifrado genera advertencia.
- Máximo 20 parameters.
- Máximo 10 headers.
- Máximo 10 response mappings.
- Los nombres de variables pueden usar letras, números y guion bajo, hasta 64 caracteres, empezando con letra o guion bajo.
- No uses nombres reservados como `contact`, `workflow`, `system`, `http`, `conversation`, `trigger`, `step` o `vectorpos`.
- El timeout de ejecución no puede superar 10 segundos.
- Los redirects no pueden superar 3.
- La respuesta máxima leída no puede superar 1 MiB.
FAQ
| Pregunta | Respuesta |
|---|---|
| ¿Puedo usar OAuth con autorización interactiva? | Este paso está pensado para APIs que aceptan tokens estáticos, API keys o secretos ya generados. Flujos OAuth con consentimiento, intercambio de códigos o refresh dinámico suelen requerir una integración técnica aparte. |
| ¿Dónde pongo un token? | Guárdalo como secret y úsalo como `$secret.nombre`, normalmente en un header `Authorization`. Si la API exige enviarlo como parameter, usa el secret como valor del parameter. |
| ¿Parameters y body son lo mismo? | No. Parameters van en la URL y sirven para filtros o valores simples. Body es el contenido principal de la solicitud y se usa para enviar datos más completos, normalmente en `POST`, `PUT` o `PATCH`. |
| ¿Qué pasa si la API tarda mucho? | Si supera el timeout configurado, la solicitud falla. Diseña una rama o un reintento controlado con `Esperar` y `Saltar a paso`. |
| ¿Puedo mapear cualquier JSON? | Puedes mapear rutas JSON simples con `$`, puntos, índices y claves entre comillas. Si necesitas transformar datos complejos, prepara la respuesta en el sistema externo. |
Buenas prácticas
- Usa HTTPS siempre que el sistema externo lo permita.
- Configura filtros simples como `Parameters` en lugar de pegarlos dentro de la URL.
- Guarda status como variable y decide con `Ramas`.
- Usa secrets para tokens y API keys.
- Prueba con datos de muestra antes de publicar.
- Agrega reintentos limitados para errores temporales.
- Documenta qué variables crea cada HTTP Request.
- No envíes datos que el sistema externo no necesita.