Actualización de datos maestros del cliente

Los campos update_* permiten controlar si la información recibida al crear un servicio debe utilizarse únicamente en ese servicio o si también debe actualizar los datos maestros del cliente o punto de entrega en Logístiko.

Propósito de estos indicadores

El objetivo principal de los campos update_* es evitar que una integración sobrescriba automáticamente información que haya sido corregida, completada o mejorada directamente en Logístiko.

Los datos procedentes del ERP no siempre son la fuente más actualizada o fiable. Por ejemplo:

• La dirección puede haberse corregido después de una geocodificación incorrecta.
• El teléfono o el correo pueden haberse actualizado desde operaciones.
• El contacto puede haberse completado con el nombre real de la persona que recibe.
• La ventana horaria puede haberse ajustado según la experiencia de reparto.
• La duración de parada puede haberse corregido para mejorar la planificación.
• Los datos fiscales pueden haberse revisado manualmente.
• El ERP puede seguir enviando información antigua, incompleta o directamente errónea.

Sin estos indicadores, cada nueva creación de servicio podría volver a escribir los datos del ERP sobre la ficha existente y deshacer esas correcciones.

Por este motivo, no es necesario declarar estos campos cuando no se quiera actualizar el dato maestro. Si un campo update_* no se envía, Logístiko lo interpreta automáticamente como false.

{
  "update_contact": false,
  "update_timeWindow": false,
  "update_stop": false,
  "update_address": false,
  "update_dni": false,
  "update_email": false,
  "update_phone": false,
  "update_fiscal": false
}

Con esta configuración:

• Los datos recibidos se utilizan en el servicio actual.
• La ficha maestra del cliente o punto de entrega no se modifica.
• Las correcciones realizadas en Logístiko se conservan.
• El ERP no recupera automáticamente el control sobre un dato que pueda estar desactualizado.

Los indicadores solo deberían activarse cuando el ERP sea realmente la fuente maestra y autorizada del dato correspondiente.

Regla recomendada: si existe la posibilidad de que el dato del ERP esté desactualizado, incompleto o sea menos fiable que el dato de Logístiko, el indicador correspondiente debe mantenerse en false.

Los indicadores son opcionales, de tipo boolean y se envían dentro de cada servicio, al mismo nivel que cliente.

{
  "pedidosLista": [
    {
      "albaran": "ALB-2026-000125",
      "actividad": 2,
      "cliente": {
        "clienteCodigo": "CLI-00025",
        "clienteNombre": "Distribuciones Ejemplo",
        "direccion": "Calle Mayor 25",
        "direccionDetalles": "Planta 2, puerta B",
        "codigoPostal": "28013",
        "ciudad": "Madrid",
        "pais": "ES",
        "contacto": "María García",
        "telefono": "+34910000000",
        "email": "[email protected]",
        "dni": "00000000T",
        "clienteDireccionFiscal": "Avenida Central 10",
        "clienteDireccionFiscalDetalles": "Oficina 3",
        "clienteDireccionFiscalCP": "28001",
        "clienteDireccionFiscalCiudad": "Madrid",
        "clienteNombreFiscal": "Distribuciones Ejemplo, S.L.",
        "clienteCIF": "B00000000"
      },
      "horarioDesde": "09:00",
      "horarioHasta": "13:00",
      "horarioCierreInicio": "10:30",
      "horarioCierreFinal": "11:00",
      "paradaDuracion": "00:15",
      "update_contact": false,
      "update_timeWindow": false,
      "update_stop": false,
      "update_address": false,
      "update_dni": false,
      "update_email": false,
      "update_phone": false,
      "update_fiscal": false
    }
  ]
}

Los campos update_* no van dentro de cliente. Se envían al mismo nivel que albaran, actividad, cliente o bultosLista.

Comportamiento general

Todos los indicadores tienen como valor predeterminado false.

Este valor predeterminado protege los datos maestros existentes. Aunque el ERP envíe un valor diferente, Logístiko puede utilizarlo en el servicio actual sin sobrescribir la información guardada del cliente.

Los indicadores son independientes. Es posible actualizar solamente el teléfono y el correo, manteniendo sin cambios la dirección, el contacto, los horarios y los datos fiscales.

Campos disponibles

Punto de entrega y cliente base

La implementación trabaja con dos posibles registros:

• Punto de entrega o sede del cliente: identificado por clienteCodigo.
• Cliente base: registro general del cliente, cuando existe.

El punto de entrega es el registro que se compara y actualiza primero.

La propagación al cliente base no es igual para todos los indicadores.

La propagación de update_phone y update_fiscal es más amplia que la del resto de indicadores. Debe tenerse en cuenta cuando un cliente base tenga varios puntos de entrega.

update_contact

Actualiza el contacto utilizando cliente.contacto.

{
  "cliente": {
    "clienteCodigo": "CLI-00025",
    "clienteNombre": "Distribuciones Ejemplo",
    "direccion": "Calle Mayor 25",
    "codigoPostal": "28013",
    "ciudad": "Madrid",
    "contacto": "María García"
  },
  "update_contact": true
}

El proceso es:

1. Comprueba que update_contact sea true.
2. Compara el contacto recibido con el contacto almacenado en el punto de entrega.
3. Si son diferentes, actualiza el punto de entrega.
4. Si existe un cliente base con el mismo código, actualiza también su contacto cuando sea diferente.

Si cliente.contacto coincide exactamente con cliente.clienteNombre, la implementación puede convertir el contacto en un valor vacío antes de la actualización.

update_timeWindow

Actualiza tanto la ventana horaria habitual como la franja de cierre.

Campos públicos relacionados:

{
  "horarioDesde": "09:00",
  "horarioHasta": "13:00",
  "horarioCierreInicio": "10:30",
  "horarioCierreFinal": "11:00",
  "update_timeWindow": true
}

La implementación también reconoce los nombres alternativos:

Los nombres alternativos tienen prioridad. Los nombres públicos se utilizan cuando el valor alternativo no está disponible.

Ventana horaria

Se actualizan:

• Hora mínima habitual.
• Hora máxima habitual.

Si los valores recibidos contienen una fecha completa o un timestamp, la implementación extrae la hora y los minutos y almacena el valor como milisegundos desde el inicio del día.

Franja de cierre

Se actualizan:

• Inicio de la franja de cierre.
• Fin de la franja de cierre.

La implementación sustituye las listas almacenadas y conserva una única pareja de inicio y fin.

Por tanto, este campo no añade una nueva franja de cierre: reemplaza la franja almacenada en la primera posición.

Propagación

La ventana y la franja de cierre se copian al cliente base únicamente cuando el cliente base y el punto de entrega tienen el mismo código.

update_stop

Actualiza la duración habitual de parada utilizando:

{
  "paradaDuracion": "00:15",
  "update_stop": true
}

La implementación también reconoce el nombre alternativo serviceDuration, que tiene prioridad sobre paradaDuracion.

Cuando el valor es diferente, se actualiza la duración habitual del punto de entrega.

La duración se replica al cliente base únicamente cuando ambos registros tienen el mismo código.

Un valor convertido a 0 puede sobrescribir la duración almacenada. No debe activarse update_stop si la duración está vacía, es inválida o no se quiere modificar.

update_address

Actualiza la dirección del punto de entrega con los siguientes campos:

• cliente.direccion
• cliente.direccionDetalles
• cliente.codigoPostal
• cliente.ciudad
• cliente.pais
• cliente.latitud
• cliente.longitud

Ejemplo:

{
  "cliente": {
    "clienteCodigo": "CLI-00025",
    "clienteNombre": "Distribuciones Ejemplo",
    "direccion": "Calle Nueva 48",
    "direccionDetalles": "Muelle 3",
    "codigoPostal": "28022",
    "ciudad": "Madrid",
    "pais": "ES",
    "latitud": 40.447,
    "longitud": -3.575
  },
  "update_address": true
}

Condiciones para actualizar

El bloque controlado por update_address se ejecuta cuando:

1. update_address es true.
2. Se recibe una dirección no vacía o unas coordenadas válidas.
3. Cambia al menos uno de estos valores respecto a los datos originales almacenados:
   • Dirección.
   • Código postal.
   • Ciudad.
   • Latitud.
   • Longitud.

Cambiar únicamente direccionDetalles o pais, manteniendo iguales los demás valores, puede no activar la actualización porque esos dos campos no forman parte de la comparación inicial.

Geocodificación

• Si se reciben coordenadas válidas, se utilizan directamente.
• Si no se reciben coordenadas válidas pero existe una dirección, Logístiko intenta geocodificarla.
• Después se recalcula el estado de validez de la dirección.

