¿Es obligatorio enviar artículos o bultos?

No.

Pueden crearse:

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

La información debe enviarse según las necesidades de la operativa.

¿Qué datos mínimos debemos enviar del cliente?

Debe informarse al menos uno de estos datos:

• Código del cliente.
• Nombre del cliente.

No pueden estar vacíos ambos valores al mismo tiempo.

También es recomendable enviar una dirección completa y geolocalizable.

¿Qué valor debemos enviar en actividad?

Los valores habituales son:

Asignación y planificación

¿Qué debemos enviar si toda la planificación se realiza en Logístiko?

Los campos de asignación pueden enviarse vacíos u omitirse:

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

Logístiko realizará posteriormente:

• La asignación.
• La agrupación.
• La creación de rutas.
• La ordenación.
• La optimización.
• El despacho.

¿Qué información ayuda a mejorar la planificación?

Es recomendable enviar:

• Dirección completa.
• Código postal.
• Localidad.
• Coordenadas.
• Fecha deseada.
• Horarios.
• Peso.
• Volumen.
• Cantidad.
• Bultos.
• Duración de parada.
• Prioridad.
• Observaciones.

Cuanta más información operativa se proporcione, mejor podrá realizarse la planificación.

El ERP conoce la zona, pero no el conductor. ¿Qué debemos enviar?

Si una persona realizará posteriormente la planificación desde Logístiko, puede crearse un conductor lógico y enviar su código.

Ejemplo:

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

Después, desde la pantalla de planificación, se sustituye ZONA_NORTE por el conductor real.

¿Podemos utilizar conductorCodigo como nombre de zona?

Sí.

Para ello debe crearse previamente un conductor lógico con ese código.

Ejemplo:

Código del conductor lógico: ZONA_NORTE

El ERP enviará:

{
  "conductorCodigo": "ZONA_NORTE"
}

Logístiko lo tratará inicialmente como un conductor y agrupará bajo ese código los servicios correspondientes.

Antes del despacho debe reasignarse al conductor real.

¿Podemos utilizar conductorCodigo como nombre de ruta?

Sí.

Puede crearse un conductor lógico cuyo código represente una ruta o agrupación.

Ejemplo:

{
  "conductorCodigo": "RUTA_MADRID_01"
}

Este modelo es adecuado cuando:

• El ERP tiene una ruta preasignada.
• Todavía no conoce el conductor.
• Una persona realizará después la planificación.
• La agrupación debe visualizarse como una asignación temporal.

Antes de despachar, RUTA_MADRID_01 debe sustituirse por el conductor real.

¿El conductor lógico debe existir en Logístiko?

Sí.

Aunque represente una zona o una ruta, conductorCodigo sigue siendo técnicamente un código de conductor.

El código debe existir previamente en el maestro de conductores.

¿Qué ocurre si el conductor lógico no existe?

El servicio puede crearse, pero no quedará asociado al conductor esperado.

La respuesta puede incluir:

201 - OK, but driver not found

No debe volver a crearse el servicio.

Debe crearse o corregirse el conductor y asignar posteriormente el servicio.

¿Se puede despachar una ruta asignada a un conductor lógico?

No es recomendable.

Antes del despacho debe sustituirse el conductor lógico por el conductor real que realizará la ruta.

Un código como ZONA_NORTE o RUTA_15 puede utilizarse para agrupar, pero no representa necesariamente a un usuario real de la aplicación.

El ERP conoce la ruta, pero no el conductor. ¿Qué debemos enviar?

Debe enviarse rutaReferencia:

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

Posteriormente la ruta puede:

• Ser seleccionada por el conductor desde la aplicación.
• Ser asignada desde la planificación.
• Ser despachada mediante API.

¿Qué diferencia hay entre utilizar una ruta en conductorCodigo y utilizar rutaReferencia?

Utilice conductorCodigo como agrupador lógico cuando:

• Una persona realizará posteriormente la planificación.
• Se quiere visualizar la agrupación como una asignación temporal.
• Se sustituirá manualmente por el conductor definitivo.

Utilice rutaReferencia cuando:

• La ruta ya está definida en el ERP.
• El conductor seleccionará la ruta desde la aplicación.
• La ruta se despachará mediante API.
• No se necesita crear un conductor lógico.

¿Puede el conductor seleccionar una ruta desde la aplicación?

Sí, cuando esta funcionalidad está configurada.

El conductor introduce o selecciona el código enviado en rutaReferencia.

Ejemplo:

RUTA-15

La ruta y sus servicios quedan asociados al conductor que realiza la acción.

¿Qué debemos enviar si el ERP conoce el conductor real?

Debe enviarse su código dentro de conductorCodigo:

{
  "conductorCodigo": "CONDUCTOR_23"
}

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

¿Podemos enviar al mismo tiempo conductor y ruta?

Sí.

Ejemplo:

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

Esto permite conservar la referencia de ruta del ERP y la asignación al conductor real.

¿Para qué sirve el campo zona?

El campo zona permite conservar una clasificación territorial u operativa del servicio.

Puede utilizarse para:

• Mostrar información.
• Buscar servicios.
• Filtrar.
• Ayudar durante la planificación.
• Aplicar reglas configuradas previamente.

Informar zona no significa necesariamente que el servicio vaya a asignarse automáticamente a un conductor.

Despacho de rutas

¿Podemos despachar automáticamente utilizando el código de ruta?

Sí.

Después de crear los servicios con rutaReferencia, puede utilizarse el endpoint:

Despachar ruta

Ejemplo conceptual:

{
  "rutaReferencia": "RUTA-15"
}

¿Podemos despachar automáticamente utilizando el código de conductor?

Sí.

Los servicios deben estar asignados previamente al conductor real.

Ejemplo:

{
  "conductorCodigo": "CONDUCTOR_23"
}

No debe utilizarse para el despacho un conductor lógico que represente una zona o agrupación temporal.

¿Podemos filtrar el despacho por ruta y conductor?

Sí.

Pueden enviarse ambos campos:

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

Esto permite limitar con mayor precisión los servicios que se incluirán en la ruta.

¿Cómo despachamos únicamente algunos servicios?

Puede utilizarse uniqueIdList:

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

De esta forma no se incluyen automáticamente todos los servicios que cumplen el resto de los filtros.

¿Se puede conservar el orden enviado por el ERP?

El endpoint de despacho puede incluir un indicador para conservar el orden actual de los servicios.

Debe acordarse durante la integración si:

• Logístiko optimizará el orden.
• Se conservará el orden definido por el ERP.
• El orden se revisará manualmente antes del despacho.

Etiquetas y datos auxiliares

¿Es obligatorio enviar etiqueta?

No.

Debe enviarse únicamente cuando se necesite mostrar, filtrar o agrupar información adicional.

¿Qué información puede enviarse en etiqueta?

Puede enviarse información como:

• Vendedor.
• Comercial.
• Canal.
• Departamento.
• Tipo de cliente.
• Prioridad operativa.
• Clasificación interna.

Pueden enviarse varios valores separados por punto y coma:

{
  "etiqueta": "VENDEDOR_15;CANAL_HORECA;URGENTE"
}

¿Para qué puede utilizarse etiqueta?

Puede utilizarse para:

• Mostrar información adicional en planificación.
• Filtrar servicios.
• Hacer seguimiento por comercial.
• Diferenciar departamentos.
• Identificar tipos de pedido.
• Facilitar la gestión operativa.

Cobros y formas de pago

¿Qué representa importeCobrar?

Representa el importe que el conductor debe cobrar al destinatario.

Ejemplo:

{
  "importeCobrar": 125.5
}

Debe corresponder con la cantidad total que debe solicitarse durante la entrega.

¿importeCobrar debe incluir IVA?

Debe enviarse el importe final que el conductor debe cobrar según la operativa definida.

Si el conductor debe cobrar el total del documento con impuestos incluidos, debe enviarse ese importe total.

¿Debemos enviar importeCobrar si enviamos artículos y precios?

No siempre.

Cuando Logístiko puede calcular el importe utilizando los artículos, cantidades y precios del albarán, no es necesario duplicar el cálculo.

Puede enviarse cuando se necesite indicar expresamente un importe distinto o cuando no se envíen precios detallados.

¿Para qué sirve tipoPago?

Muestra al conductor la forma de pago prevista.

Ejemplo:

{
  "tipoPago": "CONTADO"
}

El conductor puede registrar posteriormente la forma de pago utilizada realmente.

¿tipoPago limita las formas de pago que puede registrar el conductor?

El valor representa la forma de pago prevista procedente del ERP.

La forma de pago real puede ser diferente.

Por ejemplo, el ERP puede indicar CONTADO, pero el destinatario puede pagar mediante:

• Cheque.
• Pagaré.
• Tarjeta.
• Efectivo.

El comportamiento exacto dependerá de la configuración de la aplicación.

Artículos, bultos y costes

¿Qué ocurre si no enviamos bultosLista al actualizar un servicio?

Si no se desea modificar los bultos, bultosLista debe omitirse o enviarse como null.

Los bultos existentes se conservarán.

¿Qué ocurre si enviamos bultosLista con contenido?

Los bultos del servicio se actualizarán utilizando la información enviada.

No debe enviarse una lista parcial si se desea conservar otros bultos existentes.

¿Qué hace variableActualizarCoste?

variableActualizarCoste indica qué atributo debe utilizar Logístiko como base para calcular o recalcular los importes del artículo o bulto a partir de costeUnitario.

No es un campo booleano. Debe enviarse como un número entero.

Cuando se utiliza el valor 0, se aplica el comportamiento general o la configuración establecida para la integración, sin seleccionar mediante este campo una variable concreta.

Los impuestos, descuentos y recargos se gestionan mediante sus campos específicos:

• ivaPorcentaje
• descuentoPorcentaje
• recargoPorcentaje

¿Cómo se calcula el coste de un artículo por peso?

Para calcular el importe utilizando el peso debe enviarse:

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

El cálculo del importe base es:

costeUnitario × peso

Resultado:

0,80 × 12,5 = 10,00

En este caso, costeUnitario representa el coste correspondiente a una unidad de peso.

¿Cómo se calcula el coste de un artículo por unidades?

Para calcular el importe utilizando la cantidad o el número de unidades debe enviarse:

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

El cálculo del importe base es:

costeUnitario × cantidad

Resultado:

2,50 × 6 = 15,00

En este caso, costeUnitario representa el coste de cada unidad.

¿Cómo se calcula el coste de un artículo por volumen?

Para calcular el importe utilizando el volumen debe enviarse:

{
  "volumen": 3.5,
  "costeUnitario": 4,
  "variableActualizarCoste": 3
}

El cálculo del importe base es:

costeUnitario × volumen

Resultado:

4,00 × 3,5 = 14,00

En este caso, costeUnitario representa el coste correspondiente a una unidad de volumen.

¿Qué ocurre si se aplican impuestos, descuentos o recargos?

El resultado calculado a partir de costeUnitario y la variable seleccionada constituye el importe base del artículo o bulto.

El importe final puede verse afectado por los siguientes campos:

Ejemplo:

{
  "cantidad": 6,
  "costeUnitario": 2.5,
  "variableActualizarCoste": 2,
  "ivaPorcentaje": 21,
  "descuentoPorcentaje": 0,
  "recargoPorcentaje": "0"
}

El importe base antes de impuestos, descuentos y recargos es:

2,50 × 6 = 15,00

¿Cuándo debemos enviar variableActualizarCoste?

Debe enviarse con valor 1, 2 o 3 cuando:

• El ERP envía un coste unitario.
• Logístiko debe calcular o recalcular el importe del artículo o bulto.
• El importe depende del peso, la cantidad o el volumen.
• La magnitud utilizada puede cambiar durante la operativa.
• El importe debe actualizarse utilizando los valores registrados al inicio o al finalizar el servicio, cuando la integración esté configurada para ello.

Debe enviarse:

• Como 1 cuando el coste depende del peso.
• Como 2 cuando el coste depende de las unidades.
• Como 3 cuando el coste depende del volumen.
• Como 0 cuando no se quiera seleccionar mediante este campo una variable concreta para el cálculo.

Ejemplo dentro de bultosLista

{
  "bultosLista": [
    {
      "barcode": "BULTO-0001",
      "nombre": "Caja de producto",
      "cantidad": 6,
      "peso": 12.5,
      "volumen": 0.8,
      "costeUnitario": 2.5,
      "variableActualizarCoste": 2,
      "ivaPorcentaje": 21,
      "descuentoPorcentaje": 0,
      "recargoPorcentaje": "0",
      "pickup": 0
    }
  ]
}

En este ejemplo se utiliza cantidad como variable de cálculo porque:

{
  "variableActualizarCoste": 2
}

Por tanto, el importe base es:

2,50 × 6 = 15,00

¿variableActualizarCoste es lo mismo que importeCobrar?

No. Son conceptos diferentes.

Por ejemplo, un servicio puede contener artículos con costes calculados por unidades y, al mismo tiempo, indicar un importe total que debe cobrar el conductor:

{
  "importeCobrar": 150,
  "bultosLista": [
    {
      "barcode": "BULTO-0001",
      "cantidad": 6,
      "costeUnitario": 2.5,
      "variableActualizarCoste": 2
    }
  ]
}

El cálculo interno del artículo no modifica por sí mismo el significado de importeCobrar.

Actualización de datos maestros

¿Qué hacen los campos de actualización?

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

Puede aplicarse a datos como:

• Nombre del cliente.
• Dirección.
• Teléfono.
• Correo electrónico.
• Contacto.

¿Por qué los datos del ERP no sobrescriben siempre los datos de Logístiko?

Puede existir información corregida manualmente dentro de Logístiko.

Por defecto, estos cambios pueden conservarse para evitar que una dirección o dato incorrecto del ERP vuelva a sobrescribirlos.

¿Cuándo deben activarse los campos de actualización?

Deben activarse cuando el ERP sea la fuente principal y fiable del 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.

Formularios

¿Debemos enviar formularioEspecificoLista?

Normalmente no.

Los formularios habituales se configuran directamente en Logístiko.

Por ejemplo:

• Inicio de ruta.
• Llegada.
• Entrega.
• Incidencia.
• Fin de ruta.

Solo debe enviarse cuando un servicio necesite un formulario específico diferente.

Identificación y actualización de servicios

¿Es obligatorio utilizar uniqueId?

No es obligatorio para la creación inicial.

Sin embargo, después de crear el servicio se recomienda almacenar el uniqueId devuelto por Logístiko.

Es la opción recomendada para realizar:

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

¿Podemos actualizar un servicio sin uniqueId?

Sí.

Según la operación, el servicio también puede localizarse mediante:

• servicio
• referenciaExterna

Aun así, se recomienda utilizar uniqueId cuando esté disponible.

¿Cómo cancelamos un servicio?

Debe utilizarse Actualizar servicio V2 enviando:

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

Esto hace que el servicio deje de estar disponible para asignación.

¿Cancelar un servicio lo elimina?

No necesariamente.

En Logístiko, la cancelación mediante asignable: false significa que el servicio deja de estar disponible para nuevas asignaciones.

El servicio puede seguir existiendo para consulta, seguimiento o histórico.

¿Podemos volver a habilitar un servicio?

Cuando la operativa y el estado del servicio lo permitan, puede actualizarse nuevamente:

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

Debe revisarse previamente si el servicio estaba asociado a alguna ruta.

Sedes y conductores

¿Podemos crear conductores mediante API?

Sí.

También pueden crearse y modificarse desde Logístiko.

Antes de comenzar las pruebas debe acordarse qué sistema será responsable de mantener estos datos.

¿Podemos crear sedes mediante API?

Sí.

También pueden gestionarse desde Logístiko.

El valor enviado en sedeCodigo debe coincidir con una sede existente.

¿Los códigos deben coincidir exactamente?

Sí.

Los valores enviados en campos como:

• sedeCodigo
• conductorCodigo

deben coincidir exactamente con los códigos registrados en Logístiko.

¿Qué ocurre si enviamos un conductor que no existe?

El servicio puede crearse, pero no quedará asociado al conductor esperado.

La respuesta puede incluir:

201 - OK, but driver not found

Debe corregirse la asignación sin volver a crear el servicio.

Respuestas y errores

¿Qué debemos hacer si algunos pedidos se crean y otros fallan?

Debe revisarse:

• respuestaLista, con los pedidos creados correctamente.
• errorLista, con los pedidos que requieren revisión.

No debe reenviarse toda la petición.

Solo deben corregirse o reintentarse los pedidos afectados.

Para más información, consulte la guía Gestión de respuestas y errores de la API.

¿Qué ocurre si el servicio ya existe?

Dependiendo de las referencias coincidentes, la API puede devolver un error o la expedición existente.

No debe crearse automáticamente una nueva referencia sin revisar el pedido.

Cuando la respuesta indique que el servicio ya existe, deben utilizarse los identificadores devueltos para continuar el proceso.

¿Qué debemos hacer ante un error 429?

Debe esperarse antes de volver a realizar la llamada.

Se recomienda utilizar una espera progresiva y limitar el número de reintentos.

¿Qué debemos hacer ante un error 500?

Debe registrarse:

• La petición.
• La respuesta.
• El pedido afectado.
• La fecha y hora.

Puede realizarse un número limitado de reintentos si se considera un problema temporal.

Si el error persiste, debe revisarse con soporte.