Antes de comenzar
La herramienta de Solicitud HTTP (HTTP Request) está diseñada para realizar integraciones de API personalizadas. Su configuración se basa en la documentación de la API del servicio de terceros y requiere conocimientos básicos sobre APIs REST, similar a la creación de una solicitud en herramientas como Postman.
Antes de configurar este paso, busca la siguiente información en la documentación de la API del servicio:
La URL del endpoint (punto de enlace).
El método de la solicitud.
El método de autenticación y los encabezados (headers) requeridos.
El Content-Type (tipo de contenido) requerido, como
application/jsonoapplication/x-www-form-urlencoded.Los nombres exactos de los parámetros, los valores aceptados y los formatos de datos.
Los campos de respuesta esperados.
Importante: Una conexión de Solicitud HTTP estándar no configura la autenticación de forma automática. Debes agregar el encabezado de autorización, la clave API (API key), el token u otras credenciales requeridas de acuerdo con la documentación del servicio de terceros. Utilizar un Content-Type, un nombre de parámetro o un formato de valor incorrectos puede hacer que el servicio rechace la solicitud.
Cada API requiere una configuración individual.
¿Qué es una solicitud HTTP?
En términos simples, es una petición enviada directamente desde Darwin a una aplicación externa, solicitando que se ejecute una acción específica en dicho sistema.
Una vez ejecutada esta acción, recibimos una respuesta, la cual puede contener una confirmación de éxito, un mensaje de error o incluso la devolución de datos adicionales que se hayan solicitado.
Principales tipos de solicitudes HTTP (Métodos)
Cada solicitud HTTP utiliza un método que le indica a la aplicación externa qué acción deseas realizar. Los métodos más utilizados son los siguientes:
GET (Obtener): Se utiliza para recuperar información.
Ejemplo: Obtener datos de un usuario desde un CRM específico, listar pedidos completados o consultar productos en tu e-commerce.
POST (Crear/Enviar): Se utiliza para crear nuevos datos directamente desde Darwin en la aplicación externa.
Ejemplo: Crear un lead (prospecto) en el CRM, enviar un formulario de compra completado o registrar una venta en una hoja de cálculo. Básicamente, envía datos recopilados en Darwin hacia la aplicación externa para desencadenar una acción.
PUT / PATCH (Actualizar): Se utilizan para actualizar datos existentes.
Ejemplo: Actualizar la dirección de correo electrónico de un cliente o cambiar el estado de un pedido.
DELETE (Eliminar): Se utiliza para borrar datos.
Ejemplo: Eliminar un registro duplicado o dar de baja a un usuario que ha cancelado su plan en tu plataforma.
El método a elegir dependerá de la acción que desees realizar. Al revisar la documentación de la API de la aplicación externa, podrás determinar qué método se debe usar para cada caso específico.
¿Qué es una URL (endpoint) en una solicitud HTTP?
Toda solicitud HTTP se envía a una aplicación externa. Dependiendo de la acción, esta solicitud deberá dirigirse a un área específica de dicha aplicación o deberá contener datos predefinidos para garantizar su éxito.
Este enrutamiento se realiza a través de la URL (endpoint), la cual proporcionaremos al configurar el paso en Darwin.
Estructura de una solicitud HTTP
Como mencionamos anteriormente, toda solicitud HTTP debe incluir un Método y una URL.
Al configurar este paso en Darwin, verás tres secciones principales donde se pueden enviar o recibir datos:
Encabezados (Headers)
Esta parte de la solicitud es la primera en ser procesada por la aplicación externa. En la mayoría de los casos, los encabezados contienen información esencial como tokens, claves API y otros datos de autorización necesarios para autenticar la solicitud.
En la configuración de la solicitud HTTP, presta atención al campo Formato de mayúsculas y minúsculas del encabezado (Header case format). Algunas APIs son sensibles al uso de mayúsculas o minúsculas en los nombres de los encabezados. Esta configuración te permite definir cómo se enviarán las claves en la solicitud.
Las opciones disponibles incluyen:
Title Case: (ej.
X-Api-Key)lowercase (minúsculas): (ej.
x-api-key)UPPERCASE (MAYÚSCULAS): (ej.
X-API-KEY)Conservar original: Envía los encabezados exactamente como los escribiste.
Debes elegir el formato que coincida con los requisitos especificados en la documentación de la API de la aplicación externa. Si el formato no coincide, la solicitud podría fallar por errores de validación o autorización.
Parámetros de la Solicitud (Body o Cuerpo)
Esta sección se utiliza generalmente con los métodos POST, PUT o PATCH.
Aquí defines los parámetros que se enviarán a la aplicación externa. Por ejemplo, al crear un nuevo contacto, este es el lugar donde incluyes campos como el nombre, el correo electrónico o el número de teléfono.
Parámetros de Respuesta (Response)
Aquí configuras qué información debe devolverse como respuesta a tu solicitud.
Por ejemplo, puedes configurar que devuelva el estado de la solicitud (si fue exitosa o si ocurrió un error), o cualquier dato adicional proporcionado por la aplicación externa. En el caso de una solicitud GET, podrías enviar el ID de un usuario del CRM y configurar la respuesta para que devuelva detalles adicionales sobre ese usuario, como su nombre o dirección.
¿Dónde encuentro la información necesaria para crear una solicitud HTTP?
Para configurar una solicitud HTTP correctamente, necesitas detalles técnicos específicos como la URL del endpoint, los encabezados requeridos, los parámetros y el método adecuado. Toda esta información la proporciona la documentación de la API de la aplicación externa.
Cualquier aplicación que ofrezca una API (es decir, que permita la interacción remota con otros sistemas) proporciona una documentación que explica qué acciones están disponibles, qué datos se pueden enviar o recuperar, y cómo deben estructurarse las solicitudes. Esta documentación suele estar organizada por tipo de acción (crear, actualizar, recuperar), mostrando los endpoints disponibles, parámetros obligatorios y métodos de autenticación.
Tomemos como ejemplo la API de un CRM llamado Perfex, asumiendo que el objetivo es crear un nuevo registro (suscripción):
Al localizar esta acción en la documentación, verás el método que debes usar.
A continuación, verás la URL.
Finalmente, los campos (parámetros) que deben enviarse.
Por ejemplo, la documentación podría indicar que el campo authtoken (de tipo cadena de texto o String) es el único que debe enviarse en la sección de Encabezados (Headers). Además, detallará qué parámetros debes completar en la sección del Cuerpo (Body) para que el registro se cree correctamente en el CRM.
Atención: Cada aplicación externa tiene su propia documentación. La mayoría se puede encontrar públicamente en internet; otras requieren contactar directamente al equipo de soporte de la aplicación. Las dudas específicas sobre acciones disponibles o parámetros deben consultarse con el soporte técnico de dicha plataforma.
Configuración de la solicitud HTTP
A continuación, explicamos cómo configurar esta solicitud en la plataforma.
Creación de la Solicitud HTTP
El proceso de configuración es similar al de crear una nueva conexión.
Ve a la pestaña de Aplicaciones (Apps) y haz clic en Agregar una conexión (Add a connection).
Para empezar, solo debes completar la URL y el formato (Content-type), según lo indique la documentación.
Los campos restantes se completarán dentro de la automatización.
Puedes agregar múltiples solicitudes HTTP para diferentes aplicaciones o acciones. Por ello, es importante configurar un nombre interno que facilite su identificación en el futuro.
Una vez configurado este paso, ve a la pestaña de Automatizaciones y abre el flujo donde insertarás tu Solicitud HTTP.
En el lugar donde normalmente agregarías una acción, haz clic para añadir un nuevo paso y selecciona la conexión de Solicitud HTTP que acabas de crear.
Verás la opción de Enviar Solicitud (Send API Request) o Obtener archivo por URL (Get a File by URL). Selecciona Enviar Solicitud.
Ingresa nuevamente tu URL en el campo correspondiente.
Si es una URL dinámica, puedes ingresar una parte como valor fijo y rellenar el resto con variables dinámicas de pasos anteriores.
Completa el campo del método. (El campo de protocolo no necesita completarse a menos que la documentación lo exija explícitamente).
Configura los Encabezados (Headers). Define el nombre exacto del campo y su tipo de dato (por ejemplo, String).
Configura los Parámetros (Body). Selecciona los campos que enviarás. Si un campo no está marcado como obligatorio en la documentación, es opcional. Asigna los valores correspondientes a cada parámetro.
Configura la Respuesta (Response) para recibir el mensaje de éxito o la advertencia de error.
¡Listo! Solo activa la automatización y podrás verificar el resultado de este paso en la pestaña de historial de la plataforma.
Solicitudes de API para acceder a archivos (Obtener archivo por URL)
También puedes usar una solicitud API para descargar un archivo. Por ejemplo, si en un paso de tu automatización recibes únicamente la URL de un archivo (pero no el archivo en sí), puedes usar este método.
Darwin enviará una solicitud a esa URL y recuperará el archivo, dejándolo disponible para su uso en pasos posteriores (por ejemplo, para subirlo a Google Drive).
Cómo configurarlo:
Identifica la URL correcta (endpoint) donde está alojado el archivo.
Crea una nueva conexión especificando la URL y el formato.
En la automatización, selecciona la opción Obtener archivo por URL (Get a File by URL).
Usa el método GET y mapea la URL dinámica obtenida en el paso anterior.
La respuesta de esta solicitud será el archivo físico.
Solicitud de API Personalizada vs. Solicitud HTTP estándar
Al buscar una acción específica para una aplicación dentro de tu automatización, es posible que encuentres una opción llamada Solicitud de API Personalizada (Custom API Request).
En resumen, esta acción es una versión simplificada de la Solicitud HTTP. Acelera el proceso de configuración porque no necesitas incluir manualmente los datos obligatorios del encabezado, como las claves API o los tokens. Como la conexión con la aplicación ya está creada de forma nativa en la plataforma, la autenticación se maneja automáticamente.
Para utilizarla, la aplicación debe tener una conexión configurada previamente en tu cuenta y la acción de Custom API Request debe estar disponible en su lista de acciones. Solo necesitas consultar la documentación de la API, encontrar el endpoint deseado y completar los parámetros de solicitud o respuesta.