Integração REST

O que é a integração REST

A integração REST serve para conectar APIs RESTful como fonte de dados no sistema. Permite executar requisições HTTP (GET, POST, PUT, DELETE) para APIs externas, configurar autenticação, mapear parâmetros de envio (query string e body) e processar os dados retornados, facilitando a comunicação com serviços web externos.

---

Listagem de integrações REST

Toda integração REST precisa estar dentro de uma conexão do tipo REST. Ao acessar uma conexão do tipo REST, estarão listadas todas as integrações daquela conexão. Você pode adicionar uma nova ou inativar integrações já existentes.

---

Adicionar uma nova integração REST

Campos marcados com * são obrigatórios.

ETAPA 1: Configuração Geral (Integração)

Nome da Integração*

Descrição: Nome amigável e único para identificar esta integração.

Exemplos: Consulta Usuários API, Criar Pedido Externo, Atualizar Status Cliente.

Situação*

Descrição: Indica se a integração está ativa ou inativa para uso.

Tipos:

• Ativo: a integração poderá ser utilizada nas execuções, opção preenchida por padrão como ativa.
• Inativo: a integração ficará salva, mas não será utilizada.

Alerta*

Descrição: Define se o sistema deve emitir notificações em caso de indisponibilidade.

Tipos:

• Sim: o usuário recebe uma notificação no e-mail informando.
• Não: não será notificado sobre indisponibilidades.

Descrição

Descrição: Campo opcional para adicionar informações relacionadas à integração que está sendo cadastrada.

Avançar - Clique em Avançar para seguir para etapa 2.

---

ETAPA 2: Configuração de Acesso (Autenticação)

Nesta etapa você define como será realizada a comunicação com a API externa.

Base URL da conexão*

Descrição: URL base da API que será consumida.

Exemplo: https://jsonplaceholder.typicode.com

Path da conexão*

Descrição: Caminho específico do endpoint da API que será acessado.

Exemplo: /posts, /users, /api/v1/produtos

Tipo de autenticação*

Descrição: Define o método de autenticação que será utilizado para acessar a API.

Tipos disponíveis:

• NO AUTHENTICATION
• AUTH BODY
• BASIC AUTH
• BEARER TOKEN
• API KEY

Próximo passo

Após selecionar o tipo de autenticação, configure os detalhes específicos conforme as opções abaixo.

---

Configuração por Tipo de Autenticação

Configurações Específicas da ETAPA 2

Dependendo do tipo de autenticação selecionado acima, você deverá preencher os campos correspondentes. Role para encontrar o tipo que você escolheu e siga as instruções específicas.

Navegação rápida:

• 1. NO AUTHENTICATION - Para APIs públicas
• 2. AUTH BODY - Credenciais no corpo da requisição
• 3. BASIC AUTH - Autenticação com usuário e senha
• 4. BEARER TOKEN - Token de autenticação
• 5. API KEY - Chave de API

1. NO AUTHENTICATION

Não precisa de configurações adicionais, ideal para APIs públicas sem restrições de acesso.

---

2. AUTH BODY

Quando o tipo de autenticação selecionado for AUTH BODY, você terá acesso ao toggle “Usar autenticação da conexão”, que oferece duas formas de configuração:

Modo Manual (Toggle DESLIGADO)

Nesta opção, você configura manualmente as credenciais que serão enviadas no corpo da requisição de autenticação.

Objeto JSON de envio

Adicione os valores correspondentes de chave e valor do objeto que será enviado no body da requisição de autenticação.

Campo	Descrição	Exemplo
JSON Key	Nome da chave do campo de autenticação	username, password, client_id
JSON Value	Valor correspondente que será enviado	admin, senha123

Botão ”⊕ Adicionar”: Permite adicionar múltiplos pares de chave-valor conforme necessário.

Modo Automático (Toggle LIGADO)

Nesta opção, você reutiliza credenciais que foram retornadas de uma conexão/autenticação anterior.

Autenticar como

Selecione de onde virão as credenciais de autenticação.

Opção: Campos de retorno da conexão - Utiliza valores que foram retornados em uma etapa anterior de autenticação.

Mapeamento:

Campo	Descrição
Retorno da conexão (value)	Selecione o campo que contém o valor retornado pela conexão anterior (ex: token, access_token, api_key)
Chave de autenticação (key)	Digite a chave que será utilizada para enviar este valor na autenticação (ex: Authorization, Bearer, token)

Botão ”⊕ Adicionar”: Permite adicionar múltiplos mapeamentos conforme necessário.

Como funciona:

• O sistema utilizará os valores retornados de uma conexão anterior para compor as credenciais de autenticação da requisição atual.
• Útil quando há um fluxo de autenticação em múltiplas etapas ou quando tokens precisam ser renovados.

---

3. BASIC AUTH

Quando o tipo de autenticação selecionado for BASIC AUTH, você terá acesso ao toggle “Usar autenticação da conexão”, que oferece duas formas de configuração:

Modo Manual (Toggle DESLIGADO)

Nesta opção, você configura manualmente as credenciais de usuário e senha que serão enviadas no cabeçalho da requisição.

Username*

Campo de texto onde você deve inserir o nome de usuário para autenticação.

Exemplo: admin, usuario@email.com, api_user

Password*

Campo de texto (oculto) onde você deve inserir a senha correspondente ao usuário.

Formato: String que será codificada em Base64 junto com o username.

Exemplo: senha123, P@ssw0rd!

Como funciona:

• O sistema codificará automaticamente as credenciais no formato Base64 (username:password).
• As credenciais serão enviadas no cabeçalho da requisição como: Authorization: Basic {credenciais_codificadas}

Modo Automático (Toggle LIGADO)

Nesta opção, você reutiliza credenciais que foram retornadas de uma conexão/autenticação anterior.

Autenticar como

Selecione de onde virão as credenciais de autenticação.

Opção: Campos de retorno da conexão - Utiliza valores que foram retornados em uma etapa anterior de autenticação.

Mapeamento:

O sistema permite criar dois mapeamentos separados com as chaves fixas:

Primeiro mapeamento:

• Retorno da conexão (value): Selecione o campo que contém o username retornado pela conexão anterior.
• Chave de autenticação (key): Campo fixo (desabilitado) com valor username

Segundo mapeamento:

• Retorno da conexão (value): Selecione o campo que contém o password retornado pela conexão anterior.
• Chave de autenticação (key): Campo fixo (desabilitado) com valor password

Como funciona:

• O sistema utilizará os valores retornados de uma conexão anterior (username e password) para compor a autenticação Basic.
• As credenciais serão automaticamente codificadas em Base64 e enviadas no cabeçalho.
• Útil quando você precisa obter as credenciais dinamicamente através de uma requisição anterior.

---

4. BEARER TOKEN

Quando o tipo de autenticação selecionado for BEARER TOKEN, você terá acesso ao toggle “Usar autenticação da conexão”, que oferece duas formas de configuração:

Modo Manual (Toggle DESLIGADO)

Nesta opção, você configura manualmente o token que será enviado no cabeçalho da requisição.

Token*

Campo de texto onde você deve inserir o token de autenticação Bearer que será enviado no cabeçalho da requisição.

Formato: Digite o token completo (geralmente uma string longa de caracteres alfanuméricos).

Exemplo: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ

Como funciona:

• O token será enviado no cabeçalho da requisição como: Authorization: Bearer {token}

Modo Automático (Toggle LIGADO)

Nesta opção, você reutiliza um token que foi retornado de uma conexão/autenticação anterior.

Autenticar como

Selecione de onde virá o token de autenticação.

Opção: Campos de retorno da conexão - Utiliza valores que foram retornados em uma etapa anterior de autenticação.

Mapeamento:

Campo	Descrição
Retorno da conexão (value)	Selecione o campo que contém o token retornado pela conexão anterior (ex: token, access_token, bearer_token)
Chave de autenticação (key)	Digite a chave que será utilizada para enviar este valor na autenticação. Normalmente é token ou Authorization

Nota

O sistema adicionará automaticamente o prefixo “Bearer” no cabeçalho da requisição.

Como funciona:

• O sistema utilizará o token retornado de uma conexão anterior para compor o cabeçalho de autenticação da requisição atual.
• O token será enviado no formato: Authorization: Bearer {token}
• Útil quando você precisa primeiro fazer uma requisição de login para obter o token e depois usar esse token em outras requisições.

