Antes de comenzar la integración debe definirse dónde se realizará la planificación:

• Completamente en Logístiko.
• Parcialmente en el ERP y parcialmente en Logístiko.
• Completamente en el ERP.
• Por el propio conductor desde la aplicación.
• Automáticamente mediante la API de despacho.

Esta decisión determina principalmente cómo deben utilizarse los siguientes campos:

• conductorCodigo
• rutaReferencia
• zona

1. Endpoint para crear servicios

Crear servicios

El endpoint estándar permite crear:

• Servicios sin artículos.
• Servicios con artículos.
• Servicios con cliente existente o nuevo.
• Servicios con formularios especificos
• Servicios con facturas pasadas

2. Resumen de escenarios de asignación

3. Toda la planificación se realiza en Logístiko

Este escenario debe utilizarse cuando el ERP únicamente comunica los servicios y Logístiko se encargará de:

• Crear las agrupaciones.
• Decidir qué conductor realizará cada servicio.
• Crear las rutas.
• Ordenar las paradas.
• Optimizar las rutas.
• Realizar el despacho.

Este escenario incluye tanto la planificación manual desde el panel como los modelos de planificación y optimización automática de Logístiko.

Campos de asignación

Los servicios deben enviarse sin conductor ni ruta preasignada:

{
  "conductorCodigo": "",
  "rutaReferencia": "",
  "zona": ""
}

Información recomendada para la planificación

Aunque los campos de asignación se envíen vacíos, es recomendable proporcionar toda la información operativa disponible:

• Dirección completa.
• Código postal.
• Localidad.
• Coordenadas, cuando estén disponibles.
• Fecha deseada.
• Horarios de entrega o recogida.
• Peso.
• Volumen.
• Cantidad.
• Número de bultos.
• Duración estimada de la parada.
• Prioridad.
• Tipo de servicio.
• Observaciones relevantes.

Cuanta más información se proporcione, mejores serán los resultados de la planificación y la optimización.

Ejemplo

{
  "albaran": "ALB-2026-001",
  "actividad": 2,
  "sedeCodigo": "SEDE-01",
  "conductorCodigo": "",
  "rutaReferencia": "",
  "zona": "",
  "fechaDeseada": "2026-07-20T08:00:00+0200",
  "cantidad": 10,
  "peso": 125.5,
  "volumen": 2.4,
  "prioridad": 0,
  "comentarios": "Entregar por la puerta lateral",
  "cliente": {
        "clienteCodigo": "c0123",
....
      }
}

4. El ERP conoce una zona o agrupación, pero no el conductor real

En algunas operativas, el ERP ya tiene una zona, ruta o agrupación preasignada para cada cliente o servicio, pero todavía no conoce qué conductor realizará el reparto.

Por ejemplo:

• Zona norte.
• Zona centro.
• Ruta de mañana.
• Ruta de refrigerado.
• Ruta 15.
• Reparto urgente.

Cuando posteriormente una persona realizará la planificación definitiva desde Logístiko, puede utilizarse conductorCodigo como un conductor lógico o agrupador temporal.

Cómo funciona

En el maestro de conductores de Logístiko se crean códigos que representan las agrupaciones utilizadas por el ERP.

Por ejemplo:

El ERP envía el código dentro de conductorCodigo:

{
  "albaran": "ALB-2026-002",
  "actividad": 2,
  "conductorCodigo": "ZONA_NORTE",
  "zona": "NORTE",
  "cliente": {
        "clienteCodigo": "c0123",
....
      }
}

Logístiko tratará inicialmente ZONA_NORTE como si fuera un conductor y agrupará bajo ese código todos los servicios recibidos.

Durante la planificación, el responsable logístico cambiará el conductor lógico por el conductor real:

ZONA_NORTE → CONDUCTOR_23

Consideraciones importantes

conductorCodigo continúa siendo técnicamente un código de conductor.

Por tanto:

