Puedes pegar un ejemplo de tu JSON, detectar automáticamente sus campos y relacionarlos visualmente con los campos de Logistiko. A partir de ese momento, Logistiko adapta cada petición entrante o cada webhook saliente según el mapping guardado.

Con el conector puedes:

• crear o actualizar clientes;
• crear servicios completos o servicios que referencian clientes existentes;
• enviar artículos dentro del servicio, enviarlos después o no utilizarlos;
• actualizar parcialmente servicios existentes;
• recibir webhooks únicamente de los eventos que te interesan;
• cambiar los nombres y la estructura de los campos sin modificar tu integración actual;
• convertir tipos, limpiar valores, aplicar valores por defecto y transformar fechas;
• probar la integración con un JSON precargado antes de utilizarla en producción;
• consultar el JSON original, el JSON transformado, la respuesta y los errores en los logs.

Tu sistema habla su propio idioma; el mapper se encarga de traducirlo al formato de Logistiko y viceversa.

Las tres partes del Conector API

El conector se divide en tres módulos independientes:

Cómo funciona el mapper

Supongamos que tu ERP ya genera este JSON:

{
  "order_id": "PED-2026-00125",
  "delivery_address": "Calle Mayor 25",
  "postal_code": "28013",
  "requested_date": "2026-08-18T09:30:00+02:00"
}

No tienes que renombrar sus propiedades. En el panel puedes configurar:

Cuando Logistiko recibe la petición, el mapper genera internamente el formato esperado:

{
  "albaran": "PED-2026-00125",
  "direccion": "Calle Mayor 25",
  "codigoPostal": "28013",
  "fechaDeseada": "2026-08-18T09:30:00+02:00"
}

En los webhooks sucede al revés. Si Logistiko genera uniqueId, puedes hacer que tu sistema reciba logistikoId, shipment_id o el nombre que necesite.

Configuración paso a paso

1. Define la integración

En Conector API → Creación indica:

• el nombre de la integración;
• su tipo de flujo;
• cuándo se enviarán los artículos;
• la key que identifica esa integración.

La configuración básica puede guardarse sin mapping. El mapping será necesario cuando quieras transformar y utilizar una entidad por API.

2. Pega un JSON de ejemplo

El editor admite un JSON real o representativo de tu sistema. Al pulsar Detectar campos, analiza:

• propiedades de primer nivel;
• objetos anidados, por ejemplo customer.address.city;
• arrays, por ejemplo orders[].items[].sku.

El ejemplo queda guardado con la configuración para editar el mapping y preparar pruebas, pero no interviene en las llamadas de producción.

3. Relaciona los campos

Desde el editor visual, para cada campo de Logistiko puedes elegir:

• el campo de origen de tu JSON;
• su tipo;
• una transformación;
• si es obligatorio;
• un valor por defecto;
• un formato de fecha;

Todos los campos Logistiko muestran una ayuda contextual que explica su propósito.

4. Guarda y prueba

En las configuraciones de Creación, después del mapping puedes abrir el paso Prueba, introducir las credenciales facilitadas por Logistiko y ejecutar una petición usando el JSON de ejemplo o una versión modificada.

Las pruebas son reales. Pueden crear o actualizar clientes y servicios, y pueden crear, actualizar o eliminar artículos.

La integración debe estar activa para que sus endpoints públicos acepten peticiones.

Autenticación

Las llamadas públicas utilizan las credenciales facilitadas por Logistiko:

apiKey: TU_API_KEY
userId: TU_USER_ID
Content-Type: application/json

También existe compatibilidad con apiKey y userId dentro del body, pero se recomienda enviarlas por cabecera. En Actualización, la empresa debe identificarse antes de aplicar el mapping, por lo que las cabeceras evitan depender de los nombres del JSON externo.

Creación de información

Varias configuraciones por empresa

Una empresa puede tener varias configuraciones de creación. Cada una dispone de su propia key, mappings, ejemplos, reglas y estado activo.

Esto permite, por ejemplo:

• conectar simultáneamente un ERP y un ecommerce;
• recibir formatos distintos desde dos clientes o delegaciones;
• separar una integración de pruebas de otra de producción;
• aplicar mappings distintos según el origen.

Flujo 1: documento completo

El flujo Documento completo se utiliza cuando cada servicio incluye toda la información necesaria:

servicio
├── cliente
├── artículos opcionales
├── facturas anteriores opcionales
└── respuestas de formularios opcionales

Se configura un único mapping de documento. Puede generar campos simples y destinos anidados como:

• cliente.clienteCodigo;
• cliente.direccion;
• bultosLista[].barcode;
• bultosLista[].cantidad;
• facturasPasadas[].referencia;
• formularioEspecificoLista[].pregunta.

Es la opción apropiada cuando tu ERP ya exporta cada pedido con su cliente y sus líneas dentro del mismo JSON.

Los artículos son opcionales: el documento puede crear un servicio aunque no incluya ninguna línea.

Endpoint:

POST /api/v2/integrations/{key}/services

Flujo 2: cliente por referencia

El flujo Por referencias separa clientes y servicios. Primero existe el cliente en Logistiko y después el servicio lo referencia mediante clienteCodigo o clienteId.

Este flujo admite mappings independientes para:

1. cliente;
2. servicio;
3. artículos, cuando se envían por separado.

El cliente puede haberse creado:

• mediante el endpoint del conector;
• manualmente en Logistiko;
• mediante una importación Excel;
• por cualquier otro proceso existente.

Si el servicio referencia un cliente inexistente, Logistiko rechaza la petición con CUSTOMER_NOT_FOUND y HTTP 422.

Crear o actualizar clientes

POST /api/v2/integrations/{key}/customers

El endpoint funciona como upsert por clienteCodigo:

• si el código no existe, crea el cliente;
• si ya existe, actualiza sus datos;
• mantiene la unicidad del código dentro de la empresa.

Crear servicios

POST /api/v2/integrations/{key}/services

Cada servicio debe poder identificarse mediante albaran o externalServiceId y debe indicar clienteCodigo o clienteId.

Opciones para los artículos

No utilizo artículos

Con itemsMode = NONE, la integración no espera artículos. No es necesario configurar un mapping de líneas.

Artículos incluidos en el servicio

Con itemsMode = EMBEDDED, los artículos llegan dentro de cada servicio y se mapean como parte del paso Servicio y artículos.

Ejemplo externo:

{
  "albaranes": [
    {
      "order_id": "SRV-10003",
      "customer_code": "CLI-000156",
      "items": [
        {
          "sku": "SKU-1",
          "quantity": 2
        }
      ]
    }
  ]
}

Configuración de paths:

Array de servicios: albaranes
Array de artículos: items

Mappings posibles:

order_id       → albaran
customer_code  → clienteCodigo
sku       → codigo
quantity  → cantidad

En el mapping de artículos esos paths son relativos a cada elemento de items; el editor ya entra en el array configurado.

Artículos después de crear el servicio

Con itemsMode = DEFERRED, primero se crea el servicio y después se sincroniza su colección de artículos:

POST /api/v2/integrations/{key}/services/{serviceId}/items

serviceId puede ser el ID Logistiko o una referencia reconocida del servicio.

La colección enviada representa el estado completo:

• las líneas nuevas se crean;
• las existentes se actualizan;
• las que ya no aparecen se eliminan.

La petición debe contener al menos un artículo. Una colección vacía se rechaza, por lo que este endpoint no se utiliza para eliminar todas las líneas de una vez.

Cada artículo se identifica por el primer valor disponible entre externalLineId, idExterno, barcode o codigo. No se permiten identificadores duplicados en una misma petición.

Arrays y paths configurables

El JSON no tiene que contener una única entidad en la raíz. Puedes indicar dónde se encuentra cada colección:

• documentArrayPath: documentos completos;
• customerArrayPath: clientes;
• serviceArrayPath: servicios;
• itemArrayPath: artículos.

Si el path queda vacío, la raíz se trata como la entidad. Si apunta a un array, el mapper procesa cada objeto de la colección.

Ejemplos:

pedidos
payload.orders
albaranes
data.customers
orders[].items

Actualización de servicios

Actualización es un módulo independiente y tiene una única configuración por empresa. No utiliza key.

Endpoint del conector:

POST /api/v2/integrations/updates

El endpoint:

1. autentica las credenciales e identifica la empresa;
2. carga su configuración de Actualización;
3. transforma el JSON externo;
4. construye un UpdateExpeditionRequest de Logistiko;
5. ejecuta la misma lógica de actualización que la API estándar.

JSON estándar o personalizado

Puedes elegir entre:

• JSON estándar de Logistiko: no se realiza ninguna transformación;
• JSON externo personalizado: cada campo se adapta mediante el mapping.

Si no existe configuración, está inactiva o el mapping personalizado está desactivado, el JSON pasa sin transformación.

La API estándar continúa disponible en:

POST /api/v2/updateExpedition/

Este endpoint recibe directamente un UpdateExpeditionRequest y no aplica el mapping del conector.

Cómo identificar el servicio

Un mapping personalizado debe producir al menos uno de estos campos:

La actualización es parcial: los campos omitidos o enviados como null no se modifican.

En este módulo las cadenas vacías sí se conservan. Esto permite limpiar valores existentes, por ejemplo:

{
  "phone": "",
  "comments": ""
}

si phone → contactPhone y comments → comments están mapeados.

Artículos durante una actualización

También se puede mapear una colección externa hacia itemProductList[]:

packages[].package_id → itemProductList[].barcode
packages[].sku        → itemProductList[].code
packages[].quantity   → itemProductList[].qty

Si se envía una lista con contenido, representa el conjunto de bultos del servicio: se crean los nuevos, se actualizan los coincidentes y se eliminan los que ya no aparecen. Una lista omitida, null o vacía no modifica los bultos actuales.

Devolución de información mediante webhooks

El módulo Devolución de información permite decidir qué eventos envía Logistiko y adaptar cada evento al contrato del sistema receptor.

La configuración es única por empresa, no usa key y trabaja sobre la URL y autorización de webhook configuradas para esa empresa en Logistiko.

Para cada evento puedes:

• activarlo o desactivarlo;
• utilizar el JSON estándar de Logistiko;
• crear un JSON personalizado;
• seleccionar únicamente los campos que quieres enviar;
• cambiar el nombre de cada propiedad;
• aplicar transformaciones desde el editor y, mediante configuración avanzada, valores por defecto.

Cada tipo de webhook dispone de su propio catálogo de campos. Un campo solo aparece si realmente puede existir en ese evento.

Dirección del mapping en webhooks

En Creación y Actualización:

campo externo → campo Logistiko

En Webhooks:

campo Logistiko → campo externo

Ejemplo:

uniqueId     → logistikoId
serviceRef   → deliveryNumber
dateArrive   → arrivedAt

El receptor podría recibir:

{
  "logistikoId": "689000000000000000000125",
  "deliveryNumber": "ALB-2026-000125",
  "arrivedAt": 1787043600000
}

Eventos disponibles

Recepción e incidencia de Picker son eventos independientes: cada uno puede activarse y mapearse por separado.

Información disponible según el evento

• Predespacho: planificación, ruta, conductor, vehículo, servicio, posición, fecha estimada, coordenadas y bultos.
• Sin asignar: identificadores del servicio, tracking, etiqueta, posición y localización.
• Asignado: añade ruta, conductor, vehículo y fecha estimada.
• Ruta iniciada: añade lectura de bultos al inicio de ruta.
• Llegada: fechas, notas y coordenadas de llegada y salida.
• Finalizado: resultados, POD, firma, fotografías, bultos, formularios, cobro y facturas anteriores.
• Incidencia: código y descripción de incidencia, notas, POD y evidencias disponibles.
• Estado forzado: datos de seguimiento y motivo de incidencia cuando exista.
• Formularios de ruta: datos de ruta, fecha, coordenadas y respuestas del formulario correspondiente.
• Picker: timestamp, uniqueId, status y código/descripción del estado o incidencia.

Si una empresa todavía no ha guardado una configuración de Webhooks, se mantiene el comportamiento compatible: se envían los eventos con el JSON estándar.

Capacidades del motor de mapping

Paths simples, anidados y arrays

El motor puede leer:

order_id
customer.code
shipping.address.city
lines[].sku
orders[].items[].quantity

También puede construir objetos y arrays de destino con paths como:

cliente.clienteCodigo
bultosLista[].barcode
itemProductList[].qty
facturasPasadas[].referencia

Tipos disponibles

Opciones por campo

Los campos sin origen, sin valor por defecto y sin ninguna regla se ignoran. El resultado solo contiene los campos configurados.

Transformaciones

El editor visual permite escoger una transformación por campo. El motor también admite una configuración avanzada con transformaciones encadenadas mediante |, por ejemplo:

trim|removeSpaces|toNumber|round

Campos alternativos y valores por defecto

Si diferentes orígenes llaman de forma distinta al mismo dato, la configuración avanzada admite alternativas:

source: customer.phone
fallbackSources:
  - customer.mobile
  - delivery.contact_phone
defaultValue: "SIN-TELEFONO"

El motor utiliza el primer valor disponible. Si ninguno existe, aplica el valor por defecto.

Validación

El conector valida:

• campos requeridos;
• targets permitidos para cada tipo de mapping;
• transformaciones soportadas;
• identificadores mínimos de cliente, servicio y artículo;
• duplicados de artículos;
• existencia del cliente en el flujo por referencias;
• existencia y pertenencia del servicio a la empresa autenticada;
• configuración activa y key correcta en los endpoints de creación.

Los errores de mapping indican el campo, código y motivo para facilitar su corrección.

Catálogo de campos de creación

Cliente

clienteCodigo
clienteNombre
clienteNombreFiscal
clienteCIF
dni
direccion
direccionDetalles
codigoPostal
ciudad
pais
latitud
longitud
telefono
email
contacto
clienteDireccionFiscal
clienteDireccionFiscalDetalles
clienteDireccionFiscalCP
clienteDireccionFiscalCiudad

Servicio

externalServiceId
albaran
ordenIdentificador
idExterno
referenciaExterna
documentoConcepto
fechaDeseada
fechaCreacion
fechaPreparacion
actividad
sedeCodigo
conductorCodigo
zona
comentarios
etiqueta
prioridad
cantidad
peso
volumen
importeCobrar
tipoPago
horarioDesde
horarioCierreInicio
horarioCierreFinal
horarioHasta
paradaDuracion
clienteCodigo
clienteId
update_contact
update_timeWindow
update_stop
update_address
update_dni
update_email
update_phone
update_fiscal
posicionServicio
rutaReferencia
customText1
customText2
customText3
customBoolean1
customBoolean2
customBoolean3
customDate1
customData2
customData3
customNumber1
customNumber2
customNumber3

Artículo

idExterno
externalLineId
codigo
barcode
nombre
descripcion
cantidad
peso
volumen
costeUnitario
ivaPorcentaje
descuentoPorcentaje
recargoPorcentaje
formato
variableActualizarCoste
pickup

Facturas anteriores en documento completo

facturasPasadas[].referencia
facturasPasadas[].importe
facturasPasadas[].descripcion
facturasPasadas[].tipoPago
facturasPasadas[].fecha

Respuestas de formularios en documento completo

formularioEspecificoLista[].pregunta
formularioEspecificoLista[].etiqueta
formularioEspecificoLista[].respuesta_predefinida
formularioEspecificoLista[].tipo

Catálogo de campos de actualización

Identificación y referencias

_id
idString
idOrderExternal
referenciaNueva
referenciaExternaNueva
documentConcept

Fechas, dirección y contacto

actualPreparationDate
actualCreationDate
shippingDate
dateKeep
address
addressCP
addressCity
destinationLatitude
destinationLongitude
contactPhone
contactEmail
contactName
contactDNI
comments

Planificación y carga

routeReference
carrierCode
familyA
priority
qty
load
loadVolumetric
serviceMinDate
serviceMaxDate
stop
driverCode
asignable

Artículos

itemProductList[].barcode
itemProductList[].code
itemProductList[].name
itemProductList[].qty
itemProductList[].weight
itemProductList[].volume
itemProductList[].height
itemProductList[].length
itemProductList[].width

Catálogo de campos de webhooks

Los campos exactos dependen del evento. Los principales son:

Servicio, planificación y ruta

timestamp
routeId
routeRef
driverId
driverCode
licensePlate
uniqueId
serviceId
serviceRef
serviceIdOrder
status
trackingLink
olKey
serviceLabel
servicePos
latitudeService
longitudeService
type
dateEstimated
barcodeReadStartRoute
barcodeReadCompleteService

Llegada, finalización e incidencia

dateArrive
dateDeparture
notesArrive
notesDeparture
notesIncidence
latitudeArrive
longitudeArrive
latitudeDeparture
longitudeDeparture
status1
status1Label
status2
status2Label
codeIncidence
labelIncidence

POD, artículos, formularios y cobro

podSign
podSignName
podSignID
podPhoto
podPhotoList
parcelList
form
transaction
previousInvoiceList

Formularios de ruta

timestamp
routeId
routeRef
driverId
driverCode
licensePlate
status
dateStart
latitudeStart
longitudeStart
dateFinish
latitudeFinish
longitudeFinish
form

Picker

timestamp
uniqueId
status
code
description

Endpoints públicos

Logs y diagnóstico

Las integraciones de creación permiten consultar llamadas y filtrar por fecha, estado, método, operación o referencia externa.

El detalle puede mostrar:

• JSON de entrada;
• JSON transformado;
• respuesta;
• código HTTP;
• duración;
• mensaje y código de error;
• referencias o identificadores relacionados.

Esto permite comprobar rápidamente si el problema está en el JSON recibido, en el mapping, en una validación o en la lógica de negocio.

Ejemplo completo

Tu ERP envía:

{
  "erp": "ERP_DEMO",
  "albaranes": [
    {
      "order_id": "SRV-10003",
      "customer_code": "CLI-000156",
      "concept": "Entrega urgente",
      "requested_delivery_date": "2026-08-10T08:00:00Z",
      "notes": "Llamar 30 minutos antes",
      "items": [
        {
          "sku": "SKU-1",
          "quantity": 2
        }
      ]
    }
  ]
}

Configuras:

Flujo: Por referencias
Artículos: Incluidos en el servicio
Array de servicios: albaranes
Array de artículos: items

order_id                 → albaran
customer_code            → clienteCodigo
concept                  → documentoConcepto
requested_delivery_date  → fechaDeseada
notes                    → comentarios
sku                      → codigo
quantity                 → cantidad

Logistiko recibe cada servicio y sus artículos en el formato interno correcto, sin exigir que el ERP modifique su modelo de datos.

Recomendaciones

• Usa identificadores estables y únicos para clientes, servicios y artículos.
• Envía apiKey y userId por cabecera.
• Utiliza fechas ISO 8601 siempre que sea posible.
• Pega ejemplos que representen también objetos anidados, arrays y campos opcionales.
• Marca como obligatorio únicamente lo imprescindible para procesar la entidad.
• Usa fallbackSources cuando convivan versiones distintas del JSON externo.
• Prueba primero con referencias claramente identificables como datos de prueba.
• Recuerda que las pruebas ejecutan operaciones reales.
• En artículos diferidos, envía siempre el conjunto completo que debe quedar asociado al servicio.
• En webhooks, activa solo los eventos que el sistema receptor pueda procesar.

El Conector API permite mantener tu integración actual y adaptar sus datos desde Logistiko. En la mayoría de los casos basta con pegar un JSON de ejemplo, detectar sus campos, relacionarlos visualmente y guardar la configuración.