Conectores

O que são os conectores do iPaaS, para que servem e como cadastrá-los.

---

Um conector é o cadastro de uma API REST externa que o iPaaS pode chamar em seu nome: o endereço da API, a forma de autenticação e os endpoints (recursos) que ela oferece. Você cadastra o conector uma vez e depois o reaproveita em quantas integrações quiser.

Para que servem

Hoje os conectores são usados pelo template Busca de Produtos. Nesse template, é o ME que chama o provedor do catálogo (por exemplo, um distribuidor ou marketplace) para buscar produtos e ofertas. O conector informa ao iPaaS onde e como fazer essa chamada.

❗️ Atenção

Uma integração de Busca de Produtos não pode ser testada nem publicada sem um conector. Cadastre o conector antes, ou pelo atalho Criar novo connector na etapa Parâmetros do assistente.

Os templates Criação de Documentos (Inbound) e Busca de Documentos (Outbound) não usam conectores.

Cadastrando um conector

No Partner's Portal, acesse Integrações > Configurações > Conectores e clique em Novo conector. O cadastro tem duas etapas: Informações e Recursos.

Etapa 1: Informações

Campo	Descrição
Nome do conector	Nome para identificar o provedor, por exemplo "Grainger BR". Deve ter entre 3 e 128 caracteres.
URL base	Endereço base da API do provedor, por exemplo https://api.provedor.com/v1. Os caminhos dos recursos são adicionados a partir dela.
Descrição	Texto livre, opcional.
Autenticação	Como o iPaaS se autentica no provedor. Veja a tabela abaixo.

Tipos de autenticação

Tipo	Quando usar	O que informar
Sem autenticação	Endpoint público.	Nada.
API Key	O provedor espera uma chave fixa.	Local da chave (Header ou Parâmetro de query), Nome da chave (ex.: X-API-Key) e Valor da chave.
Bearer Token	O provedor aceita um token fixo (JWT estático ou token de longa duração).	Token. O iPaaS envia Authorization: Bearer {token}.
Basic Auth	O provedor usa usuário e senha.	Usuário e Senha.
OAuth 2.0	O provedor emite tokens por client credentials.	URL do token, Client ID, Client secret e Escopo (opcional). Em Avançado: Enviar credenciais via (corpo da requisição ou header Basic Auth), Intervalo de renovação do token (quantos segundos antes de expirar o token é renovado; padrão 60) e Parâmetros adicionais da requisição (ex.: audience, resource).

📘 Nota

As credenciais do provedor são armazenadas de forma criptografada e nunca são exibidas de novo. Ao editar o conector, os campos aparecem mascarados. Para trocar um valor, clique em Alterar credencial.

Testando a autenticação

Clique em Testar Autenticação para que o iPaaS faça uma requisição de teste com a URL base e as credenciais informadas. Se tudo estiver certo, é exibida a mensagem 200 OK — Conexão bem-sucedida. Se não, confira a URL e as credenciais.

• O teste pode ser feito antes de salvar o conector.
• Ao editar um conector já salvo, os campos que você não alterar são testados com os valores salvos. Se você trocar o host da URL base (ou da URL do token, no OAuth 2.0), é preciso informar de novo todas as credenciais. Isso evita que uma credencial salva seja enviada para outro servidor.

Etapa 2: Recursos

Um recurso é um endpoint do provedor que o iPaaS pode chamar. Adicione um recurso para cada endpoint que as suas integrações vão usar, por exemplo "buscar produtos" e "detalhe do produto".

Campo	Descrição
Nome do recurso	Ex.: "Busca de Produtos".
Caminho	Caminho relativo à URL base, fixo. Deve começar com /, por exemplo /products/search.
Métodos HTTP	GET, POST, PUT, PATCH ou DELETE. Cada combinação de método e caminho é um recurso único no conector.
Descrição	Opcional.

Como o iPaaS envia os parâmetros da busca ao provedor:

• Recursos GET e DELETE: os parâmetros vão na query string (ex.: ?searchTerm={termo}&pageNumber={página}&pageSize={tamanho}).
• Recursos POST, PUT e PATCH: os parâmetros vão no corpo JSON da requisição.

