Ciclo de vida del Dispatch (Sync)

Una vez creado un dispatch con /transportes/sync/dispatch, los sistemas externos pueden ejecutar el flujo completo sin necesidad de la app del chofer usando estos endpoints.

Autenticación: todos usan el header Authorization: Bearer <token> (AuthSyncToken), igual que el resto de endpoints /sync/*.

Estados del dispatch

1. Iniciar dispatch

También puede identificarse por source_id externo:

{
  "dispatch_source_id": "guia.despacho:501",
  "source_system": "external_erp"
}

Campos

Proporcionar dispatch_id o (dispatch_source_id + source_system).

Response

{
  "ok": true,
  "code": "SYNC_OK",
  "data": {
    "dispatch_id": 501,
    "statusOk": true,
    "message": "Dispatch started successfully."
  },
  "meta": {
    "route": "/transportes/sync/dispatch/start",
    "method": "PostDispatchStartSync",
    "upsert_action": "processed"
  }
}

2. Iniciar un stop (task/start)

Campos

Valores de task_type

Recomendación: usar dispatch_stop_id siempre que sea posible. task_type + document_id es el método legado; requiere que el documento esté en un dispatch activo del mismo driver.

3. Completar un stop (task/complete)

Campos

Campos de lines[]

Cuando delivered_quantity == expected_quantity para todas las líneas, el documento se marca COMPLETA (4). El dispatch se marca COMPLETA automáticamente al completar el último stop activo.

4. Cancelar un stop (task/cancel)

Campos

5. Confirmar recolección (pickup/status)

Acciones disponibles

Campos

6. Consultar dispatch por source_id

Requiere el query param source_system:

GET /transportes/sync/dispatch/guia.despacho:501?source_system=external_erp

Response

{
  "ok": true,
  "code": "SYNC_OK",
  "data": {
    "dispatch_id": 501,
    "status_id": 3,
    "status_description": "EN_TRANSITO",
    "driver_id": 1,
    "vehicle_id": 12,
    "stops": [...]
  }
}

Flujo completo de ejemplo

1. POST /sync/receipts          → receipt_id: 101
2. POST /sync/pickups           → purchase_order_id: 201
3. POST /sync/dispatch          → dispatch_id: 501
4. POST /sync/dispatch/start    → dispatch ASIGNADA → EN_TRANSITO
5. POST /sync/dispatch/task/start  (stop hub de inicio)
6. POST /sync/dispatch/task/start  (stop ENT_FAC receipt 101)
7. POST /sync/dispatch/task/complete (receipt 101 entregada, lines con quantidades)
8. POST /sync/dispatch/pickup/status (OC 201 confirmada con CONFIRM → COMPLETE)
9. POST /sync/dispatch/task/start + task/complete (stop hub de fin)
   → dispatch auto-completa a COMPLETA (4)
10. POST /sync/returns          → return_id: 301 (desde receipt 101)
11. POST /sync/dispatch          → dispatch de return con stop REC_DEV
12. POST /sync/dispatch/start + task/start + task/complete del return

Nota: dispatch_stop_id es la forma recomendada de identificar un stop. Se obtiene del campo stops[].dispatch_stop_id en la respuesta de GET /sync/dispatch/{source_id}.