Detalles de dirección

La implementación construye el texto de detalles concatenando:

direccion + ", " + direccionDetalles

cuando direccionDetalles no está vacío.

Propagación

La dirección se copia al cliente base únicamente cuando el cliente base y el punto de entrega tienen el mismo código.

Comportamiento especial de las coordenadas

Existe un segundo bloque que comprueba las coordenadas fuera de la condición update_address.

Si se reciben coordenadas válidas y son diferentes de las almacenadas, la ubicación del punto de entrega puede actualizarse aunque:

{
  "update_address": false
}

Cuando ambos registros tienen el mismo código, esta actualización de coordenadas también puede propagarse al cliente base.

Este comportamiento debe tenerse en cuenta: update_address: false no impide necesariamente la actualización de coordenadas válidas.

update_dni

Actualiza el identificador recibido en cliente.dni.

{
  "cliente": {
    "clienteCodigo": "CLI-00025",
    "clienteNombre": "Distribuciones Ejemplo",
    "direccion": "Calle Mayor 25",
    "codigoPostal": "28013",
    "ciudad": "Madrid",
    "dni": "00000000T"
  },
  "update_dni": true
}

Si el valor es diferente, se actualiza el punto de entrega.

Se replica al cliente base únicamente cuando ambos registros tienen el mismo código.

update_email

Actualiza el correo recibido en cliente.email.

{
  "cliente": {
    "clienteCodigo": "CLI-00025",
    "clienteNombre": "Distribuciones Ejemplo",
    "direccion": "Calle Mayor 25",
    "codigoPostal": "28013",
    "ciudad": "Madrid",
    "email": "[email protected]"
  },
  "update_email": true
}

Si el valor es diferente, se actualiza el punto de entrega.

Se replica al cliente base únicamente cuando ambos registros tienen el mismo código.

update_phone

Actualiza el teléfono recibido en cliente.telefono.

{
  "cliente": {
    "clienteCodigo": "CLI-00025",
    "clienteNombre": "Distribuciones Ejemplo",
    "direccion": "Calle Mayor 25",
    "codigoPostal": "28013",
    "ciudad": "Madrid",
    "telefono": "+34910000001"
  },
  "update_phone": true
}

Si el valor es diferente, se actualiza el teléfono del punto de entrega.

A diferencia de contacto, email, DNI, horarios, duración y dirección, la implementación copia también el teléfono al cliente base cuando existe, sin comprobar que el código del cliente base coincida con el código del punto de entrega.

update_fiscal

Actualiza conjuntamente los siguientes datos fiscales:

• cliente.clienteDireccionFiscal
• cliente.clienteDireccionFiscalDetalles
• cliente.clienteDireccionFiscalCP
• cliente.clienteDireccionFiscalCiudad
• cliente.clienteNombreFiscal
• cliente.clienteCIF

Ejemplo:

{
  "cliente": {
    "clienteCodigo": "CLI-00025",
    "clienteNombre": "Distribuciones Ejemplo",
    "direccion": "Calle Mayor 25",
    "codigoPostal": "28013",
    "ciudad": "Madrid",
    "clienteDireccionFiscal": "Avenida Central 10",
    "clienteDireccionFiscalDetalles": "Oficina 3",
    "clienteDireccionFiscalCP": "28001",
    "clienteDireccionFiscalCiudad": "Madrid",
    "clienteNombreFiscal": "Distribuciones Ejemplo, S.L.",
    "clienteCIF": "B00000000"
  },
  "update_fiscal": true
}

Si cualquiera de los seis valores es diferente, la implementación sustituye el conjunto completo de datos fiscales del punto de entrega.

También copia todos los datos fiscales al cliente base cuando existe, sin comprobar que ambos registros tengan el mismo código.

No debe activarse update_fiscal enviando solamente uno de los campos fiscales. Los campos no informados pueden llegar como cadenas vacías y sustituir valores almacenados.

Actualización parcial

Los indicadores pueden combinarse de forma independiente:

{
  "pedidosLista": [
    {
      "albaran": "ALB-2026-000125",
      "actividad": 2,
      "cliente": {
        "clienteCodigo": "CLI-00025",
        "clienteNombre": "Distribuciones Ejemplo",
        "direccion": "Calle Mayor 25",
        "codigoPostal": "28013",
        "ciudad": "Madrid",
        "telefono": "+34910000001",
        "email": "[email protected]"
      },
      "update_contact": false,
      "update_timeWindow": false,
      "update_stop": false,
      "update_address": false,
      "update_dni": false,
      "update_email": true,
      "update_phone": true,
      "update_fiscal": false
    }
  ]
}

En este ejemplo:

• Se actualizan el teléfono y el correo.
• No se actualizan el contacto, los horarios, la duración, la dirección, el DNI ni los datos fiscales.

Valores vacíos

No debe activarse un indicador cuando el dato relacionado está vacío, incompleto o no ha sido validado.

Ejemplo que debe evitarse:

{
  "cliente": {
    "clienteCodigo": "CLI-00025",
    "clienteNombre": "Distribuciones Ejemplo",
    "direccion": "Calle Mayor 25",
    "codigoPostal": "28013",
    "ciudad": "Madrid",
    "telefono": ""
  },
  "update_phone": true
}

La implementación compara los valores y puede sustituir el contenido almacenado por una cadena vacía.

La misma precaución debe aplicarse especialmente a:

• update_stop, porque puede almacenar una duración 0.
• update_timeWindow, porque puede sustituir la ventana y la franja de cierre.
• update_fiscal, porque actualiza el conjunto completo de campos fiscales.
• update_address, porque puede geocodificar y sobrescribir la dirección almacenada.

Varios servicios del mismo cliente

Cuando una petición incluye varios servicios para el mismo clienteCodigo, deben enviarse valores coherentes.

Debe evitarse que distintos servicios del mismo lote soliciten actualizar el mismo campo con valores diferentes.

Ejemplo problemático:

Servicio 1: update_phone = true, telefono = 910000001
Servicio 2: update_phone = true, telefono = 910000002

El resultado final puede depender del orden de procesamiento.

Cuándo activar los indicadores

Se recomienda activar un indicador cuando:

• El ERP es la fuente autorizada y más fiable del dato.
• Se desea que el ERP sobrescriba expresamente cualquier corrección previa realizada en Logístiko.
• El valor ha sido validado.
• El cambio debe mantenerse para futuros servicios.
• clienteCodigo identifica correctamente al punto de entrega.
• El dato no es una excepción exclusiva del servicio actual.
• Todos los servicios del mismo cliente envían información coherente.

No se recomienda activarlo cuando:

• El dato puede haber sido corregido o enriquecido en Logístiko.
• El ERP puede contener una versión antigua, incompleta o errónea.
• No existe una regla clara sobre qué sistema es el propietario del dato.
• El dato es temporal.
• Solo aplica al servicio actual.
• El valor está vacío o incompleto.
• Se trata de una dirección puntual.
• El ERP no debe modificar el maestro.
• No se conoce la relación entre cliente base y punto de entrega.

Ejemplo: conservar una corrección realizada en Logístiko

Supongamos que el ERP conserva esta dirección:

Calle Mayor 15

Después de una incidencia de reparto, el equipo corrige la dirección en Logístiko:

Calle Mayor 51, nave 3

En la siguiente creación de servicio, el ERP vuelve a enviar la dirección antigua.

Con:

{
  "update_address": false
}

la dirección antigua puede utilizarse en el servicio recibido según el flujo de creación, pero no se solicita sustituir la dirección maestra corregida en Logístiko.

Con:

{
  "update_address": true
}

el ERP recupera el control del dato y puede volver a sobrescribir la dirección almacenada.

El mismo criterio se aplica a contacto, teléfono, correo, DNI, horarios, duración de parada y datos fiscales.

Activar un campo update_* significa autorizar al ERP a sobrescribir el dato maestro correspondiente cuando detecte diferencias.

Configuración segura por defecto

Cuando el ERP debe crear servicios sin mantener el maestro de clientes:

{
  "update_contact": false,
  "update_timeWindow": false,
  "update_stop": false,
  "update_address": false,
  "update_dni": false,
  "update_email": false,
  "update_phone": false,
  "update_fiscal": false
}

Resumen

La actualización de coordenadas válidas puede ejecutarse aunque update_address sea false.

El propósito general de los indicadores es proteger las correcciones y mejoras realizadas en Logístiko frente a datos antiguos o erróneos enviados posteriormente por el ERP.