Documentación BOT Clientify – Sage50

Esta es la documentación BOT Clientify – Sage50 para el plugin de integración entre ambas plataformas.

Entidades a conectar

La integración permite sincronizar las siguientes entidades desde Sage50c hacia Clientify:

• Clientes (Clientes) → Contactos Clientify
• Artículos (Articulo) → Productos Clientify
• Albaranes de venta (c_albven) → Presupuestos Clientify
• Albaranes de venta → Oportunidades/Deals Clientify (automático desde presupuestos)

Sincronización unidireccional

• Clientes: Sage50c → Clientify
• Artículos: Sage50c → Clientify
• Albaranes de venta: Sage50c → Clientify (como presupuestos)
• Deals: Se crean automáticamente desde los presupuestos

Nota: Esta integración es unidireccional, solo sincroniza datos desde Sage50c hacia Clientify. Requiere el addon eConnect de Sage50c para funcionar.

Campos por entidad

Clientes Sage50c → Contactos Clientify

Se utiliza el campo cif (NIF/CIF) de Sage50c y taxpayer_identification_number de Clientify para vincular de manera única los registros. Si no se encuentra por CIF, se busca por el campo personalizado in_sage50c con el código del cliente.

Campo Sage50c	Campo Clientify	Observaciones
nombre	first_name	Nombre del cliente
cif	taxpayer_identification_number	Campo clave para vinculación
email	email	Email principal
direccion	addresses[0].address	Dirección (tipo 1)
poblacion	addresses[0].city	Ciudad
provincia	addresses[0].state	Provincia
pais	addresses[0].country	País (convertido a nombre completo)
cp	addresses[0].postal_code	Código postal
codigo	integrations[].integration_id	Código del cliente en Sage50c
codigo	custom_fields[].in_sage50c	Campo personalizado con código de Sage50c
f_alta	created	Fecha de alta del cliente
vendedor	owner	Se asigna el owner basado en el email del vendedor
–	tags	Se añade automáticamente la etiqueta «sage50c»
–	integrations[].category	Siempre se establece como ‘erp’

Nota:

• Solo se sincronizan clientes que tengan cif (NIF/CIF) y vendedor asignado.
• Los productos de los albaranes se añaden como etiquetas adicionales al contacto.

Artículos Sage50c → Productos Clientify

Se utiliza el campo codigo de Sage50c y sku de Clientify para vincular de manera única los registros.

Campo Sage50c	Campo Clientify	Observaciones
nombre	name	Nombre del artículo
codigo	sku	Campo clave para vinculación
observacio	description	Descripción del artículo
p_importe	price	Precio (redondeado a 2 decimales)
tipo_iva	tax	Porcentaje de IVA (se obtiene de la tabla Tipo_Iva)

Nota: El precio se calcula como floor(p_importe * 100) / 100 para redondear a 2 decimales.

Albaranes de venta Sage50c → Presupuestos Clientify

Los albaranes de venta de Sage50c se sincronizan como presupuestos en Clientify.

Campo Sage50c	Campo Clientify	Observaciones
numero	budget_code	Número de albarán
fecha	created	Fecha del albarán
fecha_fac	expiration_date	Fecha de facturación (si existe)
fecha_fac	status	Si existe fecha_fac, status = «accepted»
importe	subtotal	Importe sin IVA
totaldoc	total	Total con IVA
observacio	description	Observaciones del albarán
cliente	contact	Se sincroniza primero el cliente asociado
numero	name	Formato: «Albaran de Venta : [numero] – Factura : [factura]»
d_albven (líneas)	items[]	Líneas del albarán convertidas a items

Líneas de albarán Sage50c → Items de presupuesto Clientify

Campo Sage50c	Campo Clientify	Observaciones
definicion	item	Nombre del artículo
definicion1	description	Descripción adicional
unidades	quantity	Cantidad (redondeada)
precio	unit_price	Precio unitario (redondeado a 2 decimales)
dto1	discount_percentage	Descuento porcentual
tipo_iva	taxes[]	Se busca o crea el impuesto correspondiente

Nota: Si el albarán no tiene líneas, se crea un item genérico «General» con el importe total del albarán y un IVA del 21%.

Conversión de presupuestos a Deals

Los presupuestos creados desde albaranes se convierten automáticamente en oportunidades/deals si no existe ya un deal con el mismo número de albarán.

Mecanismo de sincronización

Proceso de vinculación

La integración utiliza diferentes estrategias para vincular registros:

Para Contactos:

1. Por CIF/NIF: Se busca primero si existe un contacto con el mismo taxpayer_identification_number.
2. Por campo personalizado in_sage50c: Si no se encuentra por CIF, se busca por el código de Sage50c en el campo personalizado.
3. Creación: Si no se encuentra ninguna coincidencia, se crea un nuevo contacto.

Para Productos:

1. Por SKU: Se busca si existe un producto con el mismo sku (código de artículo).
2. Creación: Si no se encuentra, se crea un nuevo producto.

Para Presupuestos:

1. Por número de albarán: Se busca si existe un presupuesto con el mismo budget_code (número de albarán).
2. Actualización o creación: Si existe, se actualiza; si no, se crea uno nuevo.

