FleetAssociation

Vincula una Fleet con un asociado (associated: una Company o una Branch) para prestar un Service concreto, de un ServiceType dado, usando un ServiceCharge para el cálculo base de las tarifas de envío. El manager es el dueño de la flota (quien la administra); el associated es quien recibe el servicio. in_order fija la prioridad entre las asociaciones de un mismo asociado (menor primero).

Comisión (fee_flat_e2 + fee_prc + fee_target)

La tarifa de la asociación es la comisión que cobra el dueño de la flota por prestar el servicio a ese asociado. fee_prc es una fracción (0–1) y fee_flat_e2 un monto fijo en céntimos; se aplican sobre el monto que indica fee_target:

fee_target Sobre qué monto se calcula la comisión
base Solo la tarifa base de envío.
base_add La tarifa base más las tarifas adicionales (p. ej. recargo nocturno).
provider El monto que cobra el repartidor.
profit El monto que no cobra el repartidor (margen).

Ejemplo: envío base 3,00 + recargo nocturno 1,00 → base = 300, base_add = 400. Si el repartidor cobra el 90 % del envío, provider = 360 y profit = 40 (todo en céntimos). El sufijo _add en fee_target indica además que la comisión se suma a los tramos de tarifa.

Estado

  • is_enabled lo controla el associated con set-enabled / set-disabled.
  • No se puede eliminar si ya tiene órdenes vinculadas.

Opciones (options)

Bitmask oculto: is_admin_managed (la administra un admin de la plataforma), is_payment_received_for_branches (el pago lo recibe la company por sus branches), is_payouts_enabled (se generan payouts a la flota).

Notas y gotchas

  • manager_* y associated_* están en $hidden.
  • service_type se deriva del service y debe coincidir con el service_type del service_charge; si no, la creación/edición falla con ES040.

Estructura de Datos

Atributo Tipo Descripción
id int
is_enabled bool Si la asociación está activa (la controla el asociado)
in_order int Prioridad entre asociaciones del mismo asociado (menor primero)
fee_flat_e2 int Comisión fija del dueño de la flota, en céntimos (× 100)
fee_prc string Comisión porcentual del dueño de la flota (fracción 0–1)
fleet_id int {@link Fleet} que presta el servicio
service_id int {@link Service} prestado
service_charge_id int\|null {@link ServiceCharge} usado para el cálculo base de tarifas
service_type int Código de {@link ServiceType}; se deriva del service
manager_type string Tipo del administrador de la asociación (dueño de la flota); oculto
manager_id int Id del administrador de la asociación; oculto
associated_type string Tipo del asociado que recibe el servicio (Company o Branch); oculto
associated_id int Id del asociado; oculto
created_at datetime\|null
updated_at datetime\|null
fee_target string Monto sobre el que se aplica la comisión: base, base_add, provider o profit
options int Bitmask de opciones (oculto; ver "Opciones")
is_admin_managed bool BitMask (({@link self::options} & 0x1) !== 0)
is_payment_received_for_branches bool BitMask (({@link self::options} & 0x2) !== 0)
is_payouts_enabled bool BitMask (({@link self::options} & 0x4) !== 0)
allLogs ApiLog>
associated Model\|Eloquent Asociado que recibe el servicio (Company o Branch)
fleet Fleet {@link Fleet} que presta el servicio
logs ApiLog>
manager Model\|Eloquent Administrador de la asociación (dueño de la flota)
service Service {@link Service} prestado
serviceCharge ServiceCharge\|null {@link ServiceCharge} para el cálculo base de tarifas
serviceType ServiceType {@link ServiceType} del servicio 
{
    "id": 1,
    "is_enabled": true,
    "in_order": 1,
    "fee_flat_e2": 0,
    "fee_prc": "0.0000",
    "fleet_id": 1,
    "service_id": 1,
    "service_charge_id": 1,
    "service_type": 1,
    "created_at": "2023-07-07 13:36:35",
    "updated_at": "2023-07-07 13:36:35",
    "fee_target": "base",
    "is_admin_managed": false,
    "is_payment_received_for_branches": false,
    "is_payouts_enabled": true
}

Endpoints

Listar FleetAssociation

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

Listar asociaciones de flota

Listado paginado global de FleetAssociation (uso administrativo).

Método URI Cabeceras
GET /fleet-associations Authorization

Mostrar FleetAssociation

{info} Soporta: Carga dinámica

Mostrar asociación de flota

Devuelve la FleetAssociation por su id.