• El código debe existir previamente en el maestro de conductores de Logístiko.
• El conductor lógico se utiliza como agrupador temporal.
• No representa necesariamente a una persona real.
• No representa una zona geográfica configurada en Logístiko.
• Antes de despachar la ruta debe sustituirse por el conductor definitivo.
• Los servicios se comportarán como servicios asignados a ese conductor lógico hasta que se realice la reasignación.

Importante: no debe despacharse una ruta a un conductor lógico que represente una zona o agrupación. Primero debe cambiarse al conductor real que realizará la ruta.

Cuándo utilizar este modelo

Este escenario es adecuado cuando:

• El ERP dispone de una zona preasignada.
• El ERP dispone de un nombre de ruta preasignado.
• Todavía no se conoce el conductor real.
• Existe una persona que realizará la planificación desde Logístiko.
• Se necesita mantener inicialmente las agrupaciones creadas por el ERP.

Qué ocurre si el código no existe

Si se envía un conductorCodigo que no corresponde con ningún conductor registrado, el servicio puede crearse, pero no quedará asociado al conductor esperado.

La respuesta puede incluir:

201 - OK, but driver not found

En este caso no debe crearse nuevamente el servicio. Debe corregirse o crearse el conductor y realizar posteriormente la asignación correcta.

5. El ERP conoce la ruta, pero no el conductor

Este escenario debe utilizarse cuando las rutas ya están decididas en el ERP, pero todavía no se conoce qué conductor realizará cada una.

El ERP debe informar rutaReferencia:

{
  "albaran": "ALB-2026-003",
  "actividad": 2,
  "rutaReferencia": "RUTA-15",
  "conductorCodigo": "",
  "cliente": {
        "clienteCodigo": "c0123",
....
      }
}

Todos los servicios que compartan la misma rutaReferencia podrán identificarse como parte de la misma agrupación de ruta.

Asignación desde la aplicación

Cuando esta funcionalidad está habilitada, el conductor puede introducir en la aplicación el código de la ruta que va a realizar.

Por ejemplo:

RUTA-15

Al introducir o seleccionar el código, la ruta y sus servicios se asignan al conductor que ha realizado la acción.

Este modelo permite trabajar sin que una persona tenga que asignar manualmente cada ruta desde la oficina.

Cuándo utilizar este modelo

• El ERP ya genera las rutas.
• El ERP conoce qué servicios pertenecen a cada ruta.
• El conductor definitivo se conoce al comenzar la jornada.
• No hay una persona encargada de reasignar las rutas desde el panel.
• Los conductores seleccionan la ruta que van a ejecutar.
• La plantilla de conductores cambia diariamente.
• Se trabaja con autónomos o colaboradores externos.

Diferencia con el conductor lógico

Debe utilizarse rutaReferencia en lugar de un conductor lógico cuando:

• El ERP conoce una ruta real.
• No se necesita una persona que cambie posteriormente un conductor temporal.
• El conductor seleccionará la ruta desde la aplicación.
• La ruta se despachará mediante API utilizando su referencia.

6. El ERP conoce el conductor definitivo

Cuando el ERP ya ha realizado la planificación y conoce qué conductor realizará cada servicio, debe enviarse el código real del conductor:

{
  "albaran": "ALB-2026-004",
  "actividad": 2,
  "conductorCodigo": "CONDUCTOR_23"
}

El código debe coincidir exactamente con un conductor registrado en Logístiko.

Los servicios recibidos con el mismo conductorCodigo quedarán inicialmente agrupados para ese conductor.

Posteriormente, Logístiko puede utilizarse para:

• Revisar los servicios asignados.
• Ordenar las paradas.
• Optimizar la ruta.
• Añadir o retirar servicios.
• Cambiar servicios de conductor.
• Despachar la ruta a la aplicación.

Informar también la ruta

Si el ERP conoce tanto el conductor como la ruta, puede enviar ambos campos:

{
  "albaran": "ALB-2026-005",
  "actividad": 2,
  "conductorCodigo": "CONDUCTOR_23",
  "rutaReferencia": "RUTA-15"
}

Esto permite conservar la relación con la ruta del ERP y utilizar posteriormente ambos valores para el despacho o seguimiento.

