Manual de usuario — FACTSYNC

Este manual explica como configurar una conexion con SAGE 200c y como definir metodos de sincronizacion mediante el modulo FACTSYNC. No se requieren conocimientos tecnicos: el proceso se realiza integramente desde la interfaz web.

Indice

Conceptos basicos
Crear y configurar una conexion SAGE 200c
Crear y configurar un metodo
Explorar y ejecutar sincronizaciones
Metodos disponibles para SAGE 200c
Resolucion de problemas comunes
Glosario de campos SAGE ↔ Softbase

1. Conceptos basicos

FACTSYNC se organiza en dos niveles:

Concepto	Descripcion	Ejemplo
Conexion	Credenciales y parametros para conectar con un sistema externo. Una conexion puede tener multiples metodos.	«SAGE Produccion» — conexion al servidor SAGE de la empresa
Metodo	Una operacion concreta de sincronizacion: que datos se mueven, en que direccion y con que frecuencia.	«Importar clientes cada 6 horas» — metodo `customers GET`

Las operaciones posibles de un metodo son:

Operacion	Direccion	Descripcion
GET	SAGE → Softbase	Importa datos de SAGE hacia el sistema local
POST	Softbase → SAGE	Crea registros nuevos en SAGE
PUT	Softbase → SAGE	Actualiza registros existentes en SAGE

2. Crear y configurar una conexion SAGE 200c

2.1 Acceso al listado de conexiones

Navega hasta el modulo FACTSYNC. Veras el listado de conexiones existentes con columnas ID, TIPO, NOMBRE y botones de accion.

Pantalla Gestion de conexiones con el listado de conexiones existentes y el boton Anadir.

Desde aqui puedes:

Filtrar por ID, TIPO o NOMBRE y hacer clic en FILTRAR.
Hacer clic en ✏️ para editar una conexion existente.
Hacer clic en 🗄️ para abrir el explorador de datos de esa conexion.
Hacer clic en + AGREGAR para crear una nueva.

2.2 Crear una conexion nueva

Haz clic en + AGREGAR. Aparece un dialogo modal:

Modal Nueva conexion con los campos Nombre y Tipo, y los botones Cerrar y Crear.

Rellena el campo NOMBRE Escribe un nombre descriptivo que te ayude a identificar la conexion (p. ej. «SAGE Produccion» o «SAGE Test»). Puede contener espacios.
Selecciona el TIPO En el desplegable, elige sage200c. El tipo determina que campos de configuracion apareceran y que metodos estaran disponibles.
Haz clic en CREAR El sistema crea la conexion y abre automaticamente el formulario de detalle donde podras rellenar las credenciales.

2.3 Campos de configuracion de SAGE 200c

Una vez creada la conexion, el formulario de detalle muestra dos secciones: Datos generales y Configuracion. Las pestanas de navegacion de la izquierda permiten acceder a los metodos asociados y al registro de cambios.

A continuacion se detalla cada campo de la seccion Configuracion:

SAGE_ENDPOINT

Descripcion: URL base de la API de SAGE 200c, sin barra final.
Ejemplo: https://sage.empresa.com/api/v1
Obligatorio: Si

SAGE_USERNAME

Descripcion: Client ID del proveedor OAuth2 de SAGE (no es el nombre de usuario de Windows ni del ERP).
Donde encontrarlo: El administrador de SAGE lo proporciona al configurar el acceso a la API.
Obligatorio: Si

SAGE_PASSWORD

Descripcion: Client Secret OAuth2 correspondiente al SAGE_USERNAME.
Obligatorio: Si

SAGE_TOKEN

Descripcion: Bearer token de autenticacion. No es necesario rellenarlo manualmente: el sistema lo obtiene y lo renueva automaticamente en cada sincronizacion. El campo es de solo lectura.
Obligatorio: No (gestionado automaticamente)

SAGE_EXPIRES

Descripcion: Timestamp de caducidad del token actual. No es necesario rellenarlo manualmente: el sistema lo actualiza automaticamente. El campo es de solo lectura.
Obligatorio: No (gestionado automaticamente)

SAGE_SECTORS

Descripcion: Campo de SAGE de donde se obtienen los sectores de los clientes. Elige la opcion que se ajuste a como los clasifica tu instalacion de SAGE:

Opcion	Campo SAGE usado	Cuando usarla
`sectors` (por defecto)	`CodigoSector_`	La mayoria de instalaciones estandar
`tipus_client`	`CodigoTipoClienteLc`	Cuando los sectores se gestionan por tipo de cliente; activa la expansion de condiciones especiales por tipo
`colectius`	`CodigoColectivoClienteLc`	Cuando los sectores se gestionan por colectivos

Obligatorio: No (valor por defecto: sectors)

2.4 Guardar la conexion

Revisa todos los campos Asegurate de que SAGE_ENDPOINT, SAGE_USERNAME y SAGE_PASSWORD estan correctamente rellenados.
Haz clic en 💾 GUARDAR El sistema guarda la configuracion. El token se obtendra automaticamente la primera vez que se ejecute un metodo.

La conexion ya es funcional. El siguiente paso es crear los metodos de sincronizacion que definan que datos se mueven y con que frecuencia.

Eliminar una conexion es irreversible. El boton 🗑 ELIMINAR borra la conexion y todos los metodos asociados, y elimina las columnas fsync_external_id y fsync_export_status de todas las tablas afectadas. Los datos ya importados no se borran, pero pierden el vinculo con el origen externo.

3. Crear y configurar un metodo

3.1 Acceso al listado de metodos

Desde el formulario de detalle de la conexion, haz clic en la pestana METODOS CONEXION en el panel izquierdo. Veras todos los metodos configurados para esta conexion.

Pantalla Gestion de metodos con el listado de metodos configurados (columnas Id, Metodo, Descripcion, Activo, Estado, Frecuencia, Ultima ejecucion).