Gestión de impuestos

La integración gestiona los impuestos de la siguiente manera:

1. Obtención de tipos de IVA: Se obtienen todos los tipos de IVA de Sage50c (entidad Tipo_Iva).
2. Búsqueda en Clientify: Se buscan impuestos existentes en Clientify que coincidan con el porcentaje.
3. Creación automática: Si no existe un impuesto con el porcentaje correspondiente, se crea automáticamente con el nombre «sage50c [porcentaje]%».

Asignación de propietarios (Owners)

Los contactos se asignan automáticamente a un propietario basándose en el vendedor de Sage50c:

1. Se obtienen todos los vendedores de Sage50c (entidad vendedor).
2. Se busca el vendedor asociado al cliente.
3. Si el vendedor tiene email, se busca un usuario en Clientify con ese email.
4. Si se encuentra, se asigna como owner del contacto.

Gestión de etiquetas

• Todos los contactos sincronizados reciben automáticamente la etiqueta «sage50c».
• Los productos de los albaranes se añaden como etiquetas adicionales al contacto.
• Si un albarán tiene líneas con artículos, estos se añaden como etiquetas al contacto.

Modos de sincronización

La integración puede ejecutarse en dos modos:

• Full: Sincroniza todos los registros
• Modified: Sincroniza solo los registros modificados desde la última ejecución

Proceso de conexión

Requisitos previos

1. Sage50c instalado con el addon eConnect activo
2. Servidor eConnect configurado y accesible
3. Usuario y contraseña de Sage50c con permisos para acceder a eConnect
4. URL del servidor eConnect (serverURL)

Credenciales necesarias

Para configurar la integración se necesitan las siguientes credenciales:

1. Usuario: Usuario de Sage50c con acceso a eConnect
2. Password: Contraseña del usuario
3. ServerURL: URL del servidor eConnect (ej: http://servidor:puerto/Iwfcsage50cimpl)

Autenticación

La integración utiliza autenticación SOAP mediante token:

1. Autenticación inicial: Se realiza una petición SOAP Authenticate con usuario y contraseña.
2. Token de sesión: Se obtiene un token y su fecha de caducidad.
3. Renovación automática: El token se renueva automáticamente 10 minutos antes de su expiración.
4. Almacenamiento: El token se almacena en la base de datos para evitar autenticaciones innecesarias.

Configuración en Clientify

1. Acceder a la pestaña de Integraciones en Clientify
2. Seleccionar la tarjeta de Sage50c
3. Rellenar los campos:
   • Usuario
   • Password
   • ServerURL
4. Guardar la configuración
5. Si todo es correcto, aparecerá un mensaje de confirmación y la integración se activará

Configuración avanzada

La integración permite configurar mediante ajustes de usuario:

• activeIntegration: Activa/desactiva la integración completa

Compatibilidad

Versiones de Sage50c

La integración requiere:

• Sage50c (versión compatible con eConnect)
• Addon eConnect instalado y configurado
• Servidor eConnect accesible mediante SOAP

Protocolo de comunicación

La integración utiliza:

• Protocolo SOAP (Simple Object Access Protocol)
• Namespace: http://tempuri.org/Iwfcsage50cimpl/
• Acciones SOAP:
  • Authenticate: Para autenticación
  • Consulta: Para consultar entidades

Entidades consultables

La integración puede consultar las siguientes entidades de Sage50c:

• Clientes: Lista de clientes
• Articulo: Lista de artículos
• c_albven: Cabecera de albaranes de venta
• d_albven: Líneas de albaranes de venta
• Tipo_Iva: Tipos de IVA
• vendedor: Lista de vendedores

Requisitos

• Servidor eConnect configurado y accesible
• Usuario con permisos para acceder a eConnect
• Conexión de red estable entre el servidor de integración y el servidor eConnect
• Timeout de 120 segundos para consultas SOAP

Notas importantes

1. Primera sincronización: En modo Full, la primera sincronización puede tardar bastante tiempo si hay muchos registros.
2. Albaranes sin número: Los albaranes que no tengan número se omiten durante la sincronización.
3. Clientes sin CIF o vendedor: Solo se sincronizan clientes que tengan cif y vendedor asignado.
4. Gestión de impuestos: Los impuestos se crean automáticamente en Clientify si no existen, con el prefijo «sage50c» para identificarlos.
5. Conversión de presupuestos a deals: Los presupuestos creados desde albaranes se convierten automáticamente en deals si no existe ya un deal con el mismo número.
6. Actualización de etiquetas: Cuando se sincroniza un albarán, se actualizan las etiquetas del contacto con los productos del albarán.
7. Timeout de consultas: Las consultas SOAP tienen un timeout de 120 segundos para manejar grandes volúmenes de datos.
8. Normalización de valores: Los valores vacíos en las respuestas XML se normalizan a strings vacíos para evitar errores.
9. Manejo de errores: Si ocurre un error durante la sincronización de un registro individual, se registra en el log y se continúa con el siguiente registro.
10. Filtros en consultas: Las consultas pueden incluir filtros SQL-like (ej: codigo='123') para obtener registros específicos.