Fleet

Una flota es un grupo de repartidores/vehículos que pertenece a un dueño (owner: una Company, una Branch o un ServiceSupplier) y se administra a través de un ServiceSupplier. Define la capacidad del vehículo, el alcance del servicio y las preferencias de asignación. Es la unidad del motor de asignación de repartidores y sustituye al pool global de proveedores; se conecta a companies o branches concretos mediante FleetAssociation.

Ciclo de vida

Se crea deshabilitada (is_enabled = false).
set-enabled la activa, pero solo si ya tiene al menos un FleetMember.
set-disabled la desactiva.
Al eliminarla se borra de forma definitiva (no hay soft delete).

Alcance

service_radius_m — radio de cobertura, en metros, alrededor del punto de origen.
service_distance_m — longitud máxima de la ruta de servicio, en metros.
Las áreas se acotan además con geocercas vinculadas (geofences, vía LinkedGeofence).

Preferencias (`preferences`)

Bitmask oculto. Agrupa: el límite de entregas simultáneas por repartidor (pref_max_simultaneous_deliveries), el motor de auto-asignación y el acceso a los pools (pref_enable_auto_assignment_engine, pref_enable_provider_pool_access, pref_enable_client_pool_access), las confirmaciones exigidas antes de asignar (pref_require_provider_confirmation_on_client_assignment, pref_require_client_confirmation_on_provider_assignment, pref_require_provider_confirmation_on_admin_assignment, pref_enable_admin_manual_selection_after_confirmations, pref_allow_provider_order_forfeit, pref_allow_multi_delivery_by_self) y las capacidades del repartidor/vehículo (pref_is_pet_allowed, pref_is_smoker, pref_has_cold_storage, pref_can_transport_liquids, pref_has_fragile_handling_experience, pref_has_large_backpack, pref_has_secure_lockbox, pref_accepts_cash_on_delivery).

Configuración (`config`)

Clave	Descripción
`created_action`	Código de webhook saliente que se dispara al crear la orden (integración API-partner).
`fees_action`	Código de webhook saliente para calcular las tarifas de envío; si no está, se usa el ServiceCharge de la asociación.
`delivery_action`	Código de webhook saliente para crear el envío en el partner.
`provider_id`	Provider "puente" al que se asignan las órdenes gestionadas por API-partner.
`payment_methods`	Lista de FleetPaymentMethod (cobros post-entrega tipo POS): `code`, `name`, `enabled`, `currency_iso`, `tax_flat_e2` (× 100), `tax_prc` (fracción 0–1), `binding_attribute`.
`proof_of_delivery`	Configuración de prueba de entrega por estado (`collected` / `delivered`) con los ítems `code`, `form`, `picture`, `signature`; o `groups` con ítems detallados (`type`, `is_enabled`, `is_optional`).

Notas y gotchas

owner_type / owner_id se copian del ServiceSupplier al crear la flota.
preferences está en $hidden; se expone solo a través de los accesores pref_*.
config.proof_of_delivery se normaliza a un PODConfig al leer el modelo.
statistics lo recalcula de forma asíncrona UpdateFleetStatisticsJob.

Estructura de Datos

