PortalClient SageConnector — Manual de instalación v1.0.12

GironaSoft · Conector Sage 200 ↔ PortalClient/Softbase8

Este manual describe la instalación y configuración del PortalClient SageConnector: la aplicación de servidor que GironaSoft instala en el servidor del cliente donde reside Sage 200, y que expone una API REST para integrarse con Softbase8/FACTSYNC.

1. Requisitos previos

Antes de ejecutar el instalador, estos requisitos deben estar cumplidos en el servidor del cliente:

• ⚠️
  IP pública fija o DDNS — REQUISITO INDISPENSABLE El servidor donde reside Sage 200 y el conector debe tener una dirección IP pública fija. Si no dispone de ella, es necesario un servicio DDNS que apunte siempre a la IP pública de la red. Sin esto, Softbase8 no puede localizar el conector desde el exterior.
• 🖥️
  Sage 200 (≥ 2022.01.000) y SQL Server operativos Sage 200 debe estar instalado y funcionando, con su base de datos Microsoft SQL Server accesible.
• 📦
  Capa OEM de Sage 200 instalada y registrada Necesaria para la escritura de clientes, direcciones y pedidos en Sage (vía tablas TmpIME_).
• 🔑
  Credenciales de administrador SQL disponibles Nombre de usuario y contraseña del administrador de SQL Server. Solo se utilizan durante la instalación para crear el usuario del conector.
• 🌐
  Puerto 8443 abierto en el router/cortafuegos Puerto por defecto del conector (configurable). Debe estar abierto en el firewall de Windows y redirigido al servidor en el router.
• 🛡️
  Privilegios de administrador en el servidor Para instalar y guardar la configuración del conector.
• 📄
  Módulo Gestor Documental de Sage 200 — necesario para visualizar PDFs en el PortalClient Si se quiere que el cliente pueda consultar los PDFs de los pedidos, albaranes y facturas desde el PortalClient, es imprescindible tener el módulo Gestor Documental de Sage 200 activado y configurado.
  
  Sage tiene la opción de generar PDFs automáticamente al crear documentos, pero si no se ha configurado el Gestor Documental, estos PDFs no se vinculan con el gestor y por lo tanto no son accesibles vía API.
  
  Cómo configurarlo: para cada tipo de documento (pedidos, albaranes, facturas), hay que editar la plantilla correspondiente en Sage y asignar los campos del Gestor Documental:

  1. Ir a Administración → Consola de Administración → Personalización → Informes
  2. Seleccionar el informe (plantilla) del tipo de documento a configurar
  3. Hacer clic en el icono de rueda dentada ⚙ (Propiedades)
  4. Ir a la pestaña Gest. Doc.
  5. Activar Almacenar en Gestión Documental y rellenar los campos:

  Campo Sage	Pedidos	Albaranes	Facturas
  Archivo y carpeta	DocuVentas\Pedidos	DocuVentas\Albaranes	DocuVentas\Facturas
  CodigoDocumentoLc	PVE	ALC	FAC
  CodigoCliente	[CabeceraPedidoCliente.CodigoCliente]	[CabeceraAlbaranCliente.CodigoCliente]	[ResumenCliente.CodigoCliente]
  EjercicioDocumentoLc	[LineasPedidoCliente.EjercicioPedido]	[CabeceraAlbaranCliente.EjercicioAlbaran]	[ResumenCliente.EjercicioFactura]
  SerieDocumentoLc	[LineasPedidoCliente.SeriePedido]	[CabeceraAlbaranCliente.SerieAlbaran]	[ResumenCliente.SerieFactura]
  NumeroDocumentoLc	[LineasPedidoCliente.NumeroPedido]	[CabeceraAlbaranCliente.NumeroAlbaran]	[ResumenCliente.NumeroFactura]

  Facturas — múltiples plantillas: Sage 200 puede tener varias plantillas de factura (p. ej. GES_LisFacturaClienteExp). Hay que configurar el Gestor Documental en cada una de las plantillas que se utilicen, ya que cada una genera un documento independiente. Los valores de la columna Facturas de la tabla son válidos para las plantillas estándar basadas en ResumenCliente.

  

  Propiedades del informe → Gest. Doc. — campos generales y CodigoCliente

  

  Propiedades del informe → Gest. Doc. — Ejercicio, Serie y Número del documento
