Conectar o Sage X3: verificar a conectividade da Sync API para o seu folder

Reúna os sete valores entregues no onboarding do tenant (ambiente, URL base da Sync API, folder, chave de API do tenant e o par OAuth de identidade da Sage), preencha no Integration e teste: o teste troca um token e sonda seu folder. Esta conexão apenas verifica a conectividade e não sincroniza pedidos, estoque nem clientes.

A conexão do Sage X3 verifica se este sistema consegue alcançar a Sync API de um folder do Sage X3 do seu tenant: ela troca um token de identidade da Sage e lê uma vez o feed de alterações desse folder. Tenha o escopo claro: verificar a conectividade é tudo o que esta conexão faz hoje. Ela não traz pedidos, clientes nem estoque, e não devolve estoque, porque a Sync API é uma interface geral de sincronização em nível de tabela e os nomes de tabela e o mapeamento de colunas de pedidos, estoque e clientes precisam ser confirmados com os metadados do seu próprio folder para a sua implantação. Um teste aprovado só prova que os sete valores abaixo funcionam juntos para esse folder, e nada mais.

Pré-requisitos#

• Uma implantação do Sage X3 cujo tenant tenha a Sync API disponível, e um folder X3 que você queira verificar, por exemplo SEED.
• O pacote de onboarding do tenant dessa implantação: a URL base da Sync API, a chave de API do tenant e o nome exato do folder. Nomes de folder diferenciam maiúsculas, então conserve a grafia exata que você recebeu.
• Um par de credenciais de cliente OAuth de identidade da Sage (um client ID e um client secret) emitido para este tenant, do mesmo onboarding.
• Você sabe qual ambiente está conectando: production ou test. A palavra que você preencher decide qual endereço de token da Sage o teste usa.

Obter credenciais#

1. Peça ao seu administrador do Sage X3, ou à equipe que fez o onboarding do seu tenant, o pacote de onboarding desta implantação. Os sete valores desta conexão vêm desse onboarding: não há nenhuma página de cadastro separada neste guia, e nenhum valor deve ser inventado nem emprestado de outro tenant.
2. Do pacote, anote a URL base da Sync API do seu tenant, no formato https://tenant-host/syncapi, com o host do seu próprio tenant.
3. Anote o nome do folder exatamente como está escrito no pacote, incluindo maiúsculas, por exemplo SEED. O teste depois pergunta por esse folder com esse nome exato.
4. Anote a chave de API do tenant do pacote e mantenha-a em segredo. Durante o teste, ela é enviada como cabeçalho X-API-KEY, junto com o token.
5. Anote o client ID e o client secret OAuth de identidade da Sage do mesmo pacote. Os dois andam juntos como um par: não misture o secret de um par com o ID de outro.
6. Verifique se o pacote pede um token audience. Só se os documentos de onboarding exigirem você precisa desse valor; caso contrário, deixe-o vazio ao preencher.

Preencher no Integration#

1. Abra Integration → Marketplace → Sage X3 → Nova conexão.
2. environment, obrigatório, ambiente: digite a palavra literal production para o seu tenant ativo, ou test para o seu tenant de teste. production usa o endereço de token da Sage https://id.sage.com/oauth/token, e test usa https://id-shadow.sage.com/oauth/token.
3. tenant_base_url, obrigatório, URL base da Sync API do tenant: cole a URL base da Sync API entregue no onboarding, por exemplo https://tenant-host/syncapi, com o host do seu próprio tenant.
4. folder, obrigatório, folder X3: digite o nome do folder exatamente como foi entregue, por exemplo SEED. Este campo diferencia maiúsculas: aqui seed e SEED são nomes distintos.
5. tenant_api_key, obrigatório, chave de API do tenant: cole a chave de API do tenant do pacote de onboarding. É um campo do tipo senha, guardado como segredo e enviado como cabeçalho X-API-KEY durante o teste.
6. client_id, obrigatório, OAuth client ID: cole o client ID do par OAuth de identidade da Sage do mesmo pacote. É um campo do tipo senha e guardado como segredo.
7. client_secret, obrigatório, OAuth client secret: cole o client secret desse mesmo par OAuth. É um campo do tipo senha e guardado como segredo. O ID e o secret devem vir do mesmo par.
8. audience, opcional, token audience: preencha apenas quando os documentos de onboarding do seu tenant pedirem expressamente um token audience. Caso contrário, deixe vazio: o teste pedirá o token sem audience.

Testar a conexão#

Clique em Testar a conexão. O teste primeiro verifica os cinco valores de credencial obrigatórios e para com um resultado nomeado se algum faltar: MISSING_TENANT_BASE_URL, MISSING_FOLDER, MISSING_TENANT_API_KEY, MISSING_CLIENT_ID ou MISSING_CLIENT_SECRET. Depois, executa duas etapas reais dentro de um limite compartilhado de 12 segundos. Primeiro, troca seu client_id e client_secret por um token de identidade da Sage no endereço que o seu environment seleciona, adicionando audience quando você o preencheu. Segundo, pede à Sync API do seu tenant as alterações do seu folder, enviando ao mesmo tempo o token como Authorization: Bearer e sua chave de API do tenant como X-API-KEY. Uma resposta 200 aprova, e o resultado nomeia o folder alcançado. Um 401 é informado como INVALID_TOKEN, um 403 como MISSING_SCOPE e um 404 como NOT_FOUND: veja a FAQ para saber o que cada um significa.