Atributo	Tipo	Descripción
`id`	`int`
`name`	`string`	Nombre de la flota
`is_enabled`	`bool`	Si la flota está activa para el motor de asignación
`passenger_capacity`	`int`	Capacidad de pasajeros del vehículo
`carry_capacity_kg`	`int`	Capacidad de carga del vehículo, en kg
`service_radius_m`	`int`	Radio de cobertura en metros alrededor del origen
`service_distance_m`	`int`	Longitud máxima de la ruta de servicio, en metros
`preferences`	`int`	Bitmask de preferencias de asignación (oculto; ver "Preferencias")
`service_supplier_id`	`int`	{@link ServiceSupplier} que administra la flota
`owner_type`	`string`	Tipo del dueño polimórfico (Company, Branch o ServiceSupplier)
`owner_id`	`int`	Id del dueño; se hereda del service supplier
`created_at`	`datetime\\|null`
`updated_at`	`datetime\\|null`
`config`	`array\\|null`	Configuración de la flota: webhooks, provider puente, métodos de pago y POD (ver "Configuración")
`statistics`	`array\\|null`	Estadísticas agregadas de la flota (recalculadas por `UpdateFleetStatisticsJob`)
`pref_max_simultaneous_deliveries`	`int`	BitMask ({@link self::preferences} & 0xf)
`pref_allow_multi_delivery_by_self`	`bool`	BitMask (({@link self::preferences} & 0x10) !== 0)
`pref_enable_auto_assignment_engine`	`bool`	BitMask (({@link self::preferences} & 0x20) !== 0)
`pref_enable_provider_pool_access`	`bool`	BitMask (({@link self::preferences} & 0x40) !== 0)
`pref_enable_client_pool_access`	`bool`	BitMask (({@link self::preferences} & 0x80) !== 0)
`pref_require_provider_confirmation_on_client_assignment`	`bool`	BitMask (({@link self::preferences} & 0x100) !== 0)
`pref_require_client_confirmation_on_provider_assignment`	`bool`	BitMask (({@link self::preferences} & 0x200) !== 0)
`pref_require_provider_confirmation_on_admin_assignment`	`bool`	BitMask (({@link self::preferences} & 0x400) !== 0)
`pref_enable_admin_manual_selection_after_confirmations`	`bool`	BitMask (({@link self::preferences} & 0x800) !== 0)
`pref_allow_provider_order_forfeit`	`bool`	BitMask (({@link self::preferences} & 0x1000) !== 0)
`pref_is_pet_allowed`	`bool`	BitMask (({@link self::preferences} & 0x200000) !== 0)
`pref_is_smoker`	`bool`	BitMask (({@link self::preferences} & 0x400000) !== 0)
`pref_has_cold_storage`	`bool`	BitMask (({@link self::preferences} & 0x800000) !== 0)
`pref_can_transport_liquids`	`bool`	BitMask (({@link self::preferences} & 0x1000000) !== 0)
`pref_has_fragile_handling_experience`	`bool`	BitMask (({@link self::preferences} & 0x2000000) !== 0)
`pref_has_large_backpack`	`bool`	BitMask (({@link self::preferences} & 0x4000000) !== 0)
`pref_has_secure_lockbox`	`bool`	BitMask (({@link self::preferences} & 0x8000000) !== 0)
`pref_accepts_cash_on_delivery`	`bool`	BitMask (({@link self::preferences} & 0x10000000) !== 0)
`allLogs`	`ApiLog>`
`fleetAssociations`	`FleetAssociation>`	Vínculos de la flota con companies/branches ({@link FleetAssociation})
`fleetMembers`	`FleetMember>`	Repartidores que integran la flota ({@link FleetMember})
`geofences`	`BranchGeofence>`	Geocercas de cobertura vinculadas (vía {@link LinkedGeofence})
`linkedGeofences`	`LinkedGeofence>`	Registros de geocerca vinculada de la flota
`logs`	`ApiLog>`
`owner`	`Model\\|Eloquent`	Dueño de la flota (Company, Branch o ServiceSupplier)
`serviceSupplier`	`ServiceSupplier`	{@link ServiceSupplier} que administra la flota