7. Diferencia entre conductorCodigo, rutaReferencia y zona

conductorCodigo

Identifica el conductor al que se asigna inicialmente el servicio.

Puede representar:

• Un conductor real.
• Un conductor lógico creado como zona.
• Un conductor lógico creado como ruta.
• Una agrupación temporal que será reasignada posteriormente.

El código debe existir en el maestro de conductores de Logístiko.

rutaReferencia

Identifica una ruta o agrupación de ruta procedente del ERP.

Debe utilizarse cuando:

• El ERP ya conoce la ruta.
• El conductor todavía no está decidido.
• El conductor seleccionará la ruta desde la aplicación.
• Se desea conservar la referencia de ruta del ERP.
• Se desea despachar servicios mediante API utilizando el código de ruta.

No es necesario crear un conductor con el mismo código que rutaReferencia.

zona

Permite conservar una zona o clasificación territorial dentro del servicio.

Puede utilizarse como:

• Información operativa.
• Criterio de búsqueda.
• Criterio de filtrado.
• Información visible durante la planificación.

Informar una zona no implica por sí solo que el servicio vaya a quedar asignado automáticamente a un conductor.

Si se necesita una agrupación inmediata por zona y después se realizará una reasignación manual, puede enviarse también un conductor lógico:

{
  "zona": "NORTE",
  "conductorCodigo": "ZONA_NORTE"
}

Qué campo utilizar

8. Despacho automático por API

Cuando el ERP ya ha realizado la asignación o dispone de una referencia de ruta, puede crear los servicios y realizar posteriormente el despacho mediante API.

Documentación:

Despachar ruta

Según el modelo utilizado, el despacho puede realizarse mediante:

• conductorCodigo
• rutaReferencia
• conductorCodigo y rutaReferencia
• Una lista de servicios concretos mediante uniqueIdList

Por defecto, se incluirán los servicios disponibles que cumplan los filtros enviados.

8.1. Despacho por rutaReferencia

Los servicios deben haberse creado previamente con la misma referencia de ruta:

{
  "albaran": "ALB-2026-006",
  "rutaReferencia": "RUTA-15"
}

Posteriormente se llama al endpoint de despacho utilizando esa referencia:

{
  "rutaReferencia": "RUTA-15"
}

Este modelo permite localizar y despachar los servicios asociados a la ruta enviada por el ERP.

8.2. Despacho por conductorCodigo

Los servicios deben haberse creado previamente con el conductor real:

{
  "albaran": "ALB-2026-007",
  "conductorCodigo": "CONDUCTOR_23"
}

Posteriormente se llama al endpoint de despacho:

{
  "conductorCodigo": "CONDUCTOR_23"
}

Importante: si conductorCodigo representa una zona o agrupación lógica, debe sustituirse por el conductor real antes de realizar el despacho.

8.3. Despacho por ruta y conductor

Cuando se informan ambos valores, pueden combinarse para limitar los servicios que se incluirán:

{
  "rutaReferencia": "RUTA-15",
  "conductorCodigo": "CONDUCTOR_23"
}

Este modelo es útil cuando un conductor puede tener varias rutas o cuando una misma referencia puede utilizarse en diferentes contextos operativos.

8.4. Despachar servicios concretos

Para evitar incluir todos los servicios que cumplen los filtros puede utilizarse uniqueIdList.

{
  "rutaReferencia": "RUTA-15",
  "conductorCodigo": "CONDUCTOR_23",
  "uniqueIdList": [
    "UNIQUE-ID-001",
    "UNIQUE-ID-002",
    "UNIQUE-ID-003"
  ]
}

Solamente se incluirán los servicios identificados en la lista que sean compatibles con los filtros enviados.

8.5. Otros datos del despacho

Según la configuración del endpoint, también pueden enviarse datos como:

Si no se informa una fecha prevista de inicio, se utilizará el comportamiento configurado para la integración.

9. Datos que deben enviarse al crear servicios

Los campos exactos dependerán de la operativa, pero se recomienda revisar al menos los siguientes grupos de información.