Método URI Cabeceras
GET /fleet-associations/{fleetAssociationId} Authorization

Actualizar FleetAssociation

Actualizar asociación de flota

Modifica el Service y el ServiceCharge vinculados, las tarifas (fee_flat_e2, fee_prc), in_order y las opciones. Si se cambia el servicio, el service_type se re-deriva de él y debe seguir coincidiendo con el del service charge.

Método URI Cabeceras
PATCH /fleet-associations/{fleetAssociationId} Authorization 
{
    "service_id": "required|integer|exists:services,id",
    "service_charge_id": "required|integer|exists:service_charges,id",
    "in_order": "integer|min:0|max:1000000",
    "fee_flat_e2": "integer|min:0",
    "fee_prc": "numeric|between:0.00,1.00",
    "is_admin_managed": "nullable|boolean",
    "is_payment_received_for_branches": "nullable|boolean",
    "is_payouts_enabled": "nullable|boolean"
}

Errores de negocio

Código HTTP Cuándo ocurre
ES040 400 El tipo de servicio del service y el del service_charge no coinciden.

Eliminar FleetAssociation

Eliminar asociación de flota

Elimina la FleetAssociation. No se permite si ya tiene órdenes vinculadas.

Método URI Cabeceras
DELETE /fleet-associations/{fleetAssociationId} Authorization

Errores de negocio

Código HTTP Cuándo ocurre
ES043 400 La asociación ya tiene órdenes vinculadas.

Acciones de FleetAssociation

Listar asociaciones de flota de una compañía

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

Devuelve las FleetAssociation donde la Company es el asociado. Con manager_mode las devuelve donde la company es el administrador (dueño de la flota).

Método URI Cabeceras
GET /companies/{companyId}/fleet-associations Authorization

Listar asociaciones de flota de una sucursal

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

Devuelve las FleetAssociation de la Branch y de su company. Con manager_mode alterna entre el rol de asociado y el de administrador (dueño de la flota).

Método URI Cabeceras
GET /branches/{branchId}/fleet-associations Authorization

Crear asociación de flota para una compañía

Vincula una Fleet con la Company para prestar un Service concreto, usando un ServiceCharge para el cálculo base de tarifas. in_order se asigna automáticamente al final. El service_type del servicio y el del service charge deben coincidir.

Método URI Cabeceras
POST /companies/{companyId}/fleet-associations Authorization 
{
    "fleet_id": "required|integer|exists:fleets,id",
    "service_id": "required|integer|exists:services,id",
    "service_charge_id": "required|integer|exists:service_charges,id",
    "in_order": "integer|min:0|max:1000000",
    "fee_flat_e2": "integer|min:0",
    "fee_prc": "numeric|between:0.00,1.00",
    "is_admin_managed": "nullable|boolean",
    "is_payment_received_for_branches": "nullable|boolean",
    "is_payouts_enabled": "nullable|boolean"
}

Errores de negocio

Código HTTP Cuándo ocurre
ES040 400 El tipo de servicio del service y el del service_charge no coinciden.

Crear asociación de flota para una sucursal

Igual que la versión para compañía, pero con la Branch como asociado.

Método URI Cabeceras
POST /branches/{branchId}/fleet-associations Authorization 
{
    "fleet_id": "required|integer|exists:fleets,id",
    "service_id": "required|integer|exists:services,id",
    "service_charge_id": "required|integer|exists:service_charges,id",
    "in_order": "integer|min:0|max:1000000",
    "fee_flat_e2": "integer|min:0",
    "fee_prc": "numeric|between:0.00,1.00",
    "is_admin_managed": "nullable|boolean",
    "is_payment_received_for_branches": "nullable|boolean",
    "is_payouts_enabled": "nullable|boolean"
}

Errores de negocio

Código HTTP Cuándo ocurre
ES040 400 El tipo de servicio del service y el del service_charge no coinciden.

Habilitar asociación de flota

Activa la FleetAssociation; la controla el asociado.

Método URI Cabeceras
POST /fleet-associations/{fleetAssociationId}/set-enabled Authorization

Errores de negocio

Código HTTP Cuándo ocurre
ES042 400 La asociación ya está habilitada.

Deshabilitar asociación de flota

Desactiva la FleetAssociation; la controla el asociado.

Método URI Cabeceras
POST /fleet-associations/{fleetAssociationId}/set-disabled Authorization

Errores de negocio

Código HTTP Cuándo ocurre
ES041 400 La asociación no está habilitada.

Relaciones