{
    "id": 1,
    "name": "General (Autogenerated)",
    "is_enabled": true,
    "passenger_capacity": 0,
    "carry_capacity_kg": 1000,
    "service_radius_m": 5000,
    "service_distance_m": 25000,
    "service_supplier_id": 1,
    "owner_type": "App\Company",
    "owner_id": 1,
    "created_at": "2023-07-07 13:36:35",
    "updated_at": "2026-03-16 15:40:11",
    "config": null,
    "statistics": {
        "total_orders": 0,
        "last_30_days": {
            "total_orders": 0,
            "active_drivers": 0,
            "avg_distance_m": 0,
            "avg_expected_time_s": 0,
            "avg_actual_delivery_time_s": 0,
            "avg_delay_s": 0,
            "on_time_rate_percent": 0,
            "delay_distribution": {
                "under_5min": 0,
                "between_5_15min": 0,
                "between_15_30min": 0,
                "over_30min": 0
            }
        },
        "updated_at": "2026-03-16 15:40:11"
    },
    "pref_max_simultaneous_deliveries": 0,
    "pref_allow_multi_delivery_by_self": false,
    "pref_enable_auto_assignment_engine": false,
    "pref_enable_provider_pool_access": false,
    "pref_enable_client_pool_access": false,
    "pref_require_provider_confirmation_on_client_assignment": false,
    "pref_require_client_confirmation_on_provider_assignment": false,
    "pref_require_provider_confirmation_on_admin_assignment": false,
    "pref_enable_admin_manual_selection_after_confirmations": false,
    "pref_allow_provider_order_forfeit": false,
    "pref_is_pet_allowed": false,
    "pref_is_smoker": false,
    "pref_has_cold_storage": false,
    "pref_can_transport_liquids": false,
    "pref_has_fragile_handling_experience": false,
    "pref_has_large_backpack": false,
    "pref_has_secure_lockbox": false,
    "pref_accepts_cash_on_delivery": false,
    "pref_delivery_settings": 0
}

Endpoints

Insertar Fleet

Insertar Fleet de ServiceSupplier

Crear flota

Crea una Fleet bajo un ServiceSupplier. Nace deshabilitada (is_enabled = false) y hereda el owner (Company, Branch o ServiceSupplier) del service supplier. Acepta capacidad (pasajeros, carga), alcance (service_radius_m, service_distance_m), preferencias de asignación (pref_*) y config (webhooks, POD).

Método	URI	Cabeceras
POST	`/service-suppliers/{serviceSupplierId}/fleets`	Authorization

{
    "name": "required|string|max:255",
    "passenger_capacity": "integer|min:0|max:255",
    "carry_capacity_kg": "integer|min:0|max:4096",
    "service_radius_m": "integer|min:0|max:100000",
    "service_distance_m": "integer|min:0|max:100000",
    "config": {
        "created_action": "nullable|string|in:goods_import,order_status_report,payments_validation_zelle,payments_report_stripe,fleet_prices_ridery,fleet_prices_partner,shipment_creation_ridery,shipment_creation_partner,order_creation_ridery,order_creation_partner,promos_sync,discounts_refresh",
        "fees_action": "nullable|string|in:goods_import,order_status_report,payments_validation_zelle,payments_report_stripe,fleet_prices_ridery,fleet_prices_partner,shipment_creation_ridery,shipment_creation_partner,order_creation_ridery,order_creation_partner,promos_sync,discounts_refresh",
        "delivery_action": "nullable|string|in:goods_import,order_status_report,payments_validation_zelle,payments_report_stripe,fleet_prices_ridery,fleet_prices_partner,shipment_creation_ridery,shipment_creation_partner,order_creation_ridery,order_creation_partner,promos_sync,discounts_refresh",
        "provider_id": "nullable|integer|exists:providers,id",
        "proof_of_delivery": {
            "collected": {
                "code": "boolean",
                "form": "boolean",
                "picture": "boolean",
                "signature": "boolean"
            },
            "delivered": {
                "code": "boolean",
                "form": "boolean",
                "picture": "boolean",
                "signature": "boolean"
            }
        }
    },
    "pref_max_simultaneous_deliveries": "nullable|integer|min:0|max:15",
    "pref_allow_multi_delivery_by_self": "nullable|boolean",
    "pref_enable_auto_assignment_engine": "nullable|boolean",
    "pref_enable_provider_pool_access": "nullable|boolean",
    "pref_enable_client_pool_access": "nullable|boolean",
    "pref_require_provider_confirmation_on_client_assignment": "nullable|boolean",
    "pref_require_client_confirmation_on_provider_assignment": "nullable|boolean",
    "pref_require_provider_confirmation_on_admin_assignment": "nullable|boolean",
    "pref_enable_admin_manual_selection_after_confirmations": "nullable|boolean",
    "pref_allow_provider_order_forfeit": "nullable|boolean",
    "pref_is_pet_allowed": "nullable|boolean",
    "pref_is_smoker": "nullable|boolean",
    "pref_has_cold_storage": "nullable|boolean",
    "pref_can_transport_liquids": "nullable|boolean",
    "pref_has_fragile_handling_experience": "nullable|boolean",
    "pref_has_large_backpack": "nullable|boolean",
    "pref_has_secure_lockbox": "nullable|boolean",
    "pref_accepts_cash_on_delivery": "nullable|boolean",
    "pref_delivery_settings": "nullable|integer|min:0|max:32767"
}

