Sincronización de Vehículos y Tipos

En esta sección se documentan los endpoints para sincronizar el catálogo de vehículos de la flota y sus clasificaciones por tipo, las cuales dictan las reglas base de capacidad para las rutas.

1. Tipos de Vehículo

POST/transportes/sync/vehicles/vehicle-types

Crea o actualiza tipos de vehículo y su capacidad base de carga.

Caso de uso

Crear tipos de vehículos desde el sistema externo.
Actualizar capacidad base de un tipo de vehículo.

Campos del Payload

Requeridos

Campo	Tipo	Descripción
`source_id`	string	ID único en el sistema de origen
`source_system`	string	Sistema externo (ej. `external_erp`)
`vehicle_type_description`	string	Nombre del tipo (ej. `Camion 3.5T`)

Opcionales

Campo	Tipo	Descripción
`is_active`	boolean	Estado activo
`vehicle_type_id`	int	ID interno del tipo
`min_weight`	number	Peso mínimo en kg
`max_weight`	number	Peso máximo en kg
`max_volume`	number	Volumen máximo en m³
`max_length`	number	Largo máximo en metros

Ejemplos

Request

{
  "source_id": "fleet.vehicle.model.category:3",
  "source_system": "external_erp",
  "vehicle_type_description": "Camion 3.5T",
  "min_weight": 0,
  "max_weight": 3500,
  "max_volume": 18,
  "max_length": 6
}

Response

{
  "ok": true,
  "code": "SYNC_OK",
  "message": "Sync processed successfully.",
  "data": 3,
  "meta": {
    "route": "/transportes/sync/vehicles/vehicle-types",
    "method": "PostVehicleTypeSync",
    "operation": "upsert",
    "upsert_action": "created",
    "timestamp": "2026-04-07T12:00:00.000Z"
  }
}

2. Vehículos

POST/transportes/sync/vehicles

Crea o actualiza vehículos. Permite configurar excepciones de capacidad sobre el tipo base.

Caso de uso

Crear vehículos desde flota u el sistema externo.
Definir capacidad adicional por vehículo.
Definir categorías o zonas que el vehículo puede cubrir.

Dependencias

vehicle_type_source_id requiere que el tipo de vehículo exista.
hub_source_id, driver_source_id y license_type_source_id requieren sus recursos correspondientes previamente sincronizados.

Campos del Payload

Requeridos

Campo	Tipo	Descripción
`source_id`	string	ID único en el sistema de origen
`source_system`	string	Sistema externo
`vehicle_type_id` / `vehicle_type_source_id`	int/string	Tipo de vehículo
`plate`	string	Placa del vehículo

Opcionales

Campo	Tipo	Descripción
`is_active`	boolean	Estado activo
`vehicle_id`	int	ID interno
`vehicle_type_model`	string	Modelo del tipo
`driver_id` / `driver_source_id`	int/string	Chofer asignado
`driver_model`	string	Modelo del chofer
`vehicle_description`	string	Descripción del vehículo
`is_enabled`	boolean	Habilitado para operar
`extra_weight`	number	Peso adicional permitido (kg)
`extra_volume`	number	Volumen adicional (m³)
`extra_length`	number	Largo adicional (metros)
`categories`	string[] / string	Categorías o zonas habilitadas
`hub_id` / `hub_source_id`	int/string	Sede asignada
`hub_model`	string	Modelo del hub
`license_type_id` / `license_type_source_id`	int/string	Tipo de licencia requerida
`license_type_model`	string	Modelo del tipo de licencia

Ejemplos

Request

{
  "source_id": "fleet.vehicle:12",
  "source_system": "external_erp",
  "vehicle_type_source_id": "fleet.vehicle.model.category:3",
  "vehicle_type_model": "fleet.vehicle.model.category",
  "plate": "ABC123",
  "vehicle_description": "Camion especial",
  "hub_source_id": "stock.warehouse:1",
  "driver_source_id": "hr.employee:401",
  "extra_weight": 250,
  "extra_volume": 2,
  "extra_length": 0,
  "categories": ["PVC", "GAM"],
  "is_enabled": true
}

Response

{
  "ok": true,
  "code": "SYNC_OK",
  "message": "Sync processed successfully.",
  "data": [
    {
      "vehicle_id": 12
    }
  ],
  "meta": {
    "route": "/transportes/sync/vehicles",
    "method": "PostVehicleSync",
    "operation": "upsert",
    "upsert_action": "updated",
    "timestamp": "2026-04-07T12:00:00.000Z"
  }
}

Reglas de compatibilidad vehículo ↔ producto

Definen qué puede o no puede cargar un vehículo (o un tipo de vehículo). Se usan al armar la guía: un producto con una regla deny no sube a ese camión.

POST /transportes/sync/vehicle-compatibility-rules
Authorization: Bearer YOUR_SYNC_TOKEN_HERE
Content-Type: application/json

{
  "source_system": "exactus",
  "scope_type": "vehicle_type",
  "vehicle_type_source_id": "TIPO-FURGON",
  "rule_mode": "deny",
  "target_type": "category",
  "category": "INFLAMABLES",
  "is_active": true
}

Campo	Tipo	Requerido	Descripción
`source_system`	string (≤30)	sí	Sistema de origen de las referencias.
`scope_type`	`vehicle` \| `vehicle_type`	sí	A qué aplica la regla.
`vehicle_source_id`	string (≤128)	si `scope_type = vehicle`	Vehículo, por su `source_id`.
`vehicle_type_source_id`	string (≤128)	si `scope_type = vehicle_type`	Tipo de vehículo, por su `source_id`.
`rule_mode`	`allow` \| `deny`	sí	`deny` bloquea; `allow` habilita.
`target_type`	`product` \| `category`	sí	Sobre qué aplica.
`product_source_id`	string (≤128)	si `target_type = product`	Producto, por su `source_id`.
`category`	string (≤100)	si `target_type = category`	Categoría de producto.
`is_active`	boolean	no	Por defecto `true`. Mandarlo en `false` desactiva la regla sin borrarla.

El vehículo, el tipo de vehículo o el producto referenciados tienen que estar sincronizados antes: si no existen, la respuesta es SYNC_MISSING_DEPENDENCIES.

Proveedores Choferes y Licencias