Significado de las columnas de estado:

ACTIVO ✓ — El metodo se ejecutara automaticamente si tiene frecuencia configurada. ✗ — El metodo existe pero no se ejecuta automaticamente.
ESTADO VIGENTE — El metodo es editable y funcional. OBSOLETO — El metodo ha sido marcado como obsoleto (solo lectura).

3.2 Crear un metodo nuevo

Haz clic en + AGREGAR. Aparece el modal de creacion:

Modal Anadir metodo con los campos Metodo (customers GET) y Descripcion, y los botones Cerrar y Crear.

Selecciona el METODO El desplegable muestra todas las operaciones disponibles para el tipo de conexion. Cada opcion indica el nombre del metodo y la operacion (GET, POST o PUT). Consulta la seccion 5 para la lista completa de metodos de SAGE 200c.
Escribe una DESCRIPCION Una descripcion clara te ayudara a identificar el metodo en el listado. Ejemplos: «Importar clientes cada 6h», «Sincronizar stocks cada noche», «Exportar pedidos a SAGE».
Haz clic en CREAR El sistema crea el metodo y abre el formulario de detalle para terminar de configurarlo.

3.3 Campos de configuracion del metodo

Formulario de detalle de un metodo customers GET con los campos Descripcion, Activado, Frecuencia Cron (0 */6 * * *) con validador visual, y Args (JSON).

CONEXION

Muestra la conexion a la que pertenece el metodo. No es editable una vez creado el metodo.

METODO

Nombre de la operacion y su direccion, p. ej. customers (GET). No es editable una vez creado.

ESTADO

VIGENTE El metodo es operativo. OBSOLETO El metodo se ha desactivado permanentemente y el formulario pasa a ser de solo lectura. Solo el administrador puede cambiar el estado.

ACTIVADO

Controla si el metodo participa en las ejecuciones automaticas programadas.

`Y` — Activado	El metodo se ejecutara automaticamente cuando llegue la frecuencia configurada.
`N` — Desactivado	El metodo existe y es configurable, pero no se ejecuta automaticamente. Aun puede lanzarse manualmente desde el explorador.

DESCRIPCION

Texto libre para identificar el metodo. Se recomienda que sea descriptivo e incluya la frecuencia, p. ej. «Importar clientes desde SAGE — cada 6 horas».

FRECUENCIA CRON

Expresion cron de 5 campos que determina cuando se ejecuta el metodo automaticamente. Dejar el campo vacio implica que el metodo solo se ejecutara manualmente. Se detalla en la seccion 3.4.

ARGS

Parametros adicionales en formato JSON que se pasan al metodo. La mayoria de metodos no necesitan ningun argumento; algunos metodos especificos si. Se detalla en la seccion 3.5.

3.4 Configurar la frecuencia (cron)

El campo FRECUENCIA CRON acepta una expresion estandar de 5 campos separados por espacio:

┌─────────── minuto       (0–59)
│  ┌──────── hora          (0–23)
│  │  ┌───── dia del mes   (1–31)
│  │  │  ┌── mes           (1–12)
│  │  │  │  ┌─ dia de la semana (0–7, 0 y 7 = domingo)
│  │  │  │  │
*  *  *  *  *

Ejemplos practicos:

Expresion	Significado	Recomendado para
0 /6 * *	Cada 6 horas (a :00 del minuto)	Clientes, empleados, sectores
0 2 * * *	Cada dia a las 02:00	Articulos, precios, stocks
0 1 * * MON	Cada lunes a la 01:00	Reimportacion completa semanal
0 0 1 * *	El primer dia de cada mes a las 00:00	Sincronizaciones mensuales
/30 * * *	Cada 30 minutos	Documentos (pedidos, albaranes)
0 8-18 * * MON-FRI	Cada hora entre las 8:00 y las 18:00, de lunes a viernes	Exportacion de pedidos en horario laboral
(vacio)	Solo ejecucion manual	Metodos de exportacion puntuales

Validacion en tiempo real: El campo FRECUENCIA CRON tiene un validador integrado que muestra en texto plano el significado de la expresion que escribes, ayudandote a confirmar que es correcta antes de guardar.

3.5 Configurar los argumentos (ARGS)

El campo ARGS permite pasar parametros adicionales al metodo en formato JSON. La mayoria de metodos funcionan sin necesidad de especificar ninguno (puedes dejar el campo vacio o poner {}).

ARGS vacios (la mayoria de metodos)

{}

Filtrar por fecha de modificacion

Para cualquier metodo GET, puedes restringir el rango de datos a importar:

{
    "filter": [
        { "field": "FechaAlta", "value": "2026-01-01", "comparator": ">=" }
    ]
}

Limitar el numero de registros por pagina

{
    "limit": 100,
    "pagination_server": true
}

Archivar (o no) los registros no recibidos — `archive_others`

Por defecto, al finalizar una sincronizacion completa FACTSYNC archiva (arxivat='Y' / actiu='N') los registros que ya estaban sincronizados por ese metodo pero que no se han recibido en esta pasada. Para desactivar este comportamiento, anade archive_others: "N" dentro de extra_params:

{
    "extra_params": {
        "archive_others": "N"
    }
}

Cuando usar "N": si el metodo importa solo un subconjunto de datos (por ejemplo con un filter por fecha o por serie), dejarlo en "Y" (el valor por defecto) podria archivar registros validos que simplemente no entraban en esta pasada. Valor por defecto: "Y" (mantiene el comportamiento historico de archivar siempre).

En productos: con "N" tambien se omite la sincronizacion de visibilidad web (cleanup de taxonomia), que recorre toda la tabla de articulos y ajusta el CMS (d_items) segun el campo web. Asi, importar un solo producto con archive_others: "N" no oculta del web al resto de productos. Se acepta tambien la variante en CamelCase ArchiveOthers.