• 🛒
  Campo libre CP_Canales en Sage 200 — opcional, para diferenciar canales de venta por producto Si se quiere filtrar qué productos se importan o se muestran en el PortalClient según el canal de venta (B2B, B2C, Personal...), hay que crear un campo libre en la pantalla de artículos de Sage 200.
  
  Sage no dispone de ninguna categorización nativa para esto, por lo que hay que crearlo manualmente desde Personalizar campos libres de la pantalla de artículos, con los siguientes valores:
  
  Nombre del campo: CP_Canales  •  Tipo: Texto  •  Lista: activado

  Valor a presentar	Valor a grabar	Descripción
  B2B & B2c	12	Disponible en web pública (B2C) y PortalClient (B2B). Valor por defecto.
  B2C	8	Disponible solo en la web pública
  B2B	4	Disponible solo en el PortalClient
  Personal	16	Disponible solo para clientes con tarifa específica (p. ej. productos Bonpreu)

  

  Campo libre CP_Canales — lista de valores

  

  Pantalla de artículos con el desplegable Canales de Venta

  Canal “Personal” (productos exclusivos por cliente): para que un artículo con canal 16 (OTROS) solo se muestre a los clientes que lo tienen en su tarifa, hay que activar la regla correspondiente en la configuración del PortalClient (Visibilidad del canal OTROS). Se marcan con checkboxes; no hace falta escribir SQL. Reglas disponibles:
  

  • Condición personalizada de tarifa/línea — muestra el producto si la línea de descuento del cliente tiene una condición (precio/descuento) para ese producto.
  • Precio en la tarifa del cliente — muestra el producto si tiene un precio definido en la tarifa asociada al cliente.
  • Precio en la tarifa base — muestra el producto si tiene un precio definido en la tarifa por defecto, igual para todos los clientes.

  Un producto OTROS se muestra si cumple cualquiera de las reglas marcadas.

2. Parte 1 — PortalClient SageConnector (servidor Sage)

2.1 Instalación

• Ejecutar el archivo Installer.exe Hacer doble clic sobre el ejecutable. Se requieren privilegios de administrador.

  ↓ Descargar Installer.exe

  

  [Captura: PortalClient SageConnector Setup — pantalla de bienvenida]
  Guardar la imagen como img/sc-01-installer-welcome.png

  Pantalla de bienvenida del asistente de instalación

  Se abre el asistente de instalación. Hacer clic en Siguiente > para continuar.
• Configurar la conexión a la base de datos de SAGE 200 El asistente solicita los datos de conexión a SQL Server:

  

  [Captura: Configurar la conexión a la base de datos]
  Guardar la imagen como img/sc-02-installer-db.png

  Formulario de configuración de la conexión SQL

  Campo	Descripción	Ejemplo
  Servidor SQL	Nombre del servidor SQL e instancia de Sage 200	MISERVIDOR\SQLEXPRESS_2022
  Puerto	Puerto de SQL Server. Si se deja vacío, se usa el puerto estándar	0 (estándar)
  Base de datos	Nombre de la base de datos de Sage 200	Sage
  Usuario SAGE	Usuario SQL que utilizará el conector. Si no existe, el instalador lo creará automáticamente	SAGEConnector
  Contraseña (Usuario SAGE)	Contraseña para el usuario del conector
  Usuario Administrador	Administrador de SQL Server. Solo se usa durante la instalación para crear el usuario del conector y asignar permisos. No se guarda en el conector.	sa
  Contraseña (Administrador)	Contraseña del administrador SQL

• Creación automática del usuario SQL y sus permisos Al confirmar los datos, el instalador crea el usuario SAGEConnector y le asigna:

  • SELECT / INSERT / UPDATE / DELETE sobre las tablas TmpIME_* (escritura en Sage vía importación)
  • SELECT sobre las tablas de los endpoints necesarios (lectura de datos maestros y documentos)

  Debería aparecer el mensaje "Configuración de la base de datos completada correctamente."
• Instalación del programa El asistente instala la aplicación en el sistema. Al finalizar, hacer clic en Cerrar.

2.2 Acceso a la pantalla de configuración

• Iniciar la aplicación como administrador Abrir PortalClient SageConnector haciendo clic derecho → Ejecutar como administrador. Es imprescindible para guardar la configuración.

  

  [Captura: Ventana principal — Estado del sistema]
  Guardar la imagen como img/sc-03-main-window.png

  Ventana principal del conector. Se puede ver el estado de la conexión SQL, pedidos/clientes en cola y el log en tiempo real.

  La ventana principal muestra el estado del sistema:

  Indicador	Descripción	Estado normal
  Base de datos	Conexión SQL Server a Sage 200	Connexión abierta
  Repositorio de ficheros	Carpeta de archivos (imágenes de artículos)	connected / disconnected
  Pedidos en cola	Pedidos pendientes de enviar a Sage	0 (cuando todo está procesado)
  Clientes en cola	Clientes pendientes de enviar a Sage	0 (cuando todo está procesado)

  La sección Log muestra la actividad en tiempo real.

  Para acceder a la configuración, hacer clic en el icono de engranaje ⚙ de la barra superior.

