HTTP Activities

Versión: 1.0.0  ·  ID: zoan-packages-http  ·  Autor: Zoan Software

El paquete HTTP permite que tu automatización consuma APIs y servicios web (REST): consultar datos de un sistema, enviar información, integrar dos aplicaciones que se comunican por API. Es la forma más robusta y rápida de integrarse con un sistema cuando este ofrece una API — más fiable que automatizar su interfaz con el navegador.

¿Qué es una API REST?

Una API es la “puerta de servicio” de un sistema: en lugar de usar su pantalla, le envías una petición a una URL y te devuelve datos (normalmente en formato JSON). Cada acción usa un método: GET para leer, POST para crear, PUT/PATCH para actualizar, DELETE para eliminar. No necesitas ser experto: si el sistema te da una documentación de su API, estas actividades la consumen.

La respuesta: ZoanHttpResponse

Todas las actividades devuelven un objeto ZoanHttpResponse con:

Propiedad	Tipo	Descripción
.StatusCode	número	Código HTTP (200, 201, 404…)
.Ok	booleano	true si el código es 2xx (éxito)
.Body	objeto	El cuerpo de la respuesta. Si es JSON, se convierte automáticamente en diccionario/lista, listo para leer con .clave
.Headers	diccionario	Las cabeceras de la respuesta

HTTP GET   url = "https://api.ejemplo.com/clientes/42"   → output: resp
Log   message = = "Nombre: " + resp.Body["nombre"]

Comportamiento ante errores (4xx / 5xx)

Si el servidor responde con un código de error (no 2xx, como 404 o 500), la actividad falla —no continúa— e incluye el código y el cuerpo en el mensaje de error. Por eso, cuando una respuesta de error es esperable (y quieres manejarla, no detenerte), envuelve la petición en un Try / Catch:

Try / Catch   errorVariable = error
 ├─ try:
 │    HTTP GET   url = = "https://api.ejemplo.com/clientes/" + id   → output: resp
 │    ... usar resp.Body ...
 └─ catch:
      Log   level = warning   message = = "El cliente no existe o la API falló: " + error

Autenticación

La mayoría de las APIs requieren autenticación. El parámetro authorization la configura — es un campo de tipo JSON donde indicas el tipo y sus datos. Hay tres tipos soportados:

Tipo	Qué pones en el campo authorization
Bearer (token)	{ "type": "bearer", "token": "..." }
Basic (usuario/clave)	{ "type": "basic", "username": "...", "password": "..." }
API Key	{ "type": "apikey", "header": "X-API-Key", "value": "..." }

No escribas el secreto: usa una credencial

El token, la contraseña o la API key no deben ir en texto plano en el playbook. Dentro del campo JSON puedes usar una expresión que obtenga el valor de una credencial:

authorization = { "type": "bearer", "token": = credential("api-erp").ToPlainText() }

Cabeceras (headers)

El parámetro headers es otro campo JSON: un diccionario de cabeceras extra a enviar.

headers = { "Accept": "application/json", "X-Origen": "zoan-bot" }

Cuerpo (body) y Content-Type

En POST, PUT y PATCH envías un cuerpo (body). Puede ser un objeto (se convierte automáticamente a JSON) o un texto. El contentType por defecto es application/json.

body = { "nombre": = cliente.nombre, "nit": = cliente.nit }

Actividades

Leer y eliminar (sin cuerpo)

Actividad	Tipo	Salida	Qué hace
HTTP GET	http-get	ZoanHttpResponse	Lee/consulta datos de una URL
HTTP DELETE	http-delete	ZoanHttpResponse	Elimina un recurso

Crear y actualizar (con cuerpo)

Actividad	Tipo	Salida	Qué hace
HTTP POST	http-post	ZoanHttpResponse	Crea un recurso o envía datos
HTTP PUT	http-put	ZoanHttpResponse	Reemplaza un recurso completo
HTTP PATCH	http-patch	ZoanHttpResponse	Actualiza parcialmente un recurso

Siguientes pasos

• HTTP GET — la petición más común.
• Tipos de datos › ZoanHttpResponse — leer la respuesta.
• Uso de credenciales — autenticar de forma segura.