---

5. API KEY

Quando o tipo de autenticação selecionado for API KEY, você terá acesso ao toggle “Usar autenticação da conexão”, que oferece duas formas de configuração:

Modo Manual (Toggle DESLIGADO)

Nesta opção, você configura manualmente a chave de API que será enviada na requisição.

Token key*

Campo de texto onde você deve inserir o nome da chave que será usada para enviar a API Key (geralmente no cabeçalho ou query string).

Exemplos comuns: api_key, x-api-key, apikey, Authorization

Token value*

Campo de texto onde você deve inserir o valor da API Key fornecida pelo serviço externo.

Formato: String alfanumérica fornecida pelo provedor da API.

Exemplo: sk_live_51abc123def456ghi789jkl012mno345

Modo Automático (Toggle LIGADO)

Nesta opção, você reutiliza uma API Key que foi retornada de uma conexão/autenticação anterior.

Autenticar como

Selecione de onde virá a API Key.

Opção: Campos de retorno da conexão - Utiliza valores que foram retornados em uma etapa anterior de autenticação.

Mapeamento:

Campo	Descrição
Retorno da conexão (value)	Selecione o campo que contém a API Key retornada pela conexão anterior (ex: api_key, key, apikey)
Chave de autenticação (key)	Digite o nome da chave que será utilizada para enviar este valor na autenticação (ex: x-api-key, api_key)

Botão ”⊕ Adicionar”: Permite adicionar múltiplos mapeamentos conforme necessário.

Como funciona:

• O sistema utilizará a API Key retornada de uma conexão anterior para compor a autenticação da requisição atual.
• A chave será enviada conforme o formato especificado (geralmente no cabeçalho da requisição).
• Útil quando você precisa obter a API Key dinamicamente através de uma requisição anterior.

Configuração de Autenticação Concluída

Após configurar o tipo de autenticação adequado para sua API, clique em Avançar para prosseguir para a próxima etapa de mapeamento de campos.

---

ETAPA 3: Conexão de Campos (Mapeamento)

Esta etapa possui duas abas: Envio e Retorno, onde você configurará o mapeamento dos dados que serão enviados para a API e os dados que serão recebidos como resposta.

---

ABA ENVIO

Nesta aba você configura os dados que serão enviados na requisição para a API externa.

1. Query String

Os parâmetros de query string são enviados diretamente na URL da requisição.

Prévia da URL

Mostra em tempo real como ficará a URL completa com os parâmetros mapeados.

Formato: A URL base + path + parâmetros entre chaves duplas {{NOME_CAMPO}}

Exemplo: https://jsonplaceholder.typicode.com/posts?id={{ID USER}}

Tabela de mapeamento

A tabela possui 3 colunas para configurar cada parâmetro:

Query string	Campo do sistema	Tipo
Nome do parâmetro que aparecerá na URL	Campo do sistema que fornecerá o valor	Tipo de dado

Query string:

• Nome do parâmetro que será adicionado à URL (ex: id, page, limit, status)
• Este nome aparecerá na URL após o ? ou &

Campo do sistema:

• Selecione qual campo do sistema fornecerá o valor para este parâmetro
• O valor deste campo será substituído no placeholder da URL durante a execução
• Você pode remover o campo selecionado clicando no ×

Tipo:

• Selecione o tipo de dado do campo (int, string, boolean, date, etc.)
• Isso garante que o valor seja enviado no formato correto

Botões de ação:

• ⊕ Adicionar: Adiciona uma nova linha para mapear outro parâmetro de query string
• 🗑️ (Lixeira): Remove a linha de mapeamento

Exemplo prático:

Query string: id
Campo do sistema: ID USER
Tipo: int
Resultado na URL: ?id={{ID USER}} → Durante a execução será ?id=123

---

2. Body

O corpo da requisição contém dados estruturados que serão enviados (usado principalmente em métodos POST e PUT).

Json Schema

Botão para visualizar ou definir a estrutura JSON que será enviada no corpo da requisição.

Clique em ⊕ Json Schema para expandir e ver/editar o schema

Modal “Adicionar Json Schema”:

• Título: Adicionar Json Schema
• Descrição: Digite ou cole o Json Schema abaixo para preenchimento dos campos.
• Campo de texto: Área grande para digitar ou colar a estrutura JSON
• Funcionalidade: Permite definir previamente a estrutura JSON que será enviada, facilitando o preenchimento automático dos mapeamentos
• Botão “Adicionar”: Confirma e adiciona o schema definido

Exemplo de schema:

{
  "nome": "string",
  "ativo": "boolean",
  "idade": "number",
  "endereco": {
    "rua": "string",
    "cidade": "string"
  }
}

Tabela de mapeamento do body

A tabela possui 3 colunas para configurar os dados do body:

Campo de origem	Tipo	Campo de destino
Campo do sistema de origem	Tipo de dado	Nome do campo no JSON

Campo de origem:

• Selecione qual campo do sistema fornecerá o valor
• Este é o campo de onde os dados serão retirados

Tipo:

• Selecione o tipo de dado (string, boolean, int, object, array, etc.)
• Define como o valor será formatado no JSON

Campo de destino:

• Digite o nome da propriedade que aparecerá no JSON enviado
• Este será o nome da chave no objeto JSON
• Exemplo: se digitar teste, o JSON terá "teste": valor

Botões de ação:

• ⊕ Adicionar: Adiciona uma nova linha para mapear outro campo do body
• 🗑️ (Lixeira): Remove a linha de mapeamento

Exemplo prático:

Campo de origem: Nome Completo PEC
Tipo: boolean
Campo de destino: teste
Resultado no JSON: { "teste": true }

Observação

• Para métodos GET e DELETE, normalmente não é necessário configurar o Body
• Para métodos POST e PUT, o Body é obrigatório

---

ABA RETORNO

Nesta aba você configura como os dados retornados pela API serão mapeados para os campos do sistema.

1. Response

Mapeia os dados de sucesso retornados pela API quando a requisição é bem-sucedida.

Json Schema

Botão para visualizar ou definir a estrutura JSON esperada como resposta da API.

Clique em ⊕ Json Schema para abrir o modal de configuração

Modal “Adicionar Json Schema”:

• Título: Adicionar Json Schema
• Descrição: Digite ou cole o Json Schema abaixo para preenchimento dos campos.
• Campo de texto: Área grande para digitar ou colar a estrutura JSON esperada como resposta
• Funcionalidade: Permite definir previamente a estrutura JSON que a API retornará, facilitando o mapeamento correto dos campos
• Botão “Adicionar”: Confirma e adiciona o schema definido

Exemplo de schema:

{
  "userId": 1,
  "id": 101,
  "title": "string",
  "body": "string",
  "success": true
}

Tabela de mapeamento do Response

A tabela possui 3 colunas para configurar o mapeamento da resposta:

Campo de origem	Campo de destino	Tipo
Nome do campo no JSON retornado	Campo do sistema que receberá o valor	Tipo de dado

Campo de origem:

• Digite o nome exato do campo que vem no JSON de resposta da API
• Exemplo: userId, id, title, body, name, email
• Este campo deve corresponder exatamente ao nome da propriedade no JSON retornado

Campo de destino:

• Selecione qual campo do sistema receberá e armazenará este valor
• O valor retornado pela API será gravado neste campo durante a execução da política

Tipo:

• Selecione o tipo de dado do campo (int, string, object, array, boolean, etc.)
• Garante que o valor seja processado corretamente

Botões de ação:

• ⊕ Adicionar: Adiciona uma nova linha para mapear outro campo da resposta
• 🗑️ (Lixeira): Remove a linha de mapeamento

Exemplo prático:

Se a API retorna: { "userId": 1, "id": 101, "title": "Teste", "body": "Conteúdo" }

Mapeamentos possíveis:

• Campo de origem: userId → Campo de destino: ID USER → Tipo: int
• Campo de origem: id → Campo de destino: ID USER → Tipo: int
• Campo de origem: title → Campo de destino: Nome Completo PEC → Tipo: string
• Campo de origem: body → Campo de destino: endereço → Tipo: object

---

2. Erro

Mapeia os dados de erro retornados pela API quando a requisição falha. É possível configurar múltiplas seções de erro, cada uma associada a um código de status HTTP específico.

Estrutura:

• A seção de Erro pode ter múltiplas subsecções, cada uma representando um tratamento para um código de status diferente
• Cada subsecção possui sua própria tabela de mapeamento e botão “Status Code”

Tabela de mapeamento

Cada seção de erro possui uma tabela com 3 colunas:

Campo de origem	Campo de destino	Tipo
Nome do campo no JSON de erro	Campo do sistema que receberá a mensagem de erro	Tipo de dado

Campo de origem:

• Digite o nome do campo que vem no JSON de erro retornado pela API
• Exemplo: error, message, errorMessage, errorCode, erro_200

Campo de destino:

• Selecione qual campo do sistema receberá a informação de erro
• Útil para armazenar mensagens de erro e fazer tratamento posterior

Tipo:

• Selecione o tipo de dado do campo de erro (string, int, boolean, object, etc.)
• Garante que o valor de erro seja processado corretamente

Botões de ação em cada seção:

• ⊕ Adicionar: Adiciona uma nova linha de mapeamento dentro da mesma seção de erro
• 🗑️ Status Code (vermelho): Remove a configuração do código de status da seção “container” atual
• 🗑️ (Lixeira): Remove a linha de mapeamento

Adicionar nova seção de erro:

⊕ Status Code (botão azul grande): Localizado no final da aba, adiciona uma nova seção de erro para configurar tratamento de outro código de status HTTP

Ao clicar, será criada uma nova subsecção onde você pode:

• Definir qual código de status será tratado (ex: 400, 404, 500)
• Mapear os campos de erro específicos desse código
• Configurar tratamento individualizado por tipo de erro

Exemplo prático:

Seção 1 - Status Code 400 (Bad Request):

• Campo de origem: message → Campo de destino: Mensagem de Erro

Seção 2 - Status Code 404 (Not Found):

• Campo de origem: erro_200 → Campo de destino: erro_front

Seção 3 - Status Code 500 (Internal Server Error):

• Campo de origem: error → Campo de destino: Log de Erros

---

Observações importantes

Dicas de Mapeamento

• Certifique-se de mapear todos os campos necessários tanto no envio quanto no retorno
• O sistema substituirá automaticamente os placeholders (ex: {{ID USER}}) pelos valores dos campos mapeados durante a execução
• Verifique se os nomes dos campos de origem correspondem exatamente aos nomes retornados pela API (respeitando maiúsculas/minúsculas)
• Configure diferentes tratamentos de erro para diferentes códigos de status HTTP para ter um controle mais granular sobre as falhas

Finalizar - Após configurar todos os mapeamentos de envio e retorno:

• Clique em Voltar caso queira revisar as etapas anteriores
• Clique em Cadastrar para concluir a criação da integração

---

Duplicar Integração

Para agilizar a criação de integrações com configurações semelhantes, a plataforma Wisedit oferece a funcionalidade de duplicar uma integração já existente. Este recurso economiza tempo ao evitar que você precise preencher novamente todas as informações de uma integração.

Como duplicar uma integração

1. No menu, acesse a listagem de Conexões na barra lateral.
2. Na lista, acesse a conexão do tipo REST desejada.
3. Dentro da listagem de integrações, clique no ícone de cópia, localizado ao lado do ícone de edição (lápis).
4. Ao clicar no ícone, o formulário de Adicionar nova integração será aberto, já preenchido com todas as informações da integração original utilizada como referência.

---

Editar Integração

Após configurar suas integrações, você pode precisar atualizar informações. O processo de edição é simples e direto.

Para editar uma integração, siga estes passos

1. Acesse a tela de Conexões.
2. Localize na lista a conexão do tipo REST desejada.
3. Dentro da conexão, selecione a integração que deseja editar.
4. Clique no ícone de edição (formato de lápis).

Observações

Atenção ao Editar

• Caso seja alterado o método de integração (GET, POST, PUT, DELETE), pode ser necessário reconfigurar os mapeamentos de envio e retorno.
• Alterações na Base URL ou Path não afetam o mapeamento existente.
• Se houver mudança nos campos de autenticação, verifique se as credenciais continuam válidas.

Em caso de dúvida sobre o preenchimento: Consulte o tópico de Adicionar Integração nesta documentação. Os campos e suas regras de preenchimento são os mesmos quando adiciona uma nova integração.