RPAAPIs

HTTP

HTTP

El módulo HTTP es responsable de realizar solicitudes a APIs externas y de configurar clientes de API reutilizables, con certificado de cliente (mTLS), URL base, encabezados predeterminados y autenticación OAuth2. Sus métodos pueden accederse conforme al ejemplo abajo:

js

const apiClient = await API.apiClientCreate["v1_0_0"]({
  baseURL: "https://api.ejemplo.com",
});

Métodos

apiClientCreate

Método responsable de configurar un cliente de API reutilizable. El cliente devuelto se indica en el parámetro apiClient del método apiRequest, que pasa a usar su configuración sin necesidad de repetirla en cada solicitud.

js

const apiClient = await API.apiClientCreate["v1_0_0"]({
  pfxPath: "C:\\Certificados\\cliente.pfx",
  passphrase: "contraseña-del-certificado",
  caPath: "C:\\Certificados\\ca.pem",
  baseURL: "https://api.ejemplo.com",
  headers: {
    "Accept": "application/json",
  },
  auth: {
    tokenUrl: "https://auth.ejemplo.com/oauth/token",
    clientId: "mi-client-id",
    clientSecret: "mi-client-secret",
    scope: "lectura escritura",
    credentialsIn: "basic",
  },
});

Parámetros obligatorios

Este método no tiene parámetros obligatorios. Indica solo los grupos de configuración que la API exige.

Parámetros opcionales

• pfxPath:String - espera la ruta del archivo del certificado de cliente en el formato PKCS#12 (.pfx o .p12), usado en las solicitudes con TLS mutuo (mTLS). El archivo debe existir en el dispositivo que ejecuta el robot.
• passphrase:String - espera la contraseña que protege el archivo del certificado.
• caPath:String - espera la ruta del archivo de la autoridad certificadora (CA) que debe aceptarse como confiable al validar el certificado del servidor. Solo se usa junto con pfxPath.
• baseURL:String - espera la URL base de la API. Cuando se indica, el url de las solicitudes hechas con este cliente puede ser una ruta relativa (ej.: /clientes).
• headers:Object - espera un objeto con encabezados enviados en todas las solicitudes hechas con este cliente.
• auth:Object - configura la autenticación OAuth2 con el flujo client credentials. Cuando se indica, el robot obtiene el token de acceso y lo envía en el encabezado Authorization de las solicitudes. Propiedades:
  • tokenUrl:String (obligatorio) - dirección que emite el token de acceso.
  • clientId:String (obligatorio) - identificador del cliente.
  • clientSecret:String (obligatorio) - secreto del cliente.
  • scope:String - alcances solicitados, separados por espacio.
  • audience:String - audiencia (audience) del token, cuando la API lo exige.
  • credentialsIn:String - espera "basic" (las credenciales van en el encabezado Authorization de la solicitud del token) o "body" (van en el cuerpo, como client_id y client_secret). Cuando no se indica, las credenciales van en el encabezado.

Retorno

Devuelve el objeto del cliente de API, que debe almacenarse en una variable (ej.: apiClient) e indicarse en el parámetro apiClient del método apiRequest. Cuando se indica auth, el objeto también guarda el token obtenido (accessToken, tokenType y expiresAt), reutilizado por las solicitudes siguientes.

El método valida la configuración en el momento: si el certificado no puede leerse, la contraseña es incorrecta o el token no puede obtenerse, el robot interrumpe la ejecución con error ya en este método, y no solo en la primera solicitud.

apiRequest

Método responsable de realizar una solicitud HTTP a una API.

js

const apiResponse = await API.apiRequest["v2_0_0"]({
  url: "/clientes",
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: {
    nombre: "Juan",
  },
  apiClient: apiClient,
});

Parámetros obligatorios

• url:String - espera la dirección de la solicitud. Cuando el apiClient tiene baseURL, puede ser una ruta relativa.
• method:String - espera "GET", "POST", "PUT", "DELETE", "OPTIONS", "PATCH", "HEAD", "CONNECT" o "TRACE".

Parámetros opcionales

• headers:Object - espera un objeto con los encabezados de la solicitud. Cuando se usa con apiClient, los encabezados indicados aquí prevalecen sobre los del cliente y sobre el Authorization generado por el token.
• body:Any - espera el cuerpo de la solicitud.
• apiClient:Object - espera el cliente de API devuelto por el método apiClientCreate. Cuando se indica, la solicitud usa el certificado, la URL base, los encabezados predeterminados y el token del cliente. Si la API responde con status 401, el robot obtiene un nuevo token y repite la solicitud una vez.

Retorno

js

actions.apiResponse.status // código de status HTTP de la respuesta (Number)
actions.apiResponse.statusText // texto del status HTTP de la respuesta (String)
actions.apiResponse.response // cuerpo de la respuesta (Any)

Cuando la API responde con un status de error, el método rechaza la promesa con un objeto que tiene las mismas propiedades status, statusText y response. Si no hay respuesta (falla de red), status es 0 y statusText es "Network Error".

La versión v1_0_0 de este método acepta solo url, method, headers y body, y devuelve solo response.