Metodo external_documents GET — especificar el tipo de documento

El metodo external_documents requiere indicar que tipo de documento se quiere importar. Es necesario crear un metodo separado para cada tipo:

Tipo de documento	ARGS necesarios
Facturas	{"extra_params": {"type": "invoices"}}
Albaranes	{"extra_params": {"type": "delivery_notes"}}
Pedidos (importar desde SAGE)	{"extra_params": {"type": "orders"}}

Ayuda integrada: Haz clic en el boton ❓ AYUDA del formulario del metodo para consultar la documentacion completa de los ARGS disponibles para tu tipo de conexion.

3.6 Guardar el metodo

Revisa la configuracion Comprueba que ACTIVADO, FRECUENCIA y ARGS sean correctos.
Haz clic en 💾 GUARDAR El sistema guarda el metodo. A partir de ahora aparecera en el listado de metodos y, si tiene frecuencia y esta activado, se ejecutara automaticamente.

Eliminar un metodo es irreversible. El boton 🗑 ELIMINAR borra el metodo y elimina la columna fsync_get_status_{id} de las tablas afectadas. Los datos importados no se borran, pero el historial de ejecucion se pierde.

4. Explorar y ejecutar sincronizaciones

El Explorador de datos es la herramienta principal para lanzar sincronizaciones manualmente, previsualizar los datos antes de importarlos y gestionar las exportaciones.

4.1 Acceso al explorador de datos

Hay dos vias de acceso:

Desde el listado de conexiones, haz clic en el icono 🗄️ de la conexion.
Desde el formulario de detalle de una conexion, haz clic en 🗄️ GESTOR DATOS.

Data Explorer con la barra lateral de metodos disponibles (Customers expandido mostrando GET con los botones Ver original, Ver transformado e Importar).

La barra lateral izquierda muestra un grupo para cada metodo configurado. Los botones que aparecen a la derecha de cada metodo dependen de la operacion:

Boton	Operacion	Descripcion
🔍 Ver original	GET	Muestra los datos tal como los devuelve SAGE, sin ninguna transformacion. Util para verificar la conexion.
📊 Ver transformado	GET	Muestra los datos con los campos ya mapeados al formato interno de Softbase, tal como se importaran.
📥 Importar	GET	Ejecuta la importacion real. Guarda los datos en la base de datos local.
👁️ Ver exportacion	POST / PUT	Muestra la tabla de registros pendientes de exportar a SAGE.

4.2 Importar datos (GET)

(Opcional) Verifica la conexion con 🔍 Ver original Haz clic en el boton de la lupa simple. Si la conexion funciona, veras una tabla con los datos en bruto de SAGE. Si no se carga nada o aparece un error, revisa los campos SAGE_ENDPOINT, SAGE_USERNAME y SAGE_PASSWORD de la conexion.
(Opcional) Previsualiza con 📊 Ver transformado Muestra los datos ya procesados y normalizados. Comprueba que los campos se mapean correctamente antes de importar.
Haz clic en 📥 Importar El panel principal muestra el progreso en tiempo real: barras de progreso, registros procesados y consola de log. El proceso puede tardar unos minutos si hay muchos registros. No cierres la ventana mientras se ejecuta.

Data Explorer durante una importacion customers GET con la consola Output Log visible mostrando el detalle de la llamada al conector, su estado y los posibles errores.

Consola de log: Haz clic en el boton Log Console (esquina superior derecha de la vista) para mostrar u ocultar la consola en tiempo real. Los mensajes [OK] indican exito, [SKIP] indica un registro ignorado (generalmente por no poder resolver una referencia) y [ERROR] indica un problema que hay que revisar.

4.3 Exportar datos (POST / PUT)

Para los metodos de exportacion (como orders POST o customers PUT):

Haz clic en 👁️ Ver exportacion Se abre la tabla de registros pendientes de enviar a SAGE. Cada fila muestra el estado actual:
- PENDIENTE — Registro pendiente de exportar
- EXPORTADO — Registro ya enviado correctamente (o marcado manualmente como exportado)
- NO EXPORTABLE — Registro marcado manualmente como no exportable: no se enviara y no aparece entre los pendientes
- ERROR — La ultima exportacion ha fallado
Abre el menu Acciones En la cabecera de la vista hay un menu desplegable Acciones (al estilo de los listados de mantenimiento) que agrupa todas las operaciones. Marca primero las casillas de las filas que quieras tratar (o usa la casilla de la cabecera para seleccionarlas todas) y elige una opcion:
- Exportar seleccionados — Envia a SAGE las filas marcadas que se pueden exportar.
- Exportar todo lo pendiente — Envia todos los registros con estado PENDIENTE o ERROR.
- Marcar como exportadas — Marca las filas seleccionadas como exportadas sin enviarlas. Util para pedidos correctos que ya se han gestionado fuera del sistema: dejan de aparecer entre los pendientes y el cron no los procesa.
- Marcar como no exportable — Marca las filas seleccionadas como no exportables (pedidos que seguramente nunca se enviaran). Tambien salen del listado de pendientes y el cron los ignora, pero quedan diferenciadas con el distintivo NO EXPORTABLE para no confundirlas con las exportadas correctamente.
Al exportar de verdad, las filas se actualizan en tiempo real: se ponen verdes en caso de exito y rojas en caso de error. Un registro marcado como no exportable se puede devolver al listado de pendientes con el boton Desmarcar (icono de deshacer) de su fila.

Data Explorer en modo Export View para orders POST, con el menu desplegable Acciones (Exportar seleccionados, Exportar todo lo pendiente, Marcar como exportadas, Marcar como no exportable) y la tabla filtrable de registros a exportar por estado.