9.1. Identificación del servicio

Valores de actividad:

9.2. Datos del cliente y destinatario

Debe enviarse información suficiente para identificar al cliente o destinatario.

Como mínimo debe informarse al menos uno de los siguientes datos:

• Código del cliente.
• Nombre del cliente.
• Dirección completa.
• Código postal.
• Localidad.
• Provincia.
• País.

También se recomienda enviar:

• Latitud
• Longitud
• Teléfono
• Correo electrónico.
• Persona de contacto.
• Documento de identidad, cuando aplique.
• Observaciones de entrega.

La dirección debe ser suficientemente completa para permitir una geolocalización correcta.

9.3. Datos de planificación

Los horarios deben enviarse con formato:

HH:mm

Valores habituales de prioridad:

10. Uso del campo etiqueta

El campo etiqueta permite enviar información adicional que no está incluida en los campos estándar.

Puede utilizarse para:

• Mostrar información relevante en la planificación.
• Identificar un vendedor o comercial.
• Identificar un departamento.
• Aplicar filtros.
• Facilitar el seguimiento de determinados servicios.
• Crear agrupaciones visuales o funcionales.
• Mostrar información auxiliar al equipo logístico.

Puede incluir varios valores separados por punto y coma:

VENDEDOR_15;CANAL_HORECA;URGENTE

Ejemplo:

{
  "etiqueta": "VENDEDOR_15;CANAL_HORECA"
}

No es un campo obligatorio.

Si no existe una necesidad operativa concreta, puede enviarse vacío u omitirse.

11. Cobros y formas de pago

11.1. importeCobrar

importeCobrar indica al conductor el importe que debe cobrar durante el servicio.

Se utiliza principalmente cuando:

• El servicio no contiene artículos.
• No se envían precios detallados.
• El ERP ya conoce el importe total que debe cobrarse.
• Se necesita mostrar directamente una cantidad al conductor.

Ejemplo:

{
  "importeCobrar": 125.5
}

Cuando se envían artículos, cantidades y precios, Logístiko puede obtener el importe a partir de la información del albarán.

En ese caso no es necesario duplicar el cálculo mediante importeCobrar, salvo que se necesite indicar expresamente una cantidad diferente.

importeCobrar debe representar el importe total que debe solicitarse al destinatario según la operativa definida.

11.2. tipoPago

tipoPago indica al conductor la forma de pago prevista.

Por ejemplo:

{
  "tipoPago": "CONTADO"
}

Otros posibles valores pueden ser configurados en Logistiko dentro de Ajustes

El valor se muestra al conductor en la aplicación.

Durante la entrega, el conductor puede registrar lo que haya ocurrido realmente, aunque la forma de pago real sea diferente de la prevista inicialmente.

Por ejemplo, el ERP puede indicar CONTADO, pero el destinatario puede terminar pagando mediante cheque o pagaré.

12. Artículos, bultos y costes

Los artículos y bultos pueden incluirse dentro del servicio cuando se necesite disponer de un albarán digital detallado.

La creación estándar permite trabajar con:

• Servicios sin artículos.
• Servicios con artículos.
• Servicios con bultos.
• Servicios con artículos y bultos.

12.1. Actualización de bultosLista

Al actualizar un servicio mediante Actualizar servicio V2:

• Si no se desea modificar los bultos, no debe enviarse bultosLista.
• También puede enviarse como null.
• Si se envía con contenido, los bultos existentes se actualizarán utilizando la información incluida en la nueva llamada.

Importante: no debe enviarse una lista parcial de bultos si se desea conservar el resto de los bultos existentes.

12.2. variableActualizarCoste

variableActualizarCoste indica si Logístiko debe actualizar el coste total utilizando el costeUnitario y la variable correspondiente al tipo de artículo.

La variable utilizada depende del tipo:

Cuando variableActualizarCoste es true, el coste se calcula o actualiza utilizando la variable correspondiente.

Artículo calculado por peso

Para un artículo de tipo 1:

coste total = costeUnitario × peso

Ejemplo:

{
  "tipo": 1,
  "peso": 12.5,
  "costeUnitario": 0.8,
  "variableActualizarCoste": true
}

Cálculo:

12,5 × 0,8 = 10,00

El coste resultante será 10,00.

Artículo calculado por unidades

Para un artículo de tipo 2:

coste total = costeUnitario × cantidad

Ejemplo:

{
  "tipo": 2,
  "cantidad": 6,
  "costeUnitario": 2.5,
  "variableActualizarCoste": true
}

Cálculo:

6 × 2,5 = 15,00

El coste resultante será 15,00.

Cuándo utilizarlo

Debe utilizarse cuando:

• El ERP envía un coste unitario.
• El coste total depende del peso.
• El coste total depende de las unidades.
• Logístiko debe recalcular el coste si cambia el peso o la cantidad.

No es necesario utilizarlo cuando:

• El ERP ya envía el coste total calculado.
• El artículo no tiene coste.
• No debe recalcularse el coste dentro de Logístiko.
• La información del artículo es únicamente descriptiva.

Importante: la correspondencia entre tipo, peso y unidades debe coincidir con la configuración acordada para los artículos de la integración.

Diferencia con importeCobrar

variableActualizarCoste e importeCobrar no representan lo mismo.

13. Actualización de datos maestros

Algunos campos de creación incluyen indicadores para actualizar datos maestros.

Cuando el indicador correspondiente se envía como true, Logístiko puede actualizar la información almacenada previamente.

Por ejemplo:

• Nombre del cliente.
• Dirección.
• Teléfono.
• Correo electrónico.
• Persona de contacto.
• Otros datos del destinatario.

Comportamiento por defecto

Si un dato ha sido corregido manualmente dentro de Logístiko, por defecto puede conservarse la información existente para evitar que el ERP la sobrescriba en cada servicio.

Comportamiento con actualización activa

Cuando el indicador de actualización se envía como true, el valor recibido desde el ERP reemplaza el dato almacenado en Logístiko.

Importante: los indicadores de actualización deben activarse cuando el ERP sea la fuente principal y fiable de ese dato.

No deben activarse automáticamente si los usuarios de Logístiko pueden corregir o enriquecer la información y se desea conservar esos cambios.

14. Formularios específicos

El campo formularioEspecificoLista permite asociar formularios concretos a un servicio.

En la mayoría de las integraciones no es necesario informarlo.

Lo habitual es utilizar formularios estándar configurados directamente en Logístiko, por ejemplo:

• Formulario de inicio de ruta.
• Formulario de llegada.
• Formulario de entrega.
• Formulario de incidencia.
• Formulario de fin de ruta.

Solo debe enviarse formularioEspecificoLista cuando un servicio necesite un formulario diferente al habitual.

Si no se necesitan formularios específicos por servicio, el campo puede omitirse.

15. Identificación de servicios

Después de crear un servicio, se recomienda almacenar los identificadores devueltos por Logístiko.

Para actualizar un servicio mediante:

Actualizar servicio V2

puede identificarse la expedición mediante:

1. uniqueId
2. servicio
3. referenciaExterna

uniqueId

Es la opción recomendada para localizar de forma inequívoca el servicio en Logístiko.

Debe almacenarse después de la creación para utilizarlo en:

• Actualizaciones.
• Cancelaciones.
• Consultas.
• Despachos parciales.
• Resolución de duplicidades.
• Relación entre el ERP y Logístiko.

servicio

Permite buscar el servicio mediante su número o referencia principal.

Puede utilizarse cuando no se dispone todavía del uniqueId.

referenciaExterna

Permite localizar el servicio mediante la referencia externa enviada por el ERP.

Puede utilizarse como alternativa cuando sea única y estable.

Recomendación

Aunque durante las primeras pruebas puedan utilizarse servicio o referenciaExterna, se recomienda almacenar y utilizar el uniqueId devuelto por Logístiko para las operaciones posteriores.

16. Actualización de servicios

Los servicios pueden modificarse mediante:

Actualizar servicio V2

Entre otros datos pueden actualizarse:

• Referencia principal.
• Referencia externa.
• Dirección.
• Código postal.
• Localidad.
• Coordenadas.
• Comentarios.
• Teléfono.
• Correo electrónico.
• Contacto.
• Ruta de referencia.
• Etiqueta.
• Cantidad.
• Peso.
• Volumen.
• Horarios.
• Duración.
• Conductor.
• Prioridad.
• Fechas auxiliares.
• Bultos.
• Disponibilidad para asignación.

Actualización de dirección y coordenadas

Cuando se modifica la dirección deben enviarse conjuntamente los datos necesarios para identificar correctamente el destino.

Ejemplo:

{
  "uniqueId": "UNIQUE-ID-001",
  "direccion": "Calle Mayor 25",
  "codigoPostal": "28013",
  "localidad": "Madrid"
}

Si se envían coordenadas, deben incluirse también los datos obligatorios relacionados con la dirección.

17. Cancelación de servicios

Para Logístiko, cancelar un servicio significa que deja de estar disponible para ser asignado.

La cancelación puede realizarse mediante Actualizar servicio V2 enviando:

{
  "uniqueId": "UNIQUE-ID-001",
  "asignable": false
}

También puede identificarse el servicio mediante servicio o referenciaExterna:

{
  "servicio": "ALB-2026-001",
  "asignable": false
}

Valores de asignable:

Importante: antes de cancelar o modificar un servicio que ya está asignado, despachado o en ejecución, debe revisarse su estado operativo.

18. Sedes y conductores

Antes de comenzar las pruebas debe confirmarse qué sedes y conductores existen en el entorno.

Las sedes y los conductores pueden:

• Crearse desde el panel de Logístiko.
• Crearse mediante API.
• Corregirse posteriormente.
• Sincronizarse con los códigos utilizados por el ERP.

Cuando se utiliza sedeCodigo o conductorCodigo, ambos sistemas deben utilizar exactamente el mismo código.

Debe acordarse qué sistema será responsable de mantener los maestros:

• Logístiko.
• El ERP.
• Ambos sistemas mediante una sincronización.

También deben crearse previamente los conductores lógicos que se utilizarán como zonas o agrupaciones temporales.

19. Checklist antes de comenzar las pruebas

Modelo de asignación

• Se ha definido dónde se realizará la planificación.

• Se ha confirmado si el ERP conoce el conductor definitivo.

• Se ha confirmado si el ERP conoce la ruta.

• Se ha decidido si se utilizará rutaReferencia.

• Se ha confirmado si se utilizarán conductores lógicos.

• Se han creado los conductores lógicos necesarios.

• Se ha definido quién sustituirá el conductor lógico por el real.

• Se ha confirmado si el conductor seleccionará la ruta desde la app.

• Se ha definido si el despacho será manual o mediante API.

Datos maestros

• Las sedes están creadas.
• Los códigos de sede están sincronizados.
• Los conductores están creados.
• Los códigos de conductor están sincronizados.
• Los conductores lógicos están diferenciados de los reales.
• Se ha definido qué sistema actualizará los maestros.

Creación de servicios

• Se envía albaran.
• Se envía actividad.
• Se informa el código o el nombre del cliente.
• Las direcciones son completas y geolocalizables.
• Los horarios utilizan el formato correcto.
• Se ha definido el uso de etiqueta.
• Se ha definido el uso de importeCobrar.
• Se ha definido el uso de tipoPago.
• Se ha definido el uso de artículos y bultos.
• Se ha definido el comportamiento de variableActualizarCoste.
• Se han revisado los indicadores de actualización de maestros.

Identificadores

• Se almacenan los identificadores devueltos por Logístiko.
• Se almacena el uniqueId.
• Se ha definido el control de duplicados.
• Se ha definido cuándo utilizar servicio.
• Se ha definido cuándo utilizar referenciaExterna.

Actualizaciones y cancelaciones

• Se utiliza Actualizar servicio V2.
• Se utiliza preferentemente uniqueId.
• La cancelación utiliza asignable: false.
• No se reemplaza accidentalmente bultosLista.