Flujo 1: creación única del servicio y seguimiento mediante webhooks

Este flujo se utiliza cuando el ERP envía el servicio una sola vez, después de finalizar el documento o albarán, y no necesita actualizar su información antes del despacho.

A partir de la creación, la planificación y la ejecución se gestionan desde Logístiko. El ERP recibe las novedades mediante webhooks enviados por Logístiko.

Cuándo utilizar este flujo

Este modelo es adecuado cuando:

• El documento se encuentra completo en el momento de crear el servicio.
• El ERP no necesita modificar el servicio después de la planificación.
• La asignación y optimización se realizan en Logístiko.
• El cliente puede exponer un endpoint para recibir webhooks.
• El ERP necesita conocer en tiempo real los cambios de estado de la ruta y los servicios.

flowchart TB

    %% =========================
    %% 1. CREACIÓN
    %% =========================
    subgraph P1["1. Creación única del servicio"]
        direction LR

        E1["ERP<br/>Documento finalizado"]
        L1["Logístiko<br/>Crea el servicio"]

        E1 -->|"POST Crear servicios"| L1
    end

    %% =========================
    %% 2. PLANIFICACIÓN
    %% =========================
    subgraph P2["2. Asignación y optimización"]
        direction RL

        E2["ERP<br/>Sin intervención"]

        subgraph O2[" "]
            direction TB

            L2["Logístiko<br/>Asigna, agrupa y optimiza<br/>los servicios"]
        end

        O2 ~~~ E2
		end

    %% =========================
    %% 3. DESPACHO
    %% =========================
    subgraph P3["3. Despacho de la ruta"]
        direction RL

        E3["ERP<br/>Recibe los servicios<br/>asignados a la ruta"]

        subgraph O3[" "]
            direction TB

            L3A["Logístiko<br/>Despacha la ruta<br/>desde el panel"]

            A3["APP conductor<br/>Recibe la ruta"]

            L3B["Logístiko<br/>Envía el webhook de<br/>servicio asignado a ruta"]

            L3A -->|"Ruta despachada"| A3
            L3A --> L3B
        end

        O3 -->|"POST Webhook de despacho"| E3
    end

    %% =========================
    %% 4. INICIO DE RUTA
    %% =========================
    subgraph P4["4. Inicio de ruta"]
        direction RL

        E4["ERP<br/>Recibe los eventos<br/>de inicio de ruta"]

        subgraph O4[" "]
            direction TB

            A4F["APP conductor<br/>Completa el formulario<br/>de inicio de ruta"]

            L4F["Logístiko<br/>Envía el webhook del<br/>formulario de inicio"]

            A4S["APP conductor<br/>Inicia la ruta"]

            L4S["Logístiko<br/>Envía el webhook<br/>de ruta iniciada"]

            A4F --> L4F
            L4F --> A4S
            A4S --> L4S
        end

        O4 -->|"POST Webhooks de inicio"| E4
    end

    %% =========================
    %% 5. OPERATIVA DEL SERVICIO
    %% =========================
    subgraph P5["5. Operativa por servicio"]
        direction RL

        E5["ERP<br/>Recibe los eventos<br/>del servicio"]

        subgraph O5[" "]
            direction TB

            A5A["APP conductor<br/>Registra la llegada<br/>al destino"]

            L5A["Logístiko<br/>Envía el webhook<br/>de llegada al destino"]

            D5{"Resultado<br/>del servicio"}

            A5E["APP conductor<br/>Completa la entrega"]

            L5E["Logístiko<br/>Envía el webhook<br/>de servicio completado"]

            A5I["APP conductor<br/>Registra una incidencia"]

            L5I["Logístiko<br/>Envía el webhook<br/>de incidencia"]

            X5["Acción excepcional<br/>Se fuerza el estado<br/>del servicio"]

            L5F["Logístiko<br/>Envía el webhook<br/>de estado forzado"]

            A5A --> L5A
            L5A --> D5

            D5 -->|"Entregado"| A5E
            A5E --> L5E

            D5 -->|"Incidencia"| A5I
            A5I --> L5I

            D5 -.->|"Opcional"| X5
            X5 --> L5F
        end

        O5 -->|"POST Webhooks de servicio"| E5
    end

    %% =========================
    %% 6. FIN DE RUTA
    %% =========================
    subgraph P6["6. Fin de ruta"]
        direction RL

        E6["ERP<br/>Recibe el formulario<br/>de fin de ruta"]

        subgraph O6[" "]
            direction TB

            A6["APP conductor<br/>Completa el formulario<br/>de fin de ruta"]

            L6["Logístiko<br/>Envía el webhook del<br/>formulario de fin de ruta"]

            A6 --> L6
        end

        O6 -->|"POST Webhook de fin de ruta"| E6
    end

    %% Orden vertical
    P1 ~~~ P2
    P2 ~~~ P3
    P3 ~~~ P4
    P4 ~~~ P5
    P5 ~~~ P6

    %% Colores
    classDef erp fill:#15803d,stroke:#86efac,stroke-width:2px,color:#ffffff
    classDef logistiko fill:#075985,stroke:#7dd3fc,stroke-width:2px,color:#ffffff
    classDef app fill:#6d28d9,stroke:#c4b5fd,stroke-width:2px,color:#ffffff
    classDef inactive fill:#374151,stroke:#6b7280,stroke-width:1px,color:#d1d5db
    classDef decision fill:#4c1d95,stroke:#c4b5fd,stroke-width:2px,color:#ffffff
    classDef optional fill:#78350f,stroke:#fbbf24,stroke-width:2px,color:#ffffff

    class E1,E3,E4,E5,E6 erp
    class E2 inactive

    class L1,L2,L3A,L3B,L4F,L4S,L5A,L5E,L5I,L5F,L6 logistiko
    class A3,A4F,A4S,A5A,A5E,A5I,A6 app

    class D5 decision
    class X5 optional

    %% Contenedores
    style P1 fill:#111827,stroke:#475569,stroke-width:1px,color:#f8fafc
    style P2 fill:#111827,stroke:#475569,stroke-width:1px,color:#f8fafc
    style P3 fill:#111827,stroke:#475569,stroke-width:1px,color:#f8fafc
    style P4 fill:#111827,stroke:#475569,stroke-width:1px,color:#f8fafc
    style P5 fill:#111827,stroke:#475569,stroke-width:1px,color:#f8fafc
    style P6 fill:#111827,stroke:#475569,stroke-width:1px,color:#f8fafc

    style O2 fill:transparent,stroke:transparent,color:transparent
    style O3 fill:transparent,stroke:transparent,color:transparent
    style O3 fill:transparent,stroke:transparent,color:transparent
    style O4 fill:transparent,stroke:transparent,color:transparent
    style O5 fill:transparent,stroke:transparent,color:transparent
    style O6 fill:transparent,stroke:transparent,color:transparent

    linkStyle default stroke:#94a3b8,stroke-width:2px

    %% Documentación
    click L1 "https://logistiko.readme.io/reference/servicios-crear" "Ver Crear servicios"
    click L3B "https://logistiko.readme.io/reference/webhookserviceassignedtoroute" "Ver webhook de servicio asignado a ruta"
    click L4F "https://logistiko.readme.io/reference/webhookroutestartform" "Ver webhook del formulario de inicio"
    click L4S "https://logistiko.readme.io/reference/webhookroutestarted" "Ver webhook de ruta iniciada"
    click L5A "https://logistiko.readme.io/reference/webhookservicearrived" "Ver webhook de llegada al destino"
    click L5E "https://logistiko.readme.io/reference/webhookservicecompleted" "Ver webhook de servicio completado"
    click L5I "https://logistiko.readme.io/reference/webhookserviceincidence" "Ver webhook de incidencia"
    click L5F "https://logistiko.readme.io/reference/webhookserviceforcedstatus" "Ver webhook de estado forzado"
    click L6 "https://logistiko.readme.io/reference/webhookrouteendform" "Ver webhook del formulario de fin de ruta"

