Saltar a contenido

Documentación: Nodo de Solicitud HTTP

Descripción General

El Nodo de Solicitud HTTP permite realizar peticiones HTTP/HTTPS a APIs externas, servicios web o cualquier endpoint REST desde tus automatizaciones. Este nodo soporta todos los métodos HTTP estándar y múltiples tipos de autenticación.

¿Cuándo usar este nodo?

Utiliza este nodo cuando necesites:

  • Integrar con APIs de terceros (servicios externos, webhooks)
  • Enviar datos a sistemas externos
  • Consultar información de servicios web
  • Activar acciones en plataformas externas (abrir puertas, encender luces)
  • Sincronizar datos con otros sistemas
  • Enviar comandos a dispositivos IoT

Configuración del Nodo

El nodo tiene dos pestañas de configuración: Data Configuration y Auth Configuration.

Formulario de configuración del nodo HTTP Request

Pestaña 1: Data Configuration

Paso 1: URL del Endpoint

  1. En el campo "URL", ingresa la dirección completa del endpoint al que deseas hacer la petición
  2. Debe incluir el protocolo (http:// o https://)
  3. Puede incluir parámetros de consulta (query parameters)

Ejemplos:

https://api.ejemplo.com/v1/usuarios
https://ejemplo.com/webhook?evento=alerta
http://192.168.1.100:8080/api/dispositivos

Note

Se recomienda usar https:// para conexiones seguras cuando sea posible.

Paso 2: Método HTTP

  1. En el campo "Method", selecciona o ingresa el método HTTP a usar
  2. Métodos comunes:
  3. GET - Obtener información (consultas, lecturas)
  4. POST - Crear recursos, enviar datos
  5. PUT - Actualizar recursos completos
  6. PATCH - Actualizar recursos parcialmente
  7. DELETE - Eliminar recursos
  8. HEAD - Obtener solo encabezados
  9. OPTIONS - Consultar métodos soportados

Note

El método predeterminado es GET. Asegúrate de usar el método correcto según la documentación de la API.

Paso 3: Headers (Encabezados)

  1. En el campo "Headers", ingresa los encabezados HTTP en formato JSON
  2. Los encabezados son opcionales pero comúnmente necesarios
  3. Encabezados comunes:
  4. Content-Type - Tipo de contenido del body
  5. Accept - Tipo de respuesta esperada
  6. User-Agent - Identificador del cliente

Ejemplo:

{
  "Content-Type": "application/json",
  "Accept": "application/json",
  "User-Agent": "Netsocs-Automation/1.0"
}

Para tipos de contenido específicos:

{
  "Content-Type": "application/x-www-form-urlencoded"
}

Note

Si dejas este campo vacío, se usarán los encabezados predeterminados. Los encabezados de autenticación se agregan automáticamente según la configuración en la pestaña Auth.

Paso 4: Body (Cuerpo de la Petición)

  1. En el campo "Body", ingresa el contenido que deseas enviar
  2. Solo aplica para métodos: POST, PUT, PATCH
  3. El formato debe coincidir con el Content-Type especificado en Headers

Ejemplo con JSON:

{
  "nombre": "Juan Pérez",
  "email": "juan@ejemplo.com",
  "evento": "acceso_concedido",
  "timestamp": "2026-01-28T14:30:45Z"
}

Ejemplo con form-urlencoded:

nombre=Juan+Pérez&email=juan@ejemplo.com&evento=acceso_concedido

Ejemplo con texto plano:

Alerta: Movimiento detectado en zona restringida

Note

Puedes usar variables en el body: {"usuario": "{{userName}}", "evento": "{{eventType}}"}

Pestaña 2: Auth Configuration

La pestaña de autenticación te permite configurar credenciales para acceder a APIs protegidas. Hay tres tipos de autenticación disponibles:

Opción 1: Basic Auth (Autenticación Básica)

Formulario de Basic Auth

Usa esta opción cuando la API requiera usuario y contraseña en formato Basic Authentication.

Configuración:

  1. Selecciona "Basic Auth" en el campo "Auth Type"
  2. Nombre de usuario: Ingresa el usuario proporcionado por la API
  3. Contraseña: Ingresa la contraseña (el campo está oculto por seguridad)

Cuándo usar:

  • APIs que requieren usuario/contraseña tradicional
  • Sistemas legacy que usan autenticación básica HTTP
  • Dispositivos IoT con autenticación simple

Ejemplo de configuración:

{
  "authType": "basic",
  "authUsername": "admin",
  "authPassword": "mi_contraseña_segura"
}

Note

Las credenciales se codifican automáticamente en Base64 y se envían en el header Authorization: Basic <credenciales>.

Opción 2: Bearer Token

Formulario de Bearer Token

Usa esta opción cuando la API requiera un token de portador (Bearer Token), común en APIs modernas con OAuth 2.0.

Configuración:

  1. Selecciona "Bearer Token" en el campo "Auth Type"
  2. Bearer Token: Ingresa el token proporcionado por la API (el campo está oculto por seguridad)

Cuándo usar:

  • APIs con OAuth 2.0
  • Servicios que proporcionan JWT tokens
  • Plataformas cloud modernas (AWS, Azure, GCP)
  • APIs de redes sociales (Twitter, Facebook, etc.)

Ejemplo de configuración:

{
  "authType": "bearer",
  "authToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Dónde obtener el token:

  • Generalmente se obtiene a través de un endpoint de login/autenticación
  • Puede ser un token JWT (JSON Web Token)
  • Algunos servicios proporcionan tokens de larga duración en su panel de administración

Note

El token se envía automáticamente en el header Authorization: Bearer <token>.

Opción 3: API Key

Formulario de API Key

Usa esta opción cuando la API requiera una clave de API en un header personalizado.

Configuración:

  1. Selecciona "API Key" en el campo "Auth Type"
  2. API Key Name: Nombre del header donde se enviará la clave (ejemplo: X-API-Key, api_key, apikey)
  3. API Key Value: El valor de la clave API proporcionada por el servicio (el campo está oculto por seguridad)

Cuándo usar:

  • Servicios que usan claves API simples
  • APIs públicas con autenticación por clave
  • Servicios meteorológicos, mapas, traducción, etc.

Ejemplos de nombres comunes:

  • X-API-Key
  • api_key
  • apikey
  • X-Api-Token
  • Authorization (en algunos casos)

Ejemplo de configuración:

{
  "authType": "apikey",
  "authUsername": "X-API-Key",
  "authPassword": "sk_test_abc123xyz789..."
}

Note

El sistema agrega automáticamente el header con el nombre y valor especificados: <API-Key-Name>: <API-Key-Value>.

Estructura JSON Completa

{
  "url": "https://api.ejemplo.com/v1/eventos",
  "method": "POST",
  "headers": {
    "Content-Type": "application/json",
    "Accept": "application/json"
  },
  "body": "{\"evento\": \"alerta\", \"mensaje\": \"Movimiento detectado\"}",
  "authType": "bearer",
  "authToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Campos Requeridos

  • url - URL del endpoint (debe incluir protocolo)
  • method - Método HTTP (GET, POST, PUT, PATCH, DELETE, etc.)

Campos Opcionales

  • headers - Objeto JSON con encabezados personalizados
  • body - Contenido de la petición (para POST, PUT, PATCH)
  • authType - Tipo de autenticación: basic, bearer, o apikey
  • authUsername - Usuario (Basic Auth) o nombre de API Key
  • authPassword - Contraseña (Basic Auth) o valor de API Key
  • authToken - Token (Bearer Token)

Ejemplos de Uso

Ejemplo 1: GET Simple sin Autenticación

Caso: Consultar información pública de una API

Configuración:

  • URL: https://api.openweathermap.org/data/2.5/weather?q=Madrid&appid=API_KEY
  • Method: GET
  • Headers: {}
  • Auth: Ninguna (API Key en URL)

JSON:

{
  "url": "https://api.openweathermap.org/data/2.5/weather?q=Madrid&appid=abc123",
  "method": "GET",
  "headers": {},
  "body": ""
}

Ejemplo 2: POST con Basic Auth

Caso: Crear un usuario en un sistema con autenticación básica

Configuración:

  • URL: https://sistema.ejemplo.com/api/usuarios
  • Method: POST
  • Headers: {"Content-Type": "application/json"}
  • Body: Datos del usuario
  • Auth: Basic Auth (admin / contraseña123)

JSON:

{
  "url": "https://sistema.ejemplo.com/api/usuarios",
  "method": "POST",
  "headers": {
    "Content-Type": "application/json"
  },
  "body": "{\"nombre\": \"Juan Pérez\", \"email\": \"juan@ejemplo.com\"}",
  "authType": "basic",
  "authUsername": "admin",
  "authPassword": "contraseña123"
}

Ejemplo 3: POST con Bearer Token

Caso: Enviar alerta a Slack

Configuración:

  • URL: https://slack.com/api/chat.postMessage
  • Method: POST
  • Headers: {"Content-Type": "application/json"}
  • Body: Mensaje de Slack
  • Auth: Bearer Token

JSON:

{
  "url": "https://slack.com/api/chat.postMessage",
  "method": "POST",
  "headers": {
    "Content-Type": "application/json"
  },
  "body": "{\"channel\": \"#alertas\", \"text\": \"Movimiento detectado en Entrada Principal\"}",
  "authType": "bearer",
  "authToken": "xoxb-1234567890-1234567890123-abcdefghijklmnopqrstuvwx"
}

Ejemplo 4: GET con API Key

Caso: Consultar datos de una API con clave

Configuración:

  • URL: https://api.servicio.com/v1/datos
  • Method: GET
  • Auth: API Key (X-API-Key)

JSON:

{
  "url": "https://api.servicio.com/v1/datos",
  "method": "GET",
  "headers": {},
  "body": "",
  "authType": "apikey",
  "authUsername": "X-API-Key",
  "authPassword": "sk_live_abc123xyz789def456ghi012"
}

Ejemplo 5: Controlar Dispositivo IoT

Caso: Abrir una puerta mediante API REST del dispositivo

Configuración:

  • URL: http://192.168.1.50/api/door/open
  • Method: POST
  • Headers: {"Content-Type": "application/json"}
  • Body: Comando
  • Auth: Basic Auth

JSON:

{
  "url": "http://192.168.1.50/api/door/open",
  "method": "POST",
  "headers": {
    "Content-Type": "application/json"
  },
  "body": "{\"duration\": 5, \"reason\": \"acceso_autorizado\"}",
  "authType": "basic",
  "authUsername": "admin",
  "authPassword": "dispositivo123"
}

Ejemplo 6: Webhook con Variables

Caso: Enviar evento con datos dinámicos

Configuración:

  • URL: https://webhook.ejemplo.com/eventos
  • Method: POST
  • Body: Datos con variables de la automatización

JSON:

{
  "url": "https://webhook.ejemplo.com/eventos",
  "method": "POST",
  "headers": {
    "Content-Type": "application/json"
  },
  "body": "{\"evento\": \"{{eventType}}\", \"ubicacion\": \"{{location}}\", \"usuario\": \"{{userName}}\", \"timestamp\": \"{{timestamp}}\"}"
}

Respuestas HTTP

El nodo captura la respuesta del servidor y la hace disponible para nodos posteriores en la automatización.

Códigos de Estado Comunes

Código Significado Descripción
200 OK Petición exitosa
201 Created Recurso creado exitosamente
204 No Content Petición exitosa sin contenido en respuesta
400 Bad Request Error en la petición (datos inválidos)
401 Unauthorized Autenticación requerida o inválida
403 Forbidden Sin permisos para acceder
404 Not Found Recurso no encontrado
429 Too Many Requests Límite de peticiones excedido
500 Internal Server Error Error en el servidor
503 Service Unavailable Servicio no disponible

Manejo de Respuestas

La respuesta incluye:

  • Status Code: Código de estado HTTP
  • Body: Cuerpo de la respuesta (generalmente JSON)
  • Headers: Encabezados de respuesta

Ejemplo de respuesta exitosa:

{
  "statusCode": 200,
  "body": {
    "success": true,
    "message": "Usuario creado",
    "id": "12345"
  },
  "headers": {
    "content-type": "application/json"
  }
}

Solución de Problemas

Error: "Cannot connect to URL"

Causa: No se puede establecer conexión con el servidor

Solución:

  1. Verifica que la URL sea correcta y esté accesible
  2. Confirma que incluye el protocolo (http:// o https://)
  3. Verifica conectividad de red desde el servidor Netsocs
  4. Si es una URL local, asegúrate de que el servicio esté activo
  5. Revisa firewall y reglas de red

Error: "401 Unauthorized"

Causa: Credenciales de autenticación incorrectas o faltantes

Solución:

  1. Verifica que el tipo de autenticación sea correcto
  2. Confirma que las credenciales sean válidas
  3. Para Bearer Token, verifica que no haya expirado
  4. Para API Key, confirma el nombre del header correcto
  5. Revisa la documentación de la API para el formato de autenticación esperado

Error: "400 Bad Request"

Causa: El servidor rechaza la petición por datos inválidos

Solución:

  1. Verifica el formato del body (debe ser JSON válido si el Content-Type es application/json)
  2. Confirma que todos los campos requeridos estén presentes
  3. Revisa que los tipos de datos sean correctos (números como números, no strings)
  4. Valida que el método HTTP sea el correcto
  5. Consulta la documentación de la API para el formato esperado

Error: "404 Not Found"

Causa: El endpoint no existe

Solución:

  1. Verifica que la URL sea exactamente la documentada por la API
  2. Confirma que no haya errores tipográficos
  3. Revisa la versión de la API en la URL (v1, v2, etc.)
  4. Algunos endpoints requieren parámetros en la URL

Error: "SSL Certificate Error"

Causa: Problema con el certificado HTTPS

Solución:

  1. Si es un servidor de desarrollo, considera usar http:// temporalmente
  2. Verifica que el certificado del servidor sea válido
  3. Para certificados autofirmados, puede ser necesario configuración adicional
  4. Confirma que la fecha/hora del servidor Netsocs sea correcta

El body no se envía correctamente

Causa: Formato o encoding incorrecto

Solución:

  1. Asegúrate de que el body sea un string válido
  2. Si es JSON, usa comillas dobles (") no simples (')
  3. Escapa caracteres especiales si es necesario
  4. Verifica que el Content-Type header coincida con el formato del body
  5. Para JSON, usa: {"Content-Type": "application/json"}

Variables no se reemplazan en el body

Causa: Sintaxis incorrecta de variables

Solución:

  1. Usa el formato correcto: {{nombreVariable}}
  2. Verifica que la variable exista en el contexto de la automatización
  3. Si el body es JSON, las variables de texto deben estar entre comillas: "nombre": "{{userName}}"
  4. Para variables numéricas: "edad": {{userAge}} (sin comillas)

Mejores Prácticas

1. Seguridad

  • Usa HTTPS siempre que sea posible para proteger credenciales en tránsito
  • No expongas credenciales en logs o mensajes de error
  • Rota tokens y claves periódicamente según políticas de seguridad
  • Usa variables de entorno para almacenar credenciales sensibles
  • Limita permisos de las cuentas usadas para autenticación

2. Manejo de Errores

  • Implementa reintentos para fallos temporales de red
  • Valida respuestas antes de procesar los datos
  • Log de peticiones para debugging (sin exponer credenciales)
  • Notifica fallos a administradores cuando sea crítico
  • Timeouts apropiados para evitar bloqueos

3. Rendimiento

  • Evita peticiones innecesarias usando caché cuando sea posible
  • Respeta límites de tasa (rate limits) de las APIs
  • Usa métodos apropiados (GET para lecturas, POST para escrituras)
  • Comprime datos grandes cuando la API lo soporte
  • Paginación para grandes conjuntos de datos

4. Documentación

  • Documenta cada integración con propósito y configuración
  • Incluye ejemplos de peticiones y respuestas
  • Mantén registro de cambios en APIs externas
  • Versiona configuraciones cuando sea posible

5. Testing

  • Prueba en desarrollo antes de producción
  • Valida todos los códigos de estado posibles
  • Prueba con credenciales inválidas para verificar manejo de errores
  • Simula timeouts y errores de red
  • Documenta comportamiento esperado

Casos de Uso por Industria

Integración con Sistemas de Control de Acceso

{
  "url": "https://sistema-acceso.ejemplo.com/api/v1/doors/open",
  "method": "POST",
  "headers": {
    "Content-Type": "application/json"
  },
  "body": "{\"door_id\": \"MAIN-ENTRANCE\", \"duration\": 5, \"authorized_by\": \"{{userName}}\"}",
  "authType": "bearer",
  "authToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Notificación a Sistema de Gestión de Incidentes

{
  "url": "https://incidents.ejemplo.com/api/create",
  "method": "POST",
  "headers": {
    "Content-Type": "application/json"
  },
  "body": "{\"title\": \"Alerta de Seguridad\", \"description\": \"Movimiento detectado en zona restringida\", \"priority\": \"high\", \"location\": \"{{location}}\"}",
  "authType": "apikey",
  "authUsername": "X-API-Key",
  "authPassword": "sk_live_abc123xyz"
}

Actualizar Base de Datos Externa

{
  "url": "https://api.basedatos.com/v2/registros",
  "method": "POST",
  "headers": {
    "Content-Type": "application/json"
  },
  "body": "{\"tipo_evento\": \"{{eventType}}\", \"timestamp\": \"{{timestamp}}\", \"datos\": {{eventData}}}",
  "authType": "basic",
  "authUsername": "api_user",
  "authPassword": "secure_password_123"
}

Consultar Estado de Dispositivo IoT

{
  "url": "http://192.168.1.100/api/status",
  "method": "GET",
  "headers": {
    "Accept": "application/json"
  },
  "authType": "apikey",
  "authUsername": "api_key",
  "authPassword": "device_key_xyz789"
}

Preguntas Frecuentes

P: ¿Puedo hacer peticiones a servicios sin HTTPS?
R: Sí, pero solo para entornos de desarrollo o redes internas seguras. Evita enviar credenciales por HTTP en producción.

P: ¿Cómo obtengo un Bearer Token?
R: Generalmente se obtiene haciendo una petición de login/autenticación al endpoint de la API. Algunos servicios proporcionan tokens de larga duración en su panel.

P: ¿Puedo usar múltiples tipos de autenticación?
R: No, solo puedes usar un tipo a la vez. Elige el que requiera la API según su documentación.

P: ¿Qué pasa si la petición falla?
R: El nodo captura el error y lo hace disponible en la automatización. Puedes usar nodos condicionales para manejar fallos.

P: ¿Puedo usar variables en la URL?
R: Sí, puedes usar variables: https://api.ejemplo.com/usuarios/{{userId}}/perfil

P: ¿Hay límite en el tamaño del body?
R: Depende del servidor de destino. La mayoría de APIs tienen límites documentados (comúnmente 1-10 MB).

P: ¿Cómo manejo respuestas con paginación?
R: Necesitarás crear un flujo que haga múltiples peticiones, incrementando el parámetro de página en cada iteración.

P: ¿Puedo descargar archivos?
R: Sí, pero ten en cuenta el tamaño y almacenamiento. Para archivos grandes, considera streaming o almacenamiento temporal.