Filtros de la vista de exportacion: Puedes filtrar por ID, descripcion o estado (Todos / Pendientes / Exportados / No exportables) para localizar registros concretos antes de exportar.

5. Metodos disponibles para SAGE 200c

Metodos de importacion (GET — SAGE → Softbase)

Metodo	Datos importados	ARGS especiales
`currencies`	Divisas y factores de cambio	Ninguno
`sectors`	Sectores / tipos / colectivos de cliente (fuente controlada por `SAGE_SECTORS`)	Ninguno
`employees`	Comisionistas / comerciales	Ninguno
`product_families`	Familias de producto (primer nivel)	Ninguno
`product_groups`	Grupos / subfamilias de producto	Ninguno
`products`	Articulos, precios base, precios de oferta	Ninguno
`product_images`	Imagenes de articulos (Base64)	Ninguno
`discount_lines`	Lineas de descuento / tarifas	Ninguno
`conditions`	Precios estandar por tramos de volumen	Ninguno
`customers`	Clientes (incluye cadenas y comisionistas)	Ninguno
`addresses`	Direcciones secundarias de clientes	Ninguno
`warehouses`	Almacenes	Ninguno
`stocks`	Stock por articulo y almacen	Ninguno
`external_documents`	Facturas	`{"extra_params": {"type": "invoices"}}`
`external_documents`	Albaranes	`{"extra_params": {"type": "delivery_notes"}}`
`external_documents`	Pedidos desde SAGE	`{"extra_params": {"type": "orders"}}`
`payment_methods`	Formas de pago / condiciones de plazo	Ninguno
`contacts`	Contactos de clientes	Ninguno
`custom_fields`	Campos personalizados de SAGE (caracteristicas)	Ninguno
`translations`	Traducciones de articulos por idioma	Ninguno
`cleanup_taxonomy`	Limpieza de taxonomia (areas, familias, grupos) segun productos web activos	No llama a la API; ejecucion local. `"noapi": "Y"`

Orden de importacion recomendado: Para una configuracion inicial, importa las entidades maestras primero para garantizar que las referencias se puedan resolver correctamente:

currencies
sectors · employees
discount_lines (tarifas) · payment_methods
product_families → product_groups → products → product_images
customers → addresses → contacts
conditions (depende de tarifas, productos y clientes)
warehouses → stocks
custom_fields · translations
external_documents (facturas, albaranes, pedidos)
cleanup_taxonomy (limpieza local, sin API)

Metodos de exportacion (POST / PUT — Softbase → SAGE)

Metodo	Operacion	Datos exportados
`orders`	POST	Envia pedidos de Softbase hacia SAGE

6. Resolucion de problemas comunes

Problema	Causa probable	Solucion
«Ver original» no devuelve nada o da error de conexion	`SAGE_ENDPOINT`, `SAGE_USERNAME` o `SAGE_PASSWORD` incorrectos	Abre el formulario de la conexion, verifica los tres campos y guarda. Comprueba que el servidor SAGE es accesible desde la red.
El token caduca constantemente	El servidor SAGE devuelve tokens de vida muy corta	Normal: el conector renueva el token automaticamente en cada llamada. Si ves errores 401 frecuentes, comprueba que el reloj del servidor Softbase y el de SAGE estan sincronizados (NTP).
Registros con `[SKIP]` en el log	El registro referencia una entidad que no se ha importado todavia (p. ej. un articulo que no existe en Softbase)	Importa primero las entidades maestras (articulos, clientes, almacenes) y vuelve a importar los documentos que dependen de ellas.
Los sectores de los clientes no se importan	El campo `SAGE_SECTORS` no coincide con como SAGE gestiona los sectores	Cambia `SAGE_SECTORS` a `tipus_client` o `colectius` y vuelve a importar los sectores y los clientes.
El metodo de importacion se ha ejecutado pero no veo los datos nuevos	El metodo se ejecuto anteriormente y los datos ya existian (actualizacion sin cambios visibles)	Usa «Ver transformado» para comprobar que los datos llegan correctamente de SAGE. Si el problema persiste, revisa el log de la ultima ejecucion.
La exportacion de un pedido falla	El cliente o el articulo no tiene `fsync_external_id` (no se ha sincronizado desde SAGE)	Asegurate de que el cliente y todos los articulos del pedido se han importado primero desde SAGE. Sin identificador externo no se puede crear el documento en SAGE. Para los clientes, puedes activar `{"extra_params": {"export_customers": "Y"}}` en el metodo `orders POST` para que se exporten automaticamente.
Los documentos (facturas, albaranes) no se importan	Los ARGS del metodo `external_documents` no especifican el tipo	Comprueba que el campo ARGS contiene `{"extra_params": {"type": "invoices"}}` (o el tipo correspondiente). Se necesita un metodo diferente para cada tipo de documento.
El metodo no se ejecuta automaticamente a pesar de tener frecuencia configurada	El metodo tiene `ACTIVADO = N` o la tarea cron del sistema no se esta ejecutando	Verifica que `ACTIVADO = Y`. Comprueba con el administrador del sistema que el cron de FACTSYNC (`FSYN_cron`) se ejecuta periodicamente.

7. Glosario de campos SAGE ↔ Softbase

Esta seccion lista los mapeos de campos que aplica el conector sage200c.php al importar datos desde SAGE 200c hacia Softbase. Son los mismos mapeos que documenta la Referencia API en cada endpoint, agrupados aqui por entidad para consulta rapida.

Convencion de prefijos:

__id_extern__ — clave externa que se guarda en la columna fsync_external_id_{id_connexio} de la tabla destino. Permite vincular el registro Softbase con su origen SAGE en sincronizaciones futuras.
__campo (doble guion bajo, sin sufijo) — campo temporal o auxiliar usado durante el procesado; no se persiste directamente.
=valor en la columna SAGE — valor literal asignado por el conector, no procede de la API.
Los campos derivados son los que el conector calcula despues del mapeo directo (transformaciones, lookups, concatenaciones).