2.3 Crear claves API (Autenticación)

Desde la pantalla de configuración se gestionan las credenciales que Softbase8/FACTSYNC utilizará para conectarse al conector.

• Abrir la pantalla de configuración Hacer clic en el icono de engranaje ⚙. Se abre el diálogo de configuración:

  

  [Captura: Diálogo Configuración — sección Database + Autenticación]
  Guardar la imagen como img/sc-04-config-auth.png

  Diálogo de configuración. La sección Database muestra la conexión SQL. La sección Autenticación gestiona las claves API por empresa.

  El diálogo tiene dos secciones:

  • Database: datos de conexión SQL (ya configurados durante la instalación). Se pueden verificar o modificar aquí.
  • Autenticación: tabla de credenciales API. Cada fila es un par API KEY/SECRET asociado a una empresa de Sage 200.
• Crear una nueva clave API En la tabla de Autenticación, hacer clic en la primera fila vacía y rellenar:

  Campo	Valor
  Propietario	Nombre identificativo de la integración (p. ej. PortalClient o Softbase8-EmpresaA)
  API KEY	Se genera automáticamente al guardar
  API SECRET	Se genera automáticamente al guardar
  Empresa	Seleccionar la empresa de Sage 200 desde el desplegable

• Guardar y anotar las credenciales Hacer clic en Aceptar. La API KEY y el API SECRET se generarán automáticamente.
  
  Anotarlos en un lugar seguro: deberán introducirse en FACTSYNC (Parte 2). El API SECRET no se puede recuperar, solo regenerar.

  Para regenerar el API SECRET en el futuro: hacer clic en el botón Cambiar de la columna [Cambiar API SECRET]. Se generará un nuevo secret y el antiguo dejará de ser válido. También habrá que actualizar el campo SAGE_PASSWORD en la conexión FACTSYNC.

2.4 Entornos multiempresa

Si el cliente trabaja con más de una empresa en Sage 200, hay que generar un par de credenciales independiente para cada empresa: un par API KEY/SECRET por empresa. Cada credencial da acceso únicamente a la empresa con la que fue creada.

Repetir el proceso del apartado 2.3 para cada empresa, seleccionando la empresa correspondiente en el desplegable. En la Parte 2 (FACTSYNC), habrá que crear conexiones independientes para cada empresa.

2.5 Puerto y cortafuegos

El conector publica su API REST sobre HTTPS en el puerto 8443 por defecto (visible en el log: Servidor activo en el puerto 8443). Es configurable.

• Abrir el puerto en el Firewall de Windows Añadir una regla de entrada en el Firewall de Windows del servidor para permitir tráfico TCP en el puerto elegido (p. ej. 8443).
• Redirección (port-forwarding) en el router En el router de la sede del cliente, configurar una regla NAT que redirija el puerto externo (p. ej. 8443) hacia la IP interna del servidor.
• Verificar el acceso externo Desde un equipo fuera de la red del cliente, verificar que el endpoint responde:
  https://<IP_publica_o_DDNS>:8443/api/v1/currencies Debe responder con un JSON o un error 401 (que confirma que el conector responde).

3. Parte 2 — FACTSYNC en Softbase8

Una vez el conector está instalado y las claves API generadas, hay que crear la conexión en FACTSYNC para que Softbase8 pueda comunicarse con el conector.

3.1 Crear la conexión FACTSYNC

• Abrir FACTSYNC desde el menú de Softbase8 Menú → FACTSYNC → Conexiones. Hacer clic en + Agregar.
• Indicar nombre y tipo

  • Nombre: nombre descriptivo (p. ej. SAGE Producción o SAGE — Empresa A)
  • Tipo: sage200c
• Rellenar los campos de configuración

  Campo	Valor	Notas
  SAGE_ENDPOINT	URL base de la API del conector	Sin barra final. Formato: https://<IP_o_dominio>:8443
  SAGE_USERNAME	API KEY (de la Parte 1, apartado 2.3)
  SAGE_PASSWORD	API SECRET (de la Parte 1, apartado 2.3)
  SAGE_SECTORS	Origen de los sectores en Sage	sectors (por defecto) / tipus_client / colectius
  SAGE_TOKEN	(gestionado automáticamente por FACTSYNC)
  SAGE_EXPIRES	(gestionado automáticamente por FACTSYNC)

• Guardar y verificar Guardar la conexión. A continuación, verificar que funciona creando un método de prueba (currencies GET) y ejecutándolo manualmente con el botón Ver original. Si devuelve datos de Sage, la integración está operativa.