Como cadastrar uma integração REST

A tela de Integrações é onde você cadastra e gerencia as conexões entre a cVortex e APIs externas. Cada integração reúne os dados de conexão, o método de autenticação e as operações que serão executadas.

Para acessar, siga o caminho: Configurações > Geral > Integrações.

Nessa tela também está disponível o botão Gerenciar Chaves, que permite cadastrar Chaves Seguras para proteger tokens, senhas e API keys utilizados nas integrações. Saiba mais na página [Chaves Seguras].

A tela de integrações é dividida em 3 sessões:

Dados da Integração
Informe:
- Nome da conexão.
- Tipo da integração.
- URL da API.
Configurações de Autenticação JWT (opcional)
Preencha os dados necessários para autenticação, caso necessário.
Operação
Configure métodos de requisição (GET, POST, PUT, DELETE) para manipular os dados da API. É possível adicionar várias operações para a mesma integração.

Primeiro Passo - Informações da Integração

Para acessar e configurar uma integração, siga os passos: acesse Configurações > Geral > Integrações e clique no botão Adicionar .

Na tela de Informações da Integração Externa preencha os dados da integração:

Nome da Integração
Insira um nome descritivo para a integração, por exemplo, se estiver realizando uma consulta para recuperar dados do cliente, coloque um nome que facilite a identificação dessa consulta, como: Dados do Cliente.
Tipo de integração
Escolha REST.
URL Base
Insira uma URL base que sirva como ponto de acesso principal para a API que você está integrando.

Você deve fornecer as informações do cabeçalho da integração conforme as especificações da API desejada, veja um exemplo abaixo:

// URL: 
"http://api.tenant.com/v1/"

// Autentication:
"http://api.tenant.com/v1/auth"

// Método HTTP: 
"GET"

// Headers
{    "Content-type": "application/json"
}
// Request Body:
{    "username": "tenant-admin",    "password": "*******"
}
// Response
{    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}

Escolha o método de autenticação

Tipo de Autenticação

Na plataforma é possível configurar os seguintes tipos de autenticação:

Tipo de Autenticação	Definições
Autenticação JWT	Utilizado em situações em que a autenticação ocorre por meio de um Token JWT, esse token deve ser gerado através de um endpoint da API REST. Nesse processo, o usuário e a senha são fornecidos, e em resposta, o endpoint fornece um token de acesso que deverá ser usado nas transações subsequentes.
Autenticação com Token Fixo	Assim como na Autenticação JWT, esse método de autenticação requer o envio de um Token para acessar os recursos da API. No entanto, ao contrário da geração dinâmica de tokens antes de cada operação, aqui é necessário fornecer um token fixo previamente obtido. Esse token pode ser incluído no corpo ou no título da operação REST. Para maior segurança, o token pode ser informado por meio de uma referência de Chave Segura no formato `@[chave]`.
Sem autenticação	Normalmente trata-se de APIs públicas que não exigem autenticação.

Atenção
Você deve configurar apenas um método de autenticação para cada integração.

Mensagens de erro

Principais Erros e Suas Descrições

Mensagem	Descrição
Erro 400	Solicitação inválida: Indica que a solicitação do cliente possui parâmetros inválidas ou ausentes.
Erro 401	Não autorizado: Significa que o cliente não possui autorização para acessar o recurso solicitado. Isso pode ocorrer devido a uma falha de autenticação ou falta de credenciais específicas.
Erro 403	O cliente possui autenticação válida, mas não tem permissão para acessar o recurso.
Erro 404	Não encontrado: Indica que o recurso solicitado não foi encontrado no servidor
Erro 405	Método não permitido: O servidor não permite o método HTTP utilizado na solicitação (por exemplo, tente usar POST em um recurso que só permite GET).
Erro 500	Erro interno do servidor: Indica um erro no servidor, geralmente devido a uma falha no processamento da solicitação.
Erro 502	Gateway incorreto: Podem ocorrer situações de proxy ou balanceamento de carga quando o servidor de origem não responde corretamente.
Erro 503	Serviço indisponível: O servidor está temporariamente indisponível devido a sobrecarga ou manutenção.
Erro 504	Gateway Timeout: Indica que o servidor de gateway não obteve uma resposta no tempo do servidor de origem.
Erros de validação de entrada	Esses erros ocorrem quando os dados enviados na solicitação não atendem aos critérios de validação definidos pelo servidor.
Erros personalizados	Além dos códigos de erro padrão, muitas APIs RESTful também retornam mensagens de erro personalizadas que fornecem detalhes adicionais sobre o problema específico que ocorreu.

Segundo passo: cadastrar as Integração por JWT.