Este glosario refleja el conector actual. Si SAGE añade campos nuevos o cambia nombres, hay que actualizar tanto los arrays $_mapejat_* de sage200c.php como esta tabla.

customers — Clientes (`cli_ficha`)

Campo SAGE	Campo Softbase	Notas
`CodigoCliente`	`__id_extern__` / `id_extern`	Clave externa principal
`CodigoCadena_`	`id_parent`	Si difiere de `CodigoCliente`, el cliente es hijo de la cadena
`RazonSocial`	`empresa`
`Nombre`	`nom`
`EMail1`	`email`
`Telefono`	`telefon`
`Telefono2`	`telefon2`
`Telefono3`	`telefon_movil`
`Fax`	`fax`
`CifDni`	`nif` / `num_doc`	Mismo valor en ambos campos
`FechaAlta`	`data_alta`	Convertido a Unix timestamp
`FechaNacimiento`	`data_naixement`
`FechaBajaLc`	`data_baixa`
`BajaEmpresaLc`	`arxivat`	Derivado: `0→'N'`, `≠0→'Y'`
`CodigoContable`	`subcuenta`
`CodigoDivisa`	`id_divisa`	Resuelto a `tbl_divisas.id`
`CodigoCondiciones`	`id_forma_pago`	Resuelto via lookup de formas de pago importadas (`COND_{CodigoCondiciones}`)
`TarifaPrecio`	`id_linea_descompte`	La tarifa SAGE se mapea como linea de descuento
`CodigoRuta_`	`id_ruta`
`CodigoComisionista`	`id_treballador`	Comisionista 1 (principal)
`CodigoComisionista2_` … `4_`	`__treballadors[]`	Hasta 4 comisionistas adicionales
`ComercialAsignadoLc`	`id_comercial`
`CodigoSector_`	`id_sector`	Fuente seleccionable via `SAGE_SECTORS`
`CodigoTipoClienteLc`	`id_sector`	Si `SAGE_SECTORS='tipus_client'`
`CodigoColectivoClienteLc`	`id_sector`	Si `SAGE_SECTORS='colectius'`
`ClaveIVA`	`clau_iva`
`%Descuento`	`descompte1`
`RiesgoMaximo`	`credit`
`ObservacionesCliente`	`observacions`
`DIRe`	`codi_dir3_gestor`
`CodigoBanco`	`CC_id_banc`
`CodigoAgencia`	`CC_id_sucursal`
`DC`	`CC_digit`
`CCC`	`CC_compte`
`IBAN`	`CC_iban`
`SiglaNacion`	`CC_pais`	Tambien usado en la direccion principal
`Domicilio`	`carrer`	Direccion principal del cliente
`Numero1`	`numero`
`Piso`	`pis`
`Escalera`	`escala`
`Puerta`	`porta`

addresses — Direcciones secundarias (`tbl_adreces`)

Campo SAGE	Campo Softbase	Notas
`IdDomicilio`	`__id_extern__` / `id_extern`
`CodigoCliente`	`id_tabla`	Resuelto a `cli_ficha.id`; `tabla='cli_ficha'`
`NumeroDomicilio`	`codi`	Guardado para recuperar el NumeroDomicilio sin llamada API. Si vale 0, el registro se ignora (es la direccion principal)
`RazonSocial`	`nom`	Derivado: `RazonSocial + " (" + TipoDomicilio + ")"`
`TipoDomicilio`	`defecte`	Derivado: `'F'→'Y'` (fiscal por defecto), resto `'N'`
`Domicilio` + `Domicilio2`	`carrer`	Concatenados con espacio
`Numero1`	`numero`
`Piso`	`pis`
`Escalera`	`escala`
`Puerta`	`porta`
`Telefono`	`telefon`
`Telefono2`	`telefon_movil`

products — Articulos (`art_subarticles`)

Campo SAGE	Campo Softbase	Notas
`CodigoArticulo`	`__id_extern__` / `codi`
`DescripcionArticulo`	`model`
`PrecioCompra`	`preu_compra`
`PrecioCosteEstandar`	`preu_cost`	Coste estandar calculado
`CodigoFamilia`	`id_familia`	Resuelto via `_get_id_familia()`
`CodigoSubfamilia`	`id_article`	Resuelto via `_get_id_article()`
`PrecioVenta`	`__preus[TARIFA_BASE]`	Precio base
`PrecioVentasinIVA1/2/3`	`__preus[LINIA_DESC_n]`	Precios por linea de descuento
`PrecioOfertasinIVA`	`__preus[TARIFA_BASE_OFERTA]`	Solo si la oferta esta vigente (`FechaInicioOferta ≤ hoy ≤ FechaFinalOferta`)
`GrupoIva`	`id_tipus_iva`	Resuelto via `_get_tipus_iva()` (cache desde `api/iva`)
`ObsoletoLc`	`__import`	Si `-1` el registro se descarta (`__import=false`), no se importa
`PublicarInternet`	`arxivat` / `web`	Derivado: `-1→arxivat='N',web='Y'` · `≠-1→arxivat='Y',web='N'`
`FechaAlta`	`data_alta`	Convertido a Unix timestamp
`CodigoContable`	`subcuenta`

product_families — Familias (`art_families`)

Campo SAGE	Campo Softbase	Notas
`CodigoFamilia`	`__id_extern__`	Filtro: `CodigoSubfamilia = '**********'`
`Descripcion`	`descripcio`
`PublicarGCRM`	`arxivat` / `web`	Derivado igual que en products

product_groups — Grupos / subfamilias (`art_articles`)