Flujo 2: creación única del servicio y consulta periódica del estado

Este flujo se utiliza cuando el ERP envía el servicio una sola vez, después de finalizar el documento o albarán, pero no puede recibir webhooks por limitaciones técnicas.

La planificación y la ejecución se gestionan en Logístiko. Para conocer las novedades, el ERP consulta periódicamente el estado de cada servicio.

Cuándo utilizar este flujo

Este modelo es adecuado cuando:

• El documento se encuentra completo en el momento de crear el servicio.
• El ERP no necesita actualizar el servicio después de la planificación.
• La asignación y optimización se realizan en Logístiko.
• El sistema del cliente no puede exponer un endpoint público para webhooks.
• El ERP puede realizar consultas periódicas a la API de Logístiko.

Se recomienda utilizar webhooks siempre que sea posible. La consulta periódica genera más llamadas y puede introducir retrasos entre el cambio de estado y su recepción en el ERP.

flowchart TB

    %% =========================
    %% 1. CREACIÓN
    %% =========================
    subgraph P1["1. Creación única del servicio"]
        direction LR

        E1["ERP<br/>Documento finalizado"]
        L1["Logístiko<br/>Crea el servicio"]

        E1 -->|"POST Crear servicios"| L1
    end

    %% =========================
    %% 2. PLANIFICACIÓN
    %% =========================
    subgraph P2["2. Asignación y optimización"]
        direction RL

        E2["ERP<br/>Sin intervención"]

        subgraph O2[" "]
            direction TB

            L2["Logístiko<br/>Asigna, agrupa y optimiza<br/>los servicios"]
        end

        O2 ~~~ E2
		end

    %% =========================
    %% 3. DESPACHO
    %% =========================
    subgraph P3["3. Despacho de la ruta"]
        direction LR

        E3["ERP<br/>No recibe webhook<br/>de despacho"]

        subgraph O3[" "]
            direction TB

            L3["Logístiko<br/>Despacha la ruta<br/>desde el panel"]

            A3["APP conductor<br/>Recibe la ruta"]

            L3 -->|"Ruta despachada"| A3
        end

        E3 ~~~ O3
    end

    %% =========================
    %% 4. OPERATIVA
    %% =========================
    subgraph P4["4. Operativa del conductor"]
        direction LR

        E4["ERP<br/>No recibe webhooks"]

        subgraph O4[" "]
            direction TB

            A4A["APP conductor<br/>Completa el formulario<br/>de inicio de ruta"]

            A4B["APP conductor<br/>Inicia la ruta"]

            A4C["APP conductor<br/>Registra la llegada<br/>al destino"]

            A4D["APP conductor<br/>Completa la entrega<br/>o registra una incidencia"]

            A4E["APP conductor<br/>Completa el formulario<br/>de fin de ruta"]

            L4["Logístiko<br/>Actualiza los estados,<br/>fechas y evidencias"]

            A4A --> A4B
            A4B --> A4C
            A4C --> A4D
            A4D --> A4E
            A4E --> L4
        end

        E4 ~~~ O4
    end

    %% =========================
    %% 5. CONSULTA DE ESTADO
    %% =========================
    subgraph P5["5. Consulta periódica del estado"]
        direction LR

        E5["ERP<br/>Consulta el estado<br/>de cada servicio"]

        L5["Logístiko<br/>Devuelve el estado actual<br/>del servicio"]

        E5 -->|"GET Obtener estado"| L5
        L5 -.->|"Respuesta con el estado actual"| E5
    end

    %% Orden vertical
    P1 ~~~ P2
    P2 ~~~ P3
    P3 ~~~ P4
    P4 ~~~ P5

    %% Colores
    classDef erp fill:#15803d,stroke:#86efac,stroke-width:2px,color:#ffffff
    classDef logistiko fill:#075985,stroke:#7dd3fc,stroke-width:2px,color:#ffffff
    classDef app fill:#6d28d9,stroke:#c4b5fd,stroke-width:2px,color:#ffffff
    classDef inactive fill:#374151,stroke:#6b7280,stroke-width:1px,color:#d1d5db

    class E1,E5 erp
    class E2,E3,E4 inactive

    class L1,L2,L3,L4,L5 logistiko
    class A3,A4A,A4B,A4C,A4D,A4E app

    %% Contenedores
    style P1 fill:#111827,stroke:#475569,stroke-width:1px,color:#f8fafc
    style P2 fill:#111827,stroke:#475569,stroke-width:1px,color:#f8fafc
    style P3 fill:#111827,stroke:#475569,stroke-width:1px,color:#f8fafc
    style P4 fill:#111827,stroke:#475569,stroke-width:1px,color:#f8fafc
    style P5 fill:#111827,stroke:#475569,stroke-width:1px,color:#f8fafc

    style O2 fill:transparent,stroke:transparent,color:transparent
    style O3 fill:transparent,stroke:transparent,color:transparent
    style O4 fill:transparent,stroke:transparent,color:transparent

    linkStyle default stroke:#94a3b8,stroke-width:2px

    %% Documentación
    click L1 "https://logistiko.readme.io/reference/servicios-crear" "Ver Crear servicios"
    click E5 "https://logistiko.readme.io/reference/servicios-obtener-estado" "Ver Obtener estado del servicio"
    click L5 "https://logistiko.readme.io/reference/servicios-obtener-estado" "Ver Obtener estado del servicio"