O Caminho é enviado exatamente como foi cadastrado: o iPaaS não substitui variáveis no caminho (como /products/{id}). Os parâmetros da busca sempre seguem na query string ou no corpo, como descrito acima. Cadastre caminhos fixos.

Mapeamento de requisição

Cada operação da Busca de Produtos envia ao provedor um conjunto fixo de parâmetros do ME:

Operação	Parâmetros enviados pelo ME
Listar (getAll)	searchTerm (termo buscado), pageNumber (página, a partir de 1), pageSize (itens por página)
Buscar por ID (getById)	productId (código do produto no provedor)
Buscar ofertas (getOffers)	productId (código do produto no provedor)

Se o provedor espera esses dados com outros nomes ou em outra estrutura, configure o Mapeamento de requisição do recurso:

1. Em Operação, escolha a operação que usará este recurso.
2. Em Exemplo de requisição, cole um exemplo do que o provedor espera receber:
   • para recursos POST/PUT/PATCH, um corpo JSON;
   • para recursos GET/DELETE, uma URL ou query string.
3. Clique em Gerar mapeamento. A IA liga os parâmetros do ME (Origem (ME)) aos campos do provedor (Destino (Provider)).
4. Revise as ligações e a prévia e salve o recurso.

Exemplo: o provedor espera um corpo com a palavra buscada em searchQuery e um bloco fixo de identificação do cliente.

{
  "clientDetails": { "clientId": "192533129MEP", "accountNumber": "800014904" },
  "searchQuery": "drill"
}

Depois do mapeamento, o ME envia searchTerm como searchQuery. Os valores que não vêm do ME, como clientDetails, podem ser preenchidos como valor fixo.

A primeira página é sempre pageNumber = 1. Se o provedor numera as páginas a partir de 0, use pageNumber - 1 no mapeamento de requisição. O iPaaS não impõe um valor máximo de pageSize: ele repassa o valor recebido.

Exemplo com query string: para ?productRegion=US&locale=en_US&keyword=drill&pageNumber=1, keyword recebe o searchTerm, pageNumber recebe o pageNumber, e productRegion/locale ficam como valores fixos.

Se o provedor exige um único código dentro de uma lista, por exemplo "productCodes": ["3EB46"], o iPaaS coloca o productId dentro da lista automaticamente.

📘 Nota

Se o provedor já aceita os nomes do ME (searchTerm, pageNumber, pageSize, productId), você não precisa configurar o mapeamento de requisição. Os parâmetros são enviados como estão.

Usando o conector em uma integração

Na etapa Parâmetros da integração de Busca de Produtos:

1. Selecione o Connector.
2. Em Operações, escolha qual Recurso do conector atende cada operação: Buscar todos (getAll) e Buscar por ID (getById) são obrigatórias, e Buscar ofertas (getOffers) é opcional.

Veja o passo a passo completo em Busca de Produtos.

Editando e excluindo

• Editar: em Integrações > Configurações > Conectores, abra o conector e salve as alterações.
• Excluir: a exclusão é irreversível. Um conector em uso não pode ser excluído: se alguma integração, em qualquer status (inclusive rascunho ou suspensa), usa o conector, a exclusão é bloqueada e aparece a mensagem "Este conector está em uso por integrações e não pode ser excluído.". Para excluir, troque o conector nessas integrações ou exclua-as antes.

❗️ Atenção

Alterações na URL base, na autenticação e no mapeamento de requisição de um conector passam a valer imediatamente nas próximas execuções de todas as integrações que usam o conector, sem novo teste e sem mudar o status delas.

Já alterar o método ou o caminho de um recurso não atualiza as integrações existentes: elas continuam chamando o caminho antigo e deixam de usar o mapeamento de requisição do recurso. Nesse caso, refaça a etapa Parâmetros de cada integração que usa o recurso.

Limitações

• Somente APIs REST com JSON são suportadas.
• A autenticação OAuth 2.0 suporta apenas o fluxo client credentials.
• Hoje os conectores só são usados pelo template Busca de Produtos.