Conectar Sage X3: verificar la conectividad de Sync API para su folder

Reúna los siete valores entregados en el onboarding del tenant (entorno, URL base de Sync API, folder, clave API del tenant y el par OAuth de identidad de Sage), complételos en Integration y pruebe: la prueba intercambia un token y sondea su folder. Esta conexión solo verifica la conectividad y no sincroniza pedidos, inventario ni clientes.

La conexión de Sage X3 verifica que este sistema pueda llegar a la Sync API de un folder de Sage X3 de su tenant: intercambia un token de identidad de Sage y lee una vez el feed de cambios de ese folder. Tenga claro el alcance: verificar la conectividad es todo lo que esta conexión hace hoy. No trae pedidos, clientes ni inventario, y no devuelve inventario, porque Sync API es una interfaz general de sincronización a nivel de tabla y los nombres de tabla y el mapeo de columnas de pedidos, inventario y clientes deben confirmarse con los metadatos de su propio folder para su despliegue. Una prueba aprobada solo demuestra que los siete valores siguientes funcionan juntos para ese folder, y nada más.

Requisitos previos#

• Un despliegue de Sage X3 cuyo tenant tenga Sync API disponible, y un folder X3 que quiera verificar, por ejemplo SEED.
• El paquete de onboarding del tenant de ese despliegue: la URL base de Sync API, la clave API del tenant y el nombre exacto del folder. Los nombres de folder distinguen mayúsculas, así que conserve la ortografía exacta que le entregaron.
• Un par de credenciales de cliente OAuth de identidad de Sage (un client ID y un client secret) emitido para este tenant, del mismo onboarding.
• Sabe qué entorno está conectando: production o test. La palabra que complete decide qué dirección de token de Sage usa la prueba.

Obtener credenciales#

1. Pida a su administrador de Sage X3, o al equipo que hizo el onboarding de su tenant, el paquete de onboarding de este despliegue. Los siete valores de esta conexión vienen de ese onboarding: no hay ninguna página de registro separada en esta guía, y ningún valor debe inventarse ni tomarse de otro tenant.
2. Del paquete, anote la URL base de Sync API de su tenant, con la forma https://tenant-host/syncapi, con el host de su propio tenant.
3. Anote el nombre del folder exactamente como está escrito en el paquete, mayúsculas incluidas, por ejemplo SEED. La prueba luego pregunta por ese folder con este nombre exacto.
4. Anote la clave API del tenant del paquete y manténgala en secreto. Durante la prueba se envía como encabezado X-API-KEY, junto con el token.
5. Anote el client ID y el client secret OAuth de identidad de Sage del mismo paquete. Los dos van juntos como un par: no mezcle el secret de un par con el ID de otro.
6. Compruebe si el paquete pide un token audience. Solo si sus documentos de onboarding lo exigen necesita ese valor; en caso contrario, déjelo vacío al completar.

Completar en Integration#

1. Abra Integration → Marketplace → Sage X3 → Nueva conexión.
2. environment, obligatorio, entorno: escriba la palabra literal production para su tenant en vivo, o test para su tenant de prueba. production usa la dirección de token de Sage https://id.sage.com/oauth/token, y test usa https://id-shadow.sage.com/oauth/token.
3. tenant_base_url, obligatorio, URL base de Sync API del tenant: pegue la URL base de Sync API entregada en el onboarding, por ejemplo https://tenant-host/syncapi, con el host de su propio tenant.
4. folder, obligatorio, folder X3: escriba el nombre del folder exactamente como fue entregado, por ejemplo SEED. Este campo distingue mayúsculas: aquí seed y SEED son nombres distintos.
5. tenant_api_key, obligatorio, clave API del tenant: pegue la clave API del tenant del paquete de onboarding. Es un campo de tipo contraseña, se guarda como secreto y se envía como encabezado X-API-KEY durante la prueba.
6. client_id, obligatorio, OAuth client ID: pegue el client ID del par OAuth de identidad de Sage del mismo paquete. Es un campo de tipo contraseña y se guarda como secreto.
7. client_secret, obligatorio, OAuth client secret: pegue el client secret de ese mismo par OAuth. Es un campo de tipo contraseña y se guarda como secreto. El ID y el secret deben venir del mismo par.
8. audience, opcional, token audience: complete esto solo cuando los documentos de onboarding de su tenant pidan expresamente un token audience. En caso contrario, déjelo vacío: la prueba pedirá el token sin audience.

Probar la conexión#

Haga clic en Probar la conexión. La prueba primero comprueba los cinco valores de credencial obligatorios y se detiene con un resultado nombrado si falta uno: MISSING_TENANT_BASE_URL, MISSING_FOLDER, MISSING_TENANT_API_KEY, MISSING_CLIENT_ID o MISSING_CLIENT_SECRET. Después ejecuta dos pasos reales dentro de un límite compartido de 12 segundos. Primero, intercambia su client_id y client_secret por un token de identidad de Sage en la dirección que selecciona su environment, añadiendo audience cuando lo completó. Segundo, pide a la Sync API de su tenant los cambios de su folder, enviando a la vez el token como Authorization: Bearer y su clave API del tenant como X-API-KEY. Una respuesta 200 aprueba, y el resultado nombra el folder alcanzado. Un 401 se informa como INVALID_TOKEN, un 403 como MISSING_SCOPE y un 404 como NOT_FOUND: vea la FAQ para saber qué significa cada uno.