Campo SAGE	Campo Softbase	Notas
`CodigoSubfamilia`	`__id_extern__`	Filtro: `CodigoSubfamilia <> '**********'`
`Descripcion`	`descripcio`
`CodigoFamilia`	`id_familia`	Resuelto via `_get_id_familia()`
`PublicarGCRM`	`arxivat` / `web`	Derivado igual que en products

product_images — Imagenes de articulo (`d_items_fotos`)

Campo SAGE	Campo Softbase	Notas
`ImagenExt`	`__id_extern__`	UUID; si cambia respecto al guardado, se descarga de nuevo via `api/imagen/{id}`
`CodigoArticulo`	`__codi_article`	Resuelto a `art_subarticles.id`
`sysDescripcionBinario`	`descripcio`
`ImagenBase64`	archivo en disco	Descargado via `api/imagen/{id}` y guardado en `files/public/products/prod_{ImagenExt}`

sectors — Sectores de cliente (`cli_sectors`)

Campo SAGE	Campo Softbase	Notas
`CodigoSector_` / `CodigoTipoClienteLc` / `CodigoColectivoClienteLc`	`__id_extern__`	Segun `SAGE_SECTORS`
`DescripcionSector_` / `TipoClienteLc` / `ColectivoClienteLc`	`descripcio`	Segun `SAGE_SECTORS`

employees — Comisionistas / comerciales (`ficha_treballador`)

Campo SAGE	Campo Softbase	Notas
`CodigoComisionista`	`__id_extern__`
`Comisionista`	`nom`
`CifDni`	`nif`
`Telefono`	`telefon`
`Telefono2`	`telefon_movil`
`EMail1`	`email`
`Domicilio`	`carrer`	Direccion enriquecida via `_add_address_to_data()`

discount_lines — Lineas de descuento / tarifas (`art_linees_descompte`)

Campo SAGE	Campo Softbase	Notas
`Tarifa`	`__id_extern__`
`DescripcionTarifa`	`descripcio`	Derivado: `Tarifa + " - " + DescripcionTarifa`
`IndicadorTarifa`	`__IndicadorTarifa`	0 = precio · 1 = % incremento · 2 = valor incremento

conditions — Condiciones de precio (`art_condicions`)

El metodo realiza tres pasadas que comparten tabla destino con distinto ambito (tarifa, cliente, condicion especial).

Campo SAGE	Campo Softbase	Notas
`IdTarifaPrecio` / `IdArticuloCliente` / `CodigoCondicionLc`	`__id_extern__`	Segun la pasada
`Tarifa`	`id_tabla`	Pasada 1: resuelto a `art_linees_descompte.id`
`CodigoCliente`	`id_tabla`	Pasadas 2 y 3: resuelto a `cli_ficha.id`
`CodigoArticulo`	`id_tipus_element`	Resuelto a `art_subarticles.id`
`CodigoFamilia` / `CodigoSubfamilia`	`id_tipus_element`	Pasada 3: si el ambito es familia o grupo
`FechaInicio`	`data_ini`	Convertido a Unix timestamp
`FechaFinal`	`data_fi`	Ajustado a 23:59:59 del dia indicado
`Precio` / `PrecioOferta`	`valor` + `tipus_condicio='preu'`	Ajustado por la cascada de descuentos
`%Descuento` 1/2/3	`valor` + `tipus_condicio='desc'`	% efectivo de la cascada
volumen del tramo	`volum`	Derivado del tramo de cantidad de la tarifa
`StatusActivo`	`eliminat`	Si `≠-1` se marca `eliminat=time()`

conditions (2ª pasada) — Precios especiales por cliente (`art_condicions`)

Dentro del método conditions GET, el conector hace una segunda llamada a api/articulos_cliente (filtrando Automatico=0) para traer los precios y descuentos especiales definidos por cliente–artículo. Estos registros se insertan en la misma tabla art_condicions que los tramos de tarifa.

Campo SAGE	Campo Softbase	Notas
`IdArticuloCliente`	`__id_extern__`
`CodigoCliente`	`id_tabla`	Resuelto a `cli_ficha.id`; `tabla='cli_ficha'`
`CodigoArticulo`	`id_tipus_element`	Resuelto a `art_subarticles.id`
`PrecioOferta` + `%Descuento1/2/3`	`valor`	Si `PrecioOferta>0`: `tipus_condicio='preu'` con cascada de descuentos. Si solo `%Descuento>0`: `tipus_condicio='desc'`
sin precio ni descuento	—	`__import=false` → el registro se ignora

warehouses — Almacenes (`mag_magatzems`)

Campo SAGE	Campo Softbase	Notas
`CodigoAlmacen`	`__id_extern__`
`Almacen`	`descripcio`
`Domicilio` + `Municipio` + `CodigoPostal` + `Provincia`	`adreca`	Concatenados
—	`actiu` / `web`	Siempre `'Y'` en importacion

stocks — Stock por articulo y almacen (`art_subarticles_estoc`)

Campo SAGE	Campo Softbase	Notas
`IdAcumuladoStock`	`__id_extern__`
`CodigoArticulo`	`id_subarticle`	Resuelto a `art_subarticles.id`
`CodigoAlmacen`	`id_magatzem`	Resuelto a `mag_magatzems.id`
`UnidadSaldo`	`estoc`
`PrecioMedio`	`valor_mig_unitari`

currencies — Divisas (`tbl_divisas`)

Campo SAGE	Campo Softbase	Notas
`CodigoDivisa`	`__id_extern__` / `codi`
`Divisa`	`nom`
`SimboloDivisa`	`simbol`
`Decimales`	`decimals`
`FactorCambioEuro`	`factor_conversio`

external_documents — Pedidos / Albaranes / Facturas (`ext_documents`)

Cabecera comun a los tres tipos:

Campo SAGE	Campo Softbase	Notas
`IdPedidoCli` / `IdAlbaranCli` / `IdFacturaCli`	`__id_extern__`	Segun el tipo
`CodigoCliente`	`id_client`	Resuelto via `_get_id_client()`
`EjercicioPedido` / `...Albaran` / `...Factura`	`any`
`SeriePedido` / `...Albaran` / `...Factura`	`serie`
`NumeroPedido` / `...Albaran` / `...Factura`	`numero`
`FechaPedido` / `...Albaran` / `...Factura`	`data`	Convertido a timestamp
`ImporteBruto`	`total_brut`
`ImporteLiquido`	`total`
`FactorCambio`	`factor_conversio`
`CodigoDivisa`	`id_divisa`	Resuelto via `_get_id_divisa()`
—	`tipus`	Valor fijo por tipo: `PEDIDO` / `ALBARA` / `FACTURA`
`StatusFacturado` (albaran)	`estat`	`1→'FACTURAT'` · `0→'OBERT'`
`StatusContabilizado` (factura)	`estat`	`1→'COMPTABILITZAT'` · `0→'PENDENT'`
`estado` (pedido)	`estat`	`0→'BLOQUEADO'` · `1→'SERVIDO'` · `2→'PENDIENTE'`
`StatusAbono`	`subestat`	`1→'ABONO'` en albaranes y facturas
`PathFichero`	`attached[]`	Una entrada por adjunto, descargado via `api/doc/{path}`

Lineas (mismo mapeo para los tres tipos, dentro de args.Linies[]):

Campo SAGE	Campo Softbase	Notas
`CodigoArticulo`	`id_subarticle` + `referencia`	Resuelto via `_get_id_subarticle()`
`DescripcionArticulo`	`descripcio`
`UnidadesPedidas` (pedido) / `Unidades` (albaran/factura)	`quantitat`
`Precio`	`preu`
`ImporteBruto` ↔ `BaseImponible` / `ImporteNetoLineas`	`descompte`	Derivado: `(Bruto - Neto) / Bruto × 100`
`ImporteNeto`	`preu_net`	Subtotal de linea
`%Iva` / `CodigoIva`	`iva`	% de IVA aplicado

payment_methods — Formas de pago (`fac_formes_pago`)

Campo SAGE	Campo Softbase	Notas
`IdCondicion`	`__id_extern__`	Prefijado como `COND_{CodigoCondiciones}`
`FormadePago`	`descripcion`
`NumeroPlazos`	`vencimientos`
`DiasPrimerPlazo`	`__dias_primer_plazo`	Solo visualizacion
`DiasEntrePlazos`	`__dias_entre_plazos`	Solo visualizacion
`Remesable`	`comptat` / `rebuts`	Derivado: `-1→comptat='N',rebuts='Y'` · `≠-1→comptat='Y',rebuts='N'`

contacts — Contactos de clientes (`tbl_contactes`)

Nota: Actualmente este metodo utiliza datos de ejemplo incrustados en el codigo (stub). La llamada a api/contactos esta preparada pero comentada, pendiente de activacion en produccion.

Campo SAGE	Campo Softbase	Notas
`IdContacto`	`__id_extern__`
`CodigoCliente`	`id_tabla`	Resuelto a `cli_ficha.id`; `tabla='cli_ficha'`. Si no existe, `__import=false`
`Nombre` + `Apellido1` + `Apellido2`	`nom`	Concatenados; fallback a `NombreContactoLc`
`TelefonoContactoLc`	`telefon`
`Telefono2ContactoLc`	`telefon_movil`
`Telefono3ContactoLc`	`extensio`
`EMail1`	`email`
`Cargo`	`carrec`
`CodigoAreaContactoLc`	`departament`
`EsContactoComercialLc`	`defecte`	Derivado: `-1→'Y'`, resto `'N'`
`BajaEmpresaLc`	`arxivat`	Derivado: `0→'N'`, `≠0→'Y'`

custom_fields — Campos personalizados (`art_caracteristiques`)

Campo SAGE	Campo Softbase	Notas
`sysId`	`__id_extern__`
`sysRotulo`	`descripcio`

translations — Traducciones de articulos (`d_items_idiomes`)

Importa las traducciones de descripcion de articulos desde api/idiomas_articulos. Solo se importan registros cuyo articulo exista en Softbase y cuyo idioma tenga equivalencia en el mapa interno.

Campo SAGE	Campo Softbase	Notas
`IdIdioma`	`__id_extern__`	Fallback: `CodigoArticulo_CodigoIdioma_`
`CodigoArticulo`	`id_item`	Resuelto via `_get_item_subarticle()`
`CodigoIdioma_`	`id_idioma`	Mapa: CAT→ca, CAS→es, ING→en, POR→pt, FRA→fr, ALE→de, ITA→it
`DescripcionArticulo`	`titol`
`Descripcion2Articulo`	`subtitol`

cleanup_taxonomy — Limpieza de taxonomia

Metodo especial que no realiza ninguna llamada a la API de SAGE. Ejecuta una limpieza local de areas, familias y grupos en funcion de los productos web activos. Configurado con "noapi": "Y" en el JSON del conector.

orders POST — Exportacion de pedidos hacia SAGE

El conector envia el pedido con la estructura {Cabecera, Lineas[]}. Los campos clave que requieren estar resueltos previamente:

Campo Softbase	Campo SAGE enviado	Notas
`cli_ficha.fsync_external_id_{id_connexio}`	`Cabecera.CodigoCliente`	Si esta vacio, el pedido no se puede exportar
`art_subarticles.fsync_external_id_{id_connexio}`	`Lineas[].CodigoArticulo`	Si esta vacio para alguna linea, el pedido falla
`mag_magatzems.fsync_external_id_{id_connexio}`	`Lineas[].CodigoAlmacen`
`extra_params.serie` del metodo	`Cabecera.SerieDocumento`	En blanco o sin definir, la serie/linea de origen del pedido (ver tabla siguiente)
`ped_pedidos.id`	`Cabecera.NumeroDocumento`	Referencia temporal; SAGE devolvera el numero definitivo