Flujo 3: creación como pedido, actualización a albarán y predespacho opcional

Este flujo se utiliza cuando el servicio se crea en Logístiko a partir de un pedido, antes de que el albarán definitivo esté disponible.

De esta forma, Logístiko puede comenzar la planificación anticipadamente. Cuando el ERP genera el albarán, actualiza el mismo servicio para sustituir la referencia del pedido por la referencia definitiva del albarán.

El webhook de predespacho es opcional. Solo debe utilizarse cuando el ERP necesite información de la asignación realizada por Logístiko para completar o recalcular los datos del servicio antes del despacho.

Cuándo utilizar este flujo

Este modelo es adecuado cuando:

• El ERP dispone inicialmente de un pedido, pero todavía no ha generado el albarán.
• Logístiko necesita recibir los servicios antes de la finalización del albarán para comenzar la planificación.
• El número de albarán todavía no existe en el momento de la creación.
• Los artículos, cantidades, pesos u otros datos pueden cambiar entre el pedido y el albarán.
• El ERP debe actualizar el servicio cuando se genere el documento definitivo.
• Opcionalmente, el ERP necesita conocer la ruta, el conductor, el vehículo, la posición o la hora estimada antes de completar la actualización.
• Los cambios deben estar disponibles antes de que la ruta llegue a la aplicación del conductor.