Mapping / elegir plantilla#

En esta conexión no hay un mapping estándar que configurar ni una plantilla que elegir. Sync API trabaja a nivel de tabla, y los nombres de tabla y las columnas de pedidos, inventario y clientes difieren según el folder, así que se confirman con los metadatos de su folder cuando se prepara una conexión de datos para su despliegue: no es algo que adivinar ni que completar aquí. Hasta que esa confirmación por despliegue exista para su folder, esta conexión se queda en la comprobación de conectividad que hace en el paso de prueba. No renombre tablas ni campos en Sage X3 para ajustarlos a un mapping adivinado.

Activar#

Cuando la prueba pase, active la conexión para guardarla en Integration con estos valores verificados, así el mismo folder podrá comprobarse de nuevo más tarde con las mismas credenciales. La activación no inicia ningún flujo de datos: por esta conexión no se mueven pedidos, clientes ni inventario, en ninguna dirección. Si su onboarding emite después una nueva clave API del tenant o un nuevo par OAuth, actualice aquí los campos y pruebe de nuevo antes de confiar en la conexión.

Preguntas frecuentes#

La prueba falla con INVALID_TOKEN (401)

El lado del token de la comprobación fue rechazado. O el propio intercambio de token rechazó su par client_id y client_secret, o el token devuelto no fue aceptado por la Sync API del tenant. Las causas habituales son un valor copiado con espacios extra, el secret de un par OAuth usado con el ID de otro, o una palabra de environment que envía el intercambio a la otra dirección de token de Sage distinta de aquella para la que se emitió el par.

Vuelva a copiar client_id y client_secret del mismo paquete de onboarding, sin espacios extra, y confirme que environment coincide con el tenant para el que se emitió ese par: production para el tenant en vivo, test para el de prueba. Si completó audience, quítelo salvo que sus documentos de onboarding lo exijan, y pruebe de nuevo.

La prueba falla con MISSING_SCOPE (403)

El token fue aceptado, pero su clave API del tenant no tiene permiso para el folder indicado en el campo folder. La solicitud llegó a la Sync API de su tenant: el límite es la propia clave, no la dirección ni el par OAuth.

Pida a su administrador de Sage X3 que conceda a esa clave API del tenant acceso a este folder, o que emita una clave que lo cubra. Aproveche para confirmar el nombre del folder, y pruebe de nuevo con la clave actualizada.

La prueba falla con NOT_FOUND (404)

El folder indicado en el campo folder no está habilitado para Sync API en este tenant, o el nombre no coincide con ningún folder allí. Como los nombres de folder distinguen mayúsculas, incluso el nombre correcto con la casse incorrecta se lee como otro folder.

Compare el valor de folder carácter por carácter con el paquete de onboarding, incluidas las mayúsculas. Si la ortografía es exacta, pida a su administrador de Sage X3 que habilite ese folder para Sync API, y pruebe de nuevo.

La prueba se detiene con MISSING_TENANT_BASE_URL, MISSING_FOLDER, MISSING_TENANT_API_KEY, MISSING_CLIENT_ID o MISSING_CLIENT_SECRET

El resultado nombra el campo exacto que está vacío. La prueba comprueba primero los campos y no envía nada hasta que los cinco estén presentes, porque la sonda al folder necesita el token y la clave API juntos.

Complete el campo nombrado desde su paquete de onboarding (URL base, folder, clave API del tenant, OAuth client ID u OAuth client secret), guarde y pruebe de nuevo. Repita hasta que no aparezca ningún resultado de faltante.

Escribí una dirección de servidor o una URL completa en environment y la prueba falla

environment no es un campo de dirección. Acepta solo una de dos palabras literales, y la palabra selecciona qué dirección de token de Sage usa la prueba. Cualquier otro contenido envía el intercambio de token al lugar equivocado, o a ningún lugar utilizable.

Sustituya el valor de environment por la única palabra production si esta conexión es para su tenant en vivo, o test si es para su tenant de prueba. Ponga la dirección del servidor en tenant_base_url en su lugar, y pruebe de nuevo.

La prueba pasó, pero no se sincronizan pedidos, inventario ni clientes

Ese es el alcance actual de esta conexión, no un fallo en sus valores. La prueba solo demuestra que el intercambio de token y la sonda al folder funcionan. El movimiento de datos aún no forma parte de esta conexión, porque Sync API es a nivel de tabla y las tablas y columnas de pedidos, inventario y clientes de su folder primero deben confirmarse con los metadatos de su folder para su despliegue.

Trate una prueba aprobada como una conexión verificada para este folder, y mantenga por ahora el trabajo de pedidos, inventario y clientes en el propio Sage X3. Cuando se prepare una conexión de datos para su despliegue, partirá de estos mismos valores verificados: no necesitará reunir las credenciales otra vez.