Conectar o IFS Cloud: verificar credenciais IAM e listar projeções
Preencha a URL do IFS Cloud, o IAM Client ID, o Client Secret e a IAM Token URL no Integration e teste: o sistema troca um token e lista projeções para provar que as credenciais funcionam. Esta conexão só verifica a conectividade e não sincroniza pedidos, clientes nem estoque.
O conector do IFS Cloud verifica uma única coisa: que um cliente IAM do IFS Cloud (conta de serviço) com acesso à API consiga entrar a partir deste sistema. Um teste aprovado significa que o sistema trocou seu Client ID e Client Secret por um token de acesso na sua IAM Token URL e listou projeções da sua instância do IFS Cloud. Ele não traz pedidos, não traz clientes, não lê nem devolve estoque e não sincroniza nenhum outro documento: as projeções de negócio do IFS diferem por versão e personalização de cada cliente, então nenhuma sincronização de documentos roda nesta conexão. Use-o para provar as credenciais e o endereço da instância antes de preparar qualquer trabalho com documentos para suas projeções específicas.
Pré-requisitos#
- Uma instância do IFS Cloud que você consiga alcançar e seu endereço base, por exemplo https://myserver:48080. Não há um endereço padrão para copiar.
- Um cliente IAM do IFS Cloud (conta de serviço) com acesso à API, e acesso à configuração desse cliente para ler seu Client ID, Client Secret e endpoint de token.
- O endpoint de token do seu próprio IAM, retirado da configuração desse cliente IAM. Cada implantação é diferente, então o valor deve vir da sua própria configuração.
- Se a sua implantação usa um tenant, o valor do tenant; se não usa, você deixará esse campo vazio.
Obter credenciais#
- Abra a configuração do cliente IAM do IFS Cloud (conta de serviço) que tem acesso à API. O Client ID e o Client Secret desta conexão vêm desse cliente.
- Copie o Client ID exatamente como aparece na configuração desse cliente IAM.
- Copie o Client Secret do mesmo cliente IAM. Mantenha-o privado: quem o tiver pode solicitar tokens como essa conta de serviço.
- Na mesma configuração do cliente IAM, copie o endpoint de token e use-o como valor de token_url. Ele segue um formato de token openid-connect, mas o endereço exato é próprio da sua implantação: não copie um endpoint de outra empresa nem de um exemplo.
- Anote ao mesmo tempo o endereço base do seu IFS Cloud e o valor do tenant, se a sua implantação usar um.
Preencher no Integration#
- Abra Integration → Marketplace → IFS → Nova conexão.
- base_url, obrigatório, IFS Cloud URL: o endereço base do seu IFS Cloud, por exemplo https://myserver:48080.
- tenant, opcional, Tenant: preencha só se a sua implantação usar um tenant, por exemplo TENANT1; caso contrário deixe vazio.
- client_id, obrigatório, IAM Client ID: o Client ID do cliente IAM (conta de serviço) com acesso à API. É guardado como segredo.
- client_secret, obrigatório, IAM Client Secret: o Client Secret do mesmo cliente IAM. É um campo do tipo senha e é guardado como segredo.
- token_url, obrigatório, IAM Token URL: o endpoint de token copiado da configuração do seu próprio cliente IAM. Não há um endpoint padrão, então esse valor deve vir do seu próprio IAM do IFS Cloud.
Testar a conexão#
Clique em Testar a conexão. O teste executa duas etapas reais. Primeiro, usa o fluxo OAuth2 client credentials na token_url que você preencheu, trocando client_id e client_secret por um token de acesso. Depois, chama sua instância com esse token para listar projeções — GET {base}/main/ifsapplications/projection/v1/AllProjections.svc/Projections?$top=1 — o que prova ao mesmo tempo que o token funciona e que as projeções podem ser descobertas na sua instância. Uma resposta 200 conta como aprovado. Se base_url estiver ausente, o teste para com MISSING_BASE_URL; se client_id ou client_secret estiver ausente, para com MISSING_CREDENTIALS, e se token_url estiver ausente, para com MISSING_CONFIG, sem enviar nenhuma solicitação. O teste aguarda 12 segundos antes de informar TEST_TIMEOUT.
Mapping / escolher modelo#
Ainda não há um mapping de documentos para escolher nesta conexão. As projeções de negócio do IFS são nomeadas por versão e personalização de cada cliente, então esta conexão não oferece um mapping de pedidos, clientes ou estoque, e não executa um modelo que sincronize documentos. O que você pode conferir após um teste aprovado é a própria lista de projeções: ela mostra quais projeções sua instância expõe, que é o ponto de partida se mais tarde for preparado trabalho com documentos contra suas projeções específicas. Não espere que escolher um mapping faça pedidos ou estoque fluírem: nesta conexão, eles não fluem.
Ativar#
Ative a conexão só depois que o teste aprovar. A ativação guarda esta conexão verificada — o endereço da instância, o tenant opcional e as credenciais IAM — para que a verificação de conectividade possa ser repetida a qualquer momento, por exemplo após a rotação de um cliente IAM ou a mudança do endereço da instância.
O que a ativação não inicia: esta conexão não traz nem envia pedidos, clientes, estoque ou qualquer outro documento, nem na ativação nem por agendamento. Se você precisa sincronizar documentos com o IFS, esse trabalho deve ser preparado contra as projeções de negócio reais da sua instância, partindo da lista de projeções que o teste retorna.
Perguntas frequentes#
O teste para com MISSING_BASE_URL, MISSING_CREDENTIALS ou MISSING_CONFIG
Um campo obrigatório está vazio, e o teste não envia nenhuma solicitação até que todos estejam presentes. MISSING_BASE_URL significa que base_url está vazio, MISSING_CREDENTIALS que client_id ou client_secret está vazio, e MISSING_CONFIG aqui significa que token_url está vazio.
Preencha base_url, client_id, client_secret e token_url a partir da configuração do seu próprio cliente IAM e da sua instância, salve e teste novamente. Adicione tenant só se a sua implantação usar um.
O teste falha com INVALID_CREDENTIALS ou AUTH_FAILED
Seu IAM recusou a troca: o endpoint de token respondeu, mas não aceitou o Client ID e o Client Secret, ou não devolveu nenhum token de acesso. A causa habitual é um segredo copiado de outro cliente IAM, um segredo rotacionado ou uma token_url que pertence a um IAM diferente do cliente.
Abra novamente a configuração desse único cliente IAM e copie client_id, client_secret e token_url juntos do mesmo lugar, para que os três pertençam ao mesmo cliente e ao mesmo IAM. Cole-os novamente por completo e teste de novo.
O teste falha com INVALID_TOKEN
Um token foi obtido, mas sua instância do IFS Cloud não o aceitou na chamada de lista de projeções. Isso aponta para uma incompatibilidade entre o IAM que emitiu o token e a instância em base_url: por exemplo, uma token_url de outra implantação ou um base_url que aponta para outra instância do IFS Cloud.
Verifique se base_url é o endereço da mesma implantação do IFS Cloud cujo IAM emitiu as credenciais, e se token_url foi copiado da configuração do cliente IAM dessa implantação. Corrija o valor incompatível e teste novamente.
O teste falha com MISSING_SCOPE
O token funciona, mas a conta de serviço por trás do cliente IAM não tem permissão para acessar as projeções da instância, então a chamada de lista de projeções é recusada.
No IFS Cloud, conceda a esse cliente IAM (conta de serviço) acesso às projeções e teste novamente com os mesmos valores. Não mude para uma conta de usuário pessoal para contornar: esta conexão foi feita para rodar como a conta de serviço.
O teste informa TEST_TIMEOUT ou CONNECTION_FAILED
A solicitação não terminou. TEST_TIMEOUT significa que nenhuma resposta completa chegou em 12 segundos; CONNECTION_FAILED significa que a solicitação de rede ao endpoint de token ou à instância falhou. Com um endereço auto-hospedado, costuma ser um base_url ou token_url que não pode ser alcançado de fora, ou uma porta que não está aberta.
Abra o base_url e o host do token_url num navegador para confirmar que ambos respondem, verifique se a porta do endereço (por exemplo :48080) está alcançável e teste novamente. Se ambos responderem no navegador e o teste continuar expirando, consulte seu administrador do IFS se o acesso externo ao endpoint de projeções é permitido.
Uma ação com documentos informa ERP_ENDPOINTS_PENDING, ou nada sincroniza após ativar
Esse é o escopo atual desta conexão, não um valor errado. As operações de negócio no IFS — trazer pedidos ou clientes, ler ou enviar estoque — não são executadas por esta conexão, porque os nomes das projeções de negócio diferem por instância de cliente. Um teste aprovado só prova, sempre, que as credenciais IAM funcionam e que as projeções podem ser listadas.
Continue usando a conexão para verificação de conectividade. Para sincronizar documentos, parta da lista de projeções que o teste retorna e prepare o trabalho contra as projeções de Integration reais da sua instância: mudar os cinco valores da conexão não vai ativar a sincronização de documentos.