Parametros disponibles en args.extra_params del metodo orders POST:

Parametro	Tipo	Descripcion
`linies`	String / Array	Series/lineas de pedido (`linea_pedido`) a leer, separadas por comas (`"A,WEB"`) o como array. En blanco o sin definir = todos los pedidos.
`serie`	String	Serie de destino (`Cabecera.SerieDocumento`). En blanco o sin definir, la serie/linea de origen del pedido.
`export_customers`	`"Y"`	Exporta automaticamente el cliente del pedido si no esta sincronizado: primero lo busca en SAGE por NIF (`CifDni`) o Email (`EMail1`) para vincularlo; si no existe, lo crea via `customers POST`.
`customers_method`	Integer	ID del metodo `customers POST` a usar para exportar el cliente (hereda sus `default_values`). Si no se indica, se usa el metodo `customers POST` activo de la misma conexion.

Pedidos aplazados: como la creacion de clientes en SAGE no es instantanea, cuando se envia un cliente nuevo el pedido se marca con un valor negativo en ped_pedidos.fsync_export_status_{id_connexio} (el valor absoluto es el timestamp del proximo reintento, 3 minutos despues). El cron de exportacion lo reprocesa automaticamente cuando vence. Si el cliente ya se habia enviado pero aun no aparece en SAGE, no se vuelve a enviar (se evitan duplicados) y el pedido se aplaza de nuevo.

Validacion de customers_method: con export_customers: "Y", si customers_method es invalido (el ID no existe, no es un metodo customers POST, o pertenece a otra conexion), o si no se indica y la conexion no tiene ningun metodo customers POST activo, los pedidos con cliente nuevo (no sincronizado) se marcan como error: en la vista previa de exportacion aparecen en rojo como no exportables con el motivo, y en la ejecucion se registran como error en el log sin enviar nada a SAGE. Los pedidos con cliente ya sincronizado se exportan con normalidad.

{"extra_params": {"linies": "WEB,B2B", "serie": "W", "export_customers": "Y", "customers_method": 27}}

Comportamiento del parametro serie:

Valor	Resultado en SAGE (`Cabecera.SerieDocumento`)
`"serie": "W"`	Serie W para todos los pedidos de este metodo
`"serie": ""` (clave presente, en blanco)	La serie/linea de origen de cada pedido (`linea_pedido` de Softbase)
Clave no definida	La serie/linea de origen de cada pedido (igual que en blanco)

Varios metodos orders POST con series diferentes: como cada metodo tiene su propio campo ARGS, se pueden crear varios metodos orders POST en la misma conexion, cada uno con su serie de destino:

// Metodo 1: pedidos de la linea WEB → serie "W" en SAGE
{"extra_params": {"linies": "WEB", "serie": "W"}}

// Metodo 2: pedidos de la linea B2B → serie "B" en SAGE
{"extra_params": {"linies": "B2B", "serie": "B"}}

Con varios metodos orders POST:

Usa linies para repartir los pedidos entre metodos: cada metodo deberia leer solo sus lineas. Si dos metodos leen los mismos pedidos pendientes, el primero que se ejecute los exportara todos con su serie.
La serie de destino se configura siempre en el metodo (parametro serie): no hay ninguna serie por defecto a nivel de conexion.

customers POST / PUT — Exportacion de clientes hacia SAGE

El conector carga la ficha completa de cli_ficha y envia un subconjunto reducido de campos:

Campo Softbase	Campo SAGE enviado
`empresa`	`RazonSocial`
`nom`	`Nombre`
`email`	`EMail1`
`telefon`	`Telefono`
`nif`	`CifDni`
`fsync_external_id_{id_connexio}`	`CodigoCliente` (solo en PUT, en cuerpo y URL)

El uso de POST o PUT lo decide el conector segun el estado del registro: si fsync_external_id esta vacio se llama a POST /api/clientes; si ya esta rellenado, a PUT /api/clientes/{codi}.

Parametros disponibles en args.extra_params del metodo customers POST:

Parametro	Tipo	Descripcion
`default_values`	Objeto	Valores por defecto de campos de SAGE que se anaden al crear el cliente (POST). Cada clave es el nombre exacto del campo en SAGE y el valor es el valor por defecto (como string).

{
    "extra_params": {
        "default_values": {
            "CodigoTipoClienteLc": "110",
            "PeriodicidadFacturas": "1",
            "EnvioEFactura": "-1",
            "CodigoComisionista": "10",
            "CodigoComisionista2_": "10",
            "CodigoTransportista_": "451"
        }
    }
}

Puntos a tener en cuenta:

Las claves deben ser los nombres de campo de la API de SAGE, no las etiquetas de pantalla: CodigoTipoClienteLc (no «Tipo cliente»), EnvioEFactura con -1 para «si» (los booleanos de SAGE son 0/-1). Puedes descubrir los nombres exactos con Ver original en el Explorador de datos sobre el metodo customers GET.
Solo se aplican al crear el cliente (POST). En actualizaciones (PUT) no se envian.
No sobreescriben los campos que ya se mapean desde la ficha del cliente (RazonSocial, Nombre, EMail1, Telefono, CifDni): si un campo ya tiene valor por el mapeo, su default_value se ignora.
Este mismo default_values se hereda cuando la exportacion de pedidos crea clientes automaticamente (export_customers: "Y" en el metodo orders POST): se toma del metodo indicado en customers_method — que debe ser el ID numerico del metodo (columna Id del listado de metodos), no el nombre — o, si no se indica, del metodo customers POST activo de la misma conexion.