Mapping / escolher modelo#

Nesta conexão não há mapeamento padrão para configurar nem modelo para escolher. A Sync API trabalha em nível de tabela, e os nomes de tabela e as colunas de pedidos, estoque e clientes diferem por folder, então são confirmados com os metadados do seu folder quando uma conexão de dados é preparada para a sua implantação: não é algo para adivinhar nem preencher aqui. Até que essa confirmação por implantação exista para o seu folder, esta conexão fica na verificação de conectividade que ela faz na etapa de teste. Não renomeie tabelas nem campos no Sage X3 para encaixar um mapeamento adivinhado.

Ativar#

Quando o teste passar, ative a conexão para salvá-la no Integration com esses valores verificados, assim o mesmo folder poderá ser verificado de novo depois com as mesmas credenciais. A ativação não inicia nenhum fluxo de dados: por esta conexão não se movem pedidos, clientes nem estoque, em nenhuma direção. Se o seu onboarding emitir depois uma nova chave de API do tenant ou um novo par OAuth, atualize aqui os campos e teste de novo antes de confiar na conexão.

Perguntas frequentes#

O teste falha com INVALID_TOKEN (401)

O lado do token da verificação foi recusado. Ou a própria troca de token rejeitou seu par client_id e client_secret, ou o token devolvido não foi aceito pela Sync API do tenant. As causas habituais são um valor copiado com espaços extras, o secret de um par OAuth usado com o ID de outro, ou uma palavra de environment que envia a troca para o outro endereço de token da Sage, diferente daquele para o qual o par foi emitido.

Copie novamente client_id e client_secret do mesmo pacote de onboarding, sem espaços extras, e confirme que environment corresponde ao tenant para o qual esse par foi emitido: production para o tenant ativo, test para o de teste. Se você preencheu audience, remova-o, a menos que os documentos de onboarding o exijam, e teste de novo.

O teste falha com MISSING_SCOPE (403)

O token foi aceito, mas sua chave de API do tenant não tem permissão para o folder indicado no campo folder. A solicitação chegou à Sync API do seu tenant: o limite é a própria chave, não o endereço nem o par OAuth.

Peça ao seu administrador do Sage X3 que conceda a essa chave de API do tenant acesso a este folder, ou que emita uma chave que o cubra. Aproveite para confirmar o nome do folder, e teste de novo com a chave atualizada.

O teste falha com NOT_FOUND (404)

O folder indicado no campo folder não está habilitado para a Sync API neste tenant, ou o nome não corresponde a nenhum folder lá. Como nomes de folder diferenciam maiúsculas, até o nome certo com a caixa errada é lido como outro folder.

Compare o valor de folder caractere por caractere com o pacote de onboarding, incluindo as maiúsculas. Se a grafia estiver exata, peça ao seu administrador do Sage X3 que habilite esse folder para a Sync API, e teste de novo.

O teste para com MISSING_TENANT_BASE_URL, MISSING_FOLDER, MISSING_TENANT_API_KEY, MISSING_CLIENT_ID ou MISSING_CLIENT_SECRET

O resultado nomeia o campo exato que está vazio. O teste verifica primeiro os campos e não envia nada até que os cinco estejam presentes, porque a sonda ao folder precisa do token e da chave de API juntos.

Preencha o campo nomeado a partir do seu pacote de onboarding (URL base, folder, chave de API do tenant, OAuth client ID ou OAuth client secret), salve e teste de novo. Repita até que nenhum resultado de faltante apareça.

Digitei um endereço de servidor ou uma URL completa em environment e o teste falha

environment não é um campo de endereço. Ele aceita apenas uma de duas palavras literais, e a palavra seleciona qual endereço de token da Sage o teste usa. Qualquer outro conteúdo envia a troca de token para o lugar errado, ou para nenhum lugar utilizável.

Substitua o valor de environment pela única palavra production se esta conexão for para o seu tenant ativo, ou test se for para o seu tenant de teste. Coloque o endereço do servidor em tenant_base_url, e teste de novo.

O teste passou, mas pedidos, estoque ou clientes não são sincronizados

Esse é o escopo atual desta conexão, não uma falha nos seus valores. O teste só prova que a troca de token e a sonda ao folder funcionam. A movimentação de dados ainda não faz parte desta conexão, porque a Sync API é em nível de tabela e as tabelas e colunas de pedidos, estoque e clientes do seu folder primeiro precisam ser confirmadas com os metadados do seu folder para a sua implantação.

Trate um teste aprovado como uma conexão verificada para este folder, e mantenha por enquanto o trabalho de pedidos, estoque e clientes no próprio Sage X3. Quando uma conexão de dados for preparada para a sua implantação, ela partirá desses mesmos valores verificados: você não precisará reunir as credenciais de novo.