Mostrar Fleet

{info} Soporta: Carga dinámica

Mostrar flota

Devuelve la Fleet por su id.

Método	URI	Cabeceras
GET	`/fleets/{fleetId}`	Authorization

Actualizar Fleet

Actualizar flota

Modifica nombre, capacidad, alcance, preferencias (pref_*) y config de la Fleet. El config se fusiona con el existente (merge superficial de primer nivel), no lo reemplaza.

Método	URI	Cabeceras
PATCH	`/fleets/{fleetId}`	Authorization

{
    "name": "string|max:255",
    "passenger_capacity": "integer|min:0|max:255",
    "carry_capacity_kg": "integer|min:0|max:4096",
    "service_radius_m": "integer|min:0|max:100000",
    "service_distance_m": "integer|min:0|max:100000",
    "config": {
        "created_action": "nullable|string|in:goods_import,order_status_report,payments_validation_zelle,payments_report_stripe,fleet_prices_ridery,fleet_prices_partner,shipment_creation_ridery,shipment_creation_partner,order_creation_ridery,order_creation_partner,promos_sync,discounts_refresh",
        "fees_action": "nullable|string|in:goods_import,order_status_report,payments_validation_zelle,payments_report_stripe,fleet_prices_ridery,fleet_prices_partner,shipment_creation_ridery,shipment_creation_partner,order_creation_ridery,order_creation_partner,promos_sync,discounts_refresh",
        "delivery_action": "nullable|string|in:goods_import,order_status_report,payments_validation_zelle,payments_report_stripe,fleet_prices_ridery,fleet_prices_partner,shipment_creation_ridery,shipment_creation_partner,order_creation_ridery,order_creation_partner,promos_sync,discounts_refresh",
        "provider_id": "nullable|integer|exists:providers,id",
        "proof_of_delivery": {
            "collected": {
                "code": "boolean",
                "form": "boolean",
                "picture": "boolean",
                "signature": "boolean"
            },
            "delivered": {
                "code": "boolean",
                "form": "boolean",
                "picture": "boolean",
                "signature": "boolean"
            },
            "groups": [
                {
                    "status": "required|string|in:collected,delivered",
                    "required_items_count": "nullable|integer|min:0",
                    "items": [
                        {
                            "type": "required|string|in:form,code,picture,signature",
                            "is_enabled": "nullable|boolean",
                            "is_optional": "nullable|boolean"
                        }
                    ]
                }
            ]
        }
    },
    "pref_max_simultaneous_deliveries": "nullable|integer|min:0|max:15",
    "pref_allow_multi_delivery_by_self": "nullable|boolean",
    "pref_enable_auto_assignment_engine": "nullable|boolean",
    "pref_enable_provider_pool_access": "nullable|boolean",
    "pref_enable_client_pool_access": "nullable|boolean",
    "pref_require_provider_confirmation_on_client_assignment": "nullable|boolean",
    "pref_require_client_confirmation_on_provider_assignment": "nullable|boolean",
    "pref_require_provider_confirmation_on_admin_assignment": "nullable|boolean",
    "pref_enable_admin_manual_selection_after_confirmations": "nullable|boolean",
    "pref_allow_provider_order_forfeit": "nullable|boolean",
    "pref_is_pet_allowed": "nullable|boolean",
    "pref_is_smoker": "nullable|boolean",
    "pref_has_cold_storage": "nullable|boolean",
    "pref_can_transport_liquids": "nullable|boolean",
    "pref_has_fragile_handling_experience": "nullable|boolean",
    "pref_has_large_backpack": "nullable|boolean",
    "pref_has_secure_lockbox": "nullable|boolean",
    "pref_accepts_cash_on_delivery": "nullable|boolean",
    "pref_delivery_settings": "nullable|integer|min:0|max:32767"
}

Eliminar Fleet

Eliminar flota

Borra la Fleet de forma definitiva (no hay soft delete).

Método	URI	Cabeceras
DELETE	`/fleets/{fleetId}`	Authorization

Acciones de Fleet

Listar flotas del proveedor de servicio

{info} Soporta: Paginación Filters Carga dinámica

Listado paginado de las Fleet que administra un ServiceSupplier.

Método	URI	Cabeceras
GET	`/service-suppliers/{serviceSupplierId}/fleets`	Authorization

Habilitar flota

Activa la Fleet para el motor de asignación. Requiere que la flota tenga al menos un FleetMember.

Método	URI	Cabeceras
POST	`/fleets/{fleetId}/set-enabled`	Authorization

Errores de negocio

Código	HTTP	Cuándo ocurre
`ES021`	400	La flota ya está habilitada.
`ES022`	400	La flota no está lista: no tiene miembros.

Deshabilitar flota

Desactiva la Fleet: deja de participar en el motor de asignación.

Método	URI	Cabeceras
POST	`/fleets/{fleetId}/set-disabled`	Authorization

Errores de negocio

Código	HTTP	Cuándo ocurre
`ES020`	400	La flota no está habilitada.

Agregar método de pago a la flota

Añade un FleetPaymentMethod (cobro post-entrega tipo POS) al config.payment_methods de la Fleet, identificado por code. Acepta impuestos (tax_flat_e2 en céntimos, tax_prc como fracción 0–1) y un binding_attribute opcional.

Método	URI	Cabeceras
PUT	`/fleets/{fleetId}/payment-methods`	Authorization

{
    "code": "required|string|max:16",
    "name": "required|string|max:255|min:3",
    "enabled": "nullable|boolean",
    "currency_iso": "nullable|string|min:3|max:8",
    "tax_flat_e2": "nullable|integer|min:0",
    "tax_prc": "nullable|numeric|between:0.0000,1.0000",
    "binding_attribute": {
        "nullable": true,
        "string": true,
        "in": "providers:pos_serial"
    }
}

Actualizar método de pago de la flota

Modifica el FleetPaymentMethod de la Fleet identificado por code. Los campos no enviados conservan su valor actual.

Método	URI	Cabeceras
PATCH	`/fleets/{fleetId}/payment-methods`	Authorization

{
    "code": "required|string|max:16",
    "name": "nullable|string|max:255|min:3",
    "enabled": "nullable|boolean",
    "currency_iso": "nullable|string|min:3|max:8",
    "tax_flat_e2": "nullable|integer|min:0",
    "tax_prc": "nullable|numeric|between:0.0000,1.0000",
    "binding_attribute": {
        "nullable": true,
        "string": true,
        "in": "providers:pos_serial"
    }
}

Eliminar método de pago de la flota

Quita del config.payment_methods de la Fleet el método identificado por code. Si el code no existe, la operación no falla.

Método	URI	Cabeceras
DELETE	`/fleets/{fleetId}/payment-methods`	Authorization

{
    "code": "required|string|max:16"
}

Relaciones

allLogs HasMany ApiLog
fleetAssociations HasMany FleetAssociation
fleetMembers HasMany FleetMember
geofences HasMany BranchGeofence
linkedGeofences HasMany LinkedGeofence
logs HasMany ApiLog
owner BelongsTo Company
serviceSupplier BelongsTo ServiceSupplier

Administración

Métodos de Pago

Calificaciones

Fleet

Ciclo de vida

Alcance

Preferencias (preferences)

Configuración (config)

Notas y gotchas

Estructura de Datos

Endpoints

Insertar Fleet

Insertar Fleet de ServiceSupplier

Mostrar Fleet

Actualizar Fleet

Eliminar Fleet

Acciones de Fleet

Listar flotas del proveedor de servicio

Habilitar flota

Errores de negocio

Deshabilitar flota

Errores de negocio

Agregar método de pago a la flota

Actualizar método de pago de la flota

Eliminar método de pago de la flota

Relaciones

Preferencias (`preferences`)

Configuración (`config`)