HTTP Activities

Version: 1.0.0  ·  ID: zoan-packages-http  ·  Author: Zoan Software

The HTTP package allows your automation to consume APIs and web services (REST): query data from a system, send information, integrate two applications that communicate via API. It is the most robust and fastest way to integrate with a system when it offers an API — more reliable than automating its interface with the browser.

What is a REST API?

An API is the “service gateway” of a system: instead of using its screen, you send a request to a URL and it returns data (usually in JSON format). Each action uses a method: GET to read, POST to create, PUT/PATCH to update, DELETE to delete. You don’t need to be an expert: if the system gives you documentation of its API, these activities consume it.

The answer: ZoanHttpResponse

All activities return a ZoanHttpResponse object with:

Property	Type	Description
.StatusCode	number	HTTP code (200, 201, 404…)
.Ok	boolean	true if code is 2xx (success)
.Body	objeto	The body of the response. If JSON, it is automatically converted to dictionary/list, ready to read with .clave
.Headers	diccionario	The response headers

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

Comportamiento ante errores (4xx / 5xx)

If the server responds with an error code (not 2xx, such as 404 or 500), the activity fails—it does not continue—and includes the code and body in the error message. So, when an error response is expected (and you want to handle it, not stop), wrap the request in a 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

Authentication

Most APIs require authentication. The authorization parameter configures it — it is a JSON type field where you indicate the type and its data. There are three types supported:

Type	What to put in the authorization field
Bearer (token)	{ "type": "bearer", "token": "..." }
Basic (username/password)	{ "type": "basic", "username": "...", "password": "..." }
API Key	{ "type": "apikey", "header": "X-API-Key", "value": "..." }

Don’t write down the secret: use a credential

The token, password or API key should not be in plain text in the playbook. Within the JSON field you can use an expression that obtains the value of a credential:

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

Headers

The headers parameter is another JSON field: a dictionary of extra headers to send (header name → value).

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

Body and Content-Type

In POST, PUT and PATCH you send a body (body). It can be an object (automatically converted to JSON) or text. The default contentType is application/json.

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

Activities

Read and delete (no body)

Activity	Type	Output	What it does
HTTP GET	http-get	ZoanHttpResponse	Read/query data from a URL
HTTP DELETE	http-delete	ZoanHttpResponse	Delete a resource

Create and update (with body)

Activity	Type	Output	What it does
HTTP POST	http-post	ZoanHttpResponse	Create a resource or send data
HTTP PUT	http-put	ZoanHttpResponse	Replaces an entire resource
HTTP PATCH	http-patch	ZoanHttpResponse	Partially update a resource

Next steps

• HTTP GET — the most common request.
• Data Types › ZoanHttpResponse — read the response.
• Credential usage — authenticate securely.