RPAAPIs

HTTP

HTTP

O módulo HTTP é responsável por fazer requisições a APIs externas e por configurar clientes de API reutilizáveis, com certificado de cliente (mTLS), URL base, cabeçalhos padrão e autenticação OAuth2. Seus métodos podem ser acessados conforme o exemplo abaixo:

js

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

Métodos

apiClientCreate

Método responsável por configurar um cliente de API reutilizável. O cliente retornado é informado no parâmetro apiClient do método apiRequest, que passa a usar a configuração dele sem precisar repeti-la em cada requisição.

js

const apiClient = await API.apiClientCreate["v1_0_0"]({
  pfxPath: "C:\\Certificados\\cliente.pfx",
  passphrase: "senha-do-certificado",
  caPath: "C:\\Certificados\\ca.pem",
  baseURL: "https://api.exemplo.com.br",
  headers: {
    "Accept": "application/json",
  },
  auth: {
    tokenUrl: "https://auth.exemplo.com.br/oauth/token",
    clientId: "meu-client-id",
    clientSecret: "meu-client-secret",
    scope: "leitura escrita",
    credentialsIn: "basic",
  },
});

Parâmetros obrigatórios

Este método não possui parâmetros obrigatórios. Informe apenas os grupos de configuração que a API exige.

Parâmetros opcionais

• pfxPath:String - espera o caminho do arquivo do certificado de cliente no formato PKCS#12 (.pfx ou .p12), usado nas requisições com TLS mútuo (mTLS). O arquivo precisa existir no dispositivo que executa o robô.
• passphrase:String - espera a senha que protege o arquivo do certificado.
• caPath:String - espera o caminho do arquivo da autoridade certificadora (CA) que deve ser aceita como confiável ao validar o certificado do servidor. Só é usado junto com pfxPath.
• baseURL:String - espera a URL base da API. Quando informada, o url das requisições feitas com este cliente pode ser um caminho relativo (ex.: /clientes).
• headers:Object - espera um objeto com cabeçalhos enviados em todas as requisições feitas com este cliente.
• auth:Object - configura a autenticação OAuth2 com o fluxo client credentials. Quando informado, o robô obtém o token de acesso e o envia no cabeçalho Authorization das requisições. Propriedades:
  • tokenUrl:String (obrigatório) - endereço que emite o token de acesso.
  • clientId:String (obrigatório) - identificador do cliente.
  • clientSecret:String (obrigatório) - segredo do cliente.
  • scope:String - escopos solicitados, separados por espaço.
  • audience:String - público (audience) do token, quando a API exige.
  • credentialsIn:String - espera "basic" (as credenciais vão no cabeçalho Authorization da requisição do token) ou "body" (vão no corpo, como client_id e client_secret). Quando não informado, as credenciais vão no cabeçalho.

Retorno

Retorna o objeto do cliente de API, que deve ser armazenado em uma variável (ex.: apiClient) e informado no parâmetro apiClient do método apiRequest. Quando auth é informado, o objeto também guarda o token obtido (accessToken, tokenType e expiresAt), reaproveitado pelas requisições seguintes.

O método valida a configuração na hora: se o certificado não puder ser lido, a senha estiver errada ou o token não puder ser obtido, o robô interrompe a execução com erro já neste método, e não apenas na primeira requisição.

apiRequest

Método responsável por fazer uma requisição HTTP a uma API.

js

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

Parâmetros obrigatórios

• url:String - espera o endereço da requisição. Quando o apiClient tem baseURL, pode ser um caminho relativo.
• method:String - espera "GET", "POST", "PUT", "DELETE", "OPTIONS", "PATCH", "HEAD", "CONNECT" ou "TRACE".

Parâmetros opcionais

• headers:Object - espera um objeto com os cabeçalhos da requisição. Quando usado com apiClient, os cabeçalhos informados aqui prevalecem sobre os do cliente e sobre o Authorization gerado pelo token.
• body:Any - espera o corpo da requisição.
• apiClient:Object - espera o cliente de API retornado pelo método apiClientCreate. Quando informado, a requisição usa o certificado, a URL base, os cabeçalhos padrão e o token do cliente. Se a API responder com status 401, o robô obtém um novo token e repete a requisição uma vez.

Retorno

js

actions.apiResponse.status // código de status HTTP da resposta (Number)
actions.apiResponse.statusText // texto do status HTTP da resposta (String)
actions.apiResponse.response // corpo da resposta (Any)

Quando a API responde com um status de erro, o método rejeita a promise com um objeto que tem as mesmas propriedades status, statusText e response. Se não houver resposta (falha de rede), status é 0 e statusText é "Network Error".

A versão v1_0_0 deste método aceita apenas url, method, headers e body, e retorna somente response.