{
  "albaran": "PED-2026-00125",
  "documentoConcepto": "Pedido"
}

[
  {
    "uniqueId": "687000000000000000000001",
    "serviceRef": "PED-2026-00125",
    "serviceIdOrder": "PED-2026-00125",
    "routeRef": "RUTA-15",
    "driverCode": "CONDUCTOR-01",
    "licensePlate": "1234-ABC",
    "servicePos": 4,
    "dateEstimated": 1784536200000,
    "status": 40
  }
]

{
  "uniqueId": "687000000000000000000001",
  "referenciaNueva": "ALB-2026-00457",
  "referenciaExternaNueva": "PED-2026-00125",
  "documentoConcepto": "Albaran"
}

Referencia principal: PED-2026-00125
Referencia externa: -
Documento: Pedido

Referencia principal: ALB-2026-00457
Referencia externa: PED-2026-00125
Documento: Albaran

{
  "uniqueId": "687000000000000000000001",
  "referenciaNueva": "ALB-2026-00457",
  "referenciaExternaNueva": "PED-2026-00125",
  "documentoConcepto": "Albaran",
  "cantidad": 8,
  "peso": 124.5
}

ERP crea el servicio como Pedido
→ Logístiko planifica
→ ERP genera el albarán
→ ERP actualiza Pedido a Albaran
→ Logístiko actualiza la planificación
→ Logístiko despacha la ruta
→ La ruta llega a la aplicación

ERP crea el servicio como Pedido
→ Logístiko planifica
→ Logístiko envía el webhook de predespacho
→ ERP utiliza la asignación para generar o completar el albarán
→ ERP actualiza Pedido a Albaran
→ Logístiko actualiza la planificación
→ Logístiko despacha la ruta
→ La ruta llega a la aplicación

flowchart TB

    %% =========================
    %% 1. CREACIÓN COMO PEDIDO
    %% =========================
    subgraph P1["1. Creación inicial como pedido"]
        direction LR

        E1["ERP<br/>Genera el pedido"]
        L1["Logístiko<br/>Crea el servicio con<br/>documentoConcepto = 'Pedido'"]

        E1 -->|"POST Crear servicios"| L1
    end

    %% =========================
    %% 2. PLANIFICACIÓN Y PREDESPACHO OPCIONAL
    %% =========================
    subgraph P2["2. Planificación y predespacho opcional"]
        direction RL

        E2["ERP<br/>Continúa con la generación<br/>o finalización del albarán"]

        subgraph O2[" "]
            direction TB

            L2A["Logístiko<br/>Asigna y optimiza<br/>los servicios"]

            D2{"¿El ERP necesita información<br/>de la asignación para<br/>actualizar los servicios?"}

            L2B["Logístiko<br/>Envía el webhook<br/>de predespacho"]

            L2A --> D2
            D2 -->|"Sí"| L2B
        end

        L2B -->|"POST Webhook de predespacho<br/>(opcional)"| E2
        D2 -.->|"No necesita la asignación"| E2
    end

    %% =========================
    %% 3. PEDIDO A ALBARÁN
    %% =========================
    subgraph P3["3. Actualización de pedido a albarán"]
        direction LR

        E3["ERP<br/>Finaliza el albarán y actualiza:<br/>referenciaNueva = nº de albarán<br/>referenciaExternaNueva = nº de pedido (opcional)<br/>documentoConcepto = 'Albaran'<br/>Artículos actualizados si han cambiado"]

        L3["Logístiko<br/>Actualiza el mismo servicio<br/>y sustituye la referencia<br/>principal del pedido"]

        E3 -->|"POST Actualizar servicio V2"| L3
    end

    %% =========================
    %% 4. REVISIÓN Y DESPACHO
    %% =========================
    subgraph P4["4. Actualización de la planificación y despacho"]
        direction RL

        E4["ERP<br/>Recibe la asignación<br/>finalmente despachada"]

        subgraph O4[" "]
            direction TB

            L4A["Logístiko<br/>Actualiza la planificación<br/>con los cambios del ERP"]

            L4B["Logístiko<br/>Revisa y despacha<br/>la ruta desde el panel"]

            A4["APP conductor<br/>Recibe la ruta"]

            L4C["Logístiko<br/>Envía el webhook de<br/>servicio asignado a ruta"]

            L4A --> L4B
            L4B -->|"Ruta despachada"| A4
            L4B --> L4C
        end

        O4 -->|"POST Webhook de despacho"| E4
    end

    %% =========================
    %% 5. INICIO DE RUTA
    %% =========================
    subgraph P5["5. Inicio de ruta"]
        direction RL

        E5["ERP<br/>Recibe los eventos<br/>de inicio de ruta"]

        subgraph O5[" "]
            direction TB

            A5F["APP conductor<br/>Completa el formulario<br/>de inicio de ruta"]

            L5F["Logístiko<br/>Envía el webhook del<br/>formulario de inicio"]

            A5S["APP conductor<br/>Inicia la ruta"]

            L5S["Logístiko<br/>Envía el webhook<br/>de ruta iniciada"]

            A5F --> L5F
            L5F --> A5S
            A5S --> L5S
        end

        O5 -->|"POST Webhooks de inicio"| E5
    end

    %% =========================
    %% 6. OPERATIVA DEL SERVICIO
    %% =========================
    subgraph P6["6. Operativa por servicio"]
        direction RL

        E6["ERP<br/>Recibe los eventos<br/>del servicio"]

        subgraph O6[" "]
            direction TB

            A6A["APP conductor<br/>Registra la llegada<br/>al destino"]

            L6A["Logístiko<br/>Envía el webhook<br/>de llegada al destino"]

            D6{"Resultado<br/>del servicio"}

            A6E["APP conductor<br/>Completa la entrega"]

            L6E["Logístiko<br/>Envía el webhook<br/>de servicio completado"]

            A6I["APP conductor<br/>Registra una incidencia"]

            L6I["Logístiko<br/>Envía el webhook<br/>de incidencia"]

            X6["Acción excepcional<br/>Se fuerza el estado<br/>del servicio"]

            L6F["Logístiko<br/>Envía el webhook<br/>de estado forzado"]

            A6A --> L6A
            L6A --> D6

            D6 -->|"Entregado"| A6E
            A6E --> L6E

            D6 -->|"Incidencia"| A6I
            A6I --> L6I

            D6 -.->|"Opcional"| X6
            X6 --> L6F
        end

        O6 -->|"POST Webhooks de servicio"| E6
    end

    %% =========================
    %% 7. FIN DE RUTA
    %% =========================
    subgraph P7["7. Fin de ruta"]
        direction RL

        E7["ERP<br/>Recibe el formulario<br/>de fin de ruta"]

        subgraph O7[" "]
            direction TB

            A7["APP conductor<br/>Completa el formulario<br/>de fin de ruta"]

            L7["Logístiko<br/>Envía el webhook del<br/>formulario de fin de ruta"]

            A7 --> L7
        end

        O7 -->|"POST Webhook de fin de ruta"| E7
    end

    %% Orden vertical
    P1 ~~~ P2
    P2 ~~~ P3
    P3 ~~~ P4
    P4 ~~~ P5
    P5 ~~~ P6
    P6 ~~~ P7

    %% Colores
    classDef erp fill:#15803d,stroke:#86efac,stroke-width:2px,color:#ffffff
    classDef logistiko fill:#075985,stroke:#7dd3fc,stroke-width:2px,color:#ffffff
    classDef app fill:#6d28d9,stroke:#c4b5fd,stroke-width:2px,color:#ffffff
    classDef decision fill:#4c1d95,stroke:#c4b5fd,stroke-width:2px,color:#ffffff
    classDef optional fill:#78350f,stroke:#fbbf24,stroke-width:2px,color:#ffffff

    class E1,E2,E3,E4,E5,E6,E7 erp

    class L1,L2A,L2B,L3,L4A,L4B,L4C,L5F,L5S,L6A,L6E,L6I,L6F,L7 logistiko
    class A4,A5F,A5S,A6A,A6E,A6I,A7 app

    class D2,D6 decision
    class X6 optional

    %% Contenedores
    style P1 fill:#111827,stroke:#475569,stroke-width:1px,color:#f8fafc
    style P2 fill:#111827,stroke:#475569,stroke-width:1px,color:#f8fafc
    style P3 fill:#111827,stroke:#475569,stroke-width:1px,color:#f8fafc
    style P4 fill:#111827,stroke:#475569,stroke-width:1px,color:#f8fafc
    style P5 fill:#111827,stroke:#475569,stroke-width:1px,color:#f8fafc
    style P6 fill:#111827,stroke:#475569,stroke-width:1px,color:#f8fafc
    style P7 fill:#111827,stroke:#475569,stroke-width:1px,color:#f8fafc

    style O2 fill:transparent,stroke:transparent,color:transparent
    style O4 fill:transparent,stroke:transparent,color:transparent
    style O5 fill:transparent,stroke:transparent,color:transparent
    style O6 fill:transparent,stroke:transparent,color:transparent
    style O7 fill:transparent,stroke:transparent,color:transparent

    linkStyle default stroke:#94a3b8,stroke-width:2px

    %% Documentación
    click L1 "https://logistiko.readme.io/reference/servicios-crear" "Ver Crear servicios"
    click L2B "https://logistiko.readme.io/reference/webhookpredispatch" "Ver webhook de predespacho"
    click E3 "https://logistiko.readme.io/reference/actualizar-servicio-v2" "Ver Actualizar servicio V2"
    click L3 "https://logistiko.readme.io/reference/actualizar-servicio-v2" "Ver Actualizar servicio V2"
    click L4C "https://logistiko.readme.io/reference/webhookserviceassignedtoroute" "Ver webhook de servicio asignado a ruta"
    click L5F "https://logistiko.readme.io/reference/webhookroutestartform" "Ver webhook del formulario de inicio"
    click L5S "https://logistiko.readme.io/reference/webhookroutestarted" "Ver webhook de ruta iniciada"
    click L6A "https://logistiko.readme.io/reference/webhookservicearrived" "Ver webhook de llegada al destino"
    click L6E "https://logistiko.readme.io/reference/webhookservicecompleted" "Ver webhook de servicio completado"
    click L6I "https://logistiko.readme.io/reference/webhookserviceincidence" "Ver webhook de incidencia"
    click L6F "https://logistiko.readme.io/reference/webhookserviceforcedstatus" "Ver webhook de estado forzado"
    click L7 "https://logistiko.readme.io/reference/webhookrouteendform" "Ver webhook del formulario de fin de ruta"