ServiceCharge

Regla con nombre para el cálculo de las tarifas de envío. Pertenece a un owner (una Company o una Branch) y aplica a un ServiceType concreto. Define los tramos de tarifa (deliveryFees) por geocerca (ServiceChargeGeofence) y es lo que usan las FleetAssociation para calcular el costo base del envío.

Tipos (type)

  • 1 — TYPE_LEGACY: la tarifa se calcula con los tramos configurados en la plataforma. Es el valor por defecto al crear.
  • 2 — TYPE_WEBHOOK: el cálculo se delega a un webhook saliente (p. ej. integración Ridery); sus parámetros van en config.

Cobertura

linkedGeofences / geofences son las geocercas donde aplica el cargo, cada una con sus tramos de tarifa. El pivote lleva is_enabled.

Notas y gotchas

  • No se puede cambiar service_type mientras el cargo esté en uso por alguna FleetAssociation: hay que desvincularlo primero (ES030).

Estructura de Datos

Atributo Tipo Descripción
id int
name string Nombre del cargo de servicio
type int Tipo de cálculo: 1 = tramos en plataforma (legacy), 2 = webhook
service_type int Código de {@link ServiceType} al que aplica el cargo
owner_type string Tipo del dueño polimórfico (Company o Branch)
owner_id int Id del dueño del cargo
created_at datetime\|null
updated_at datetime\|null
config array\|null Parámetros del cálculo (se usa cuando type = webhook)
allLogs ApiLog>
deliveryFees DeliveryFee> Tramos de tarifa de envío del cargo
fleetAssociations FleetAssociation> Asociaciones de flota que usan este cargo
geofences BranchGeofence> Geocercas donde aplica el cargo (pivote con is_enabled)
linkedGeofences ServiceChargeGeofence> Geocercas vinculadas con sus tramos de tarifa ({@link ServiceChargeGeofence})
logs ApiLog>
owner Model\|Eloquent Dueño del cargo (Company o Branch)
serviceType ServiceType {@link ServiceType} al que aplica el cargo 
{
    "id": 1,
    "name": "Delivery Fee",
    "type": 1,
    "service_type": 1,
    "owner_type": "App\Company",
    "owner_id": 1,
    "created_at": "2023-07-07 13:36:35",
    "updated_at": "2023-07-07 13:36:35",
    "config": null
}

Endpoints

Listar ServiceCharge

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

Listar cargos de servicio

Listado paginado global de ServiceCharge (uso administrativo).

Método URI Cabeceras
GET /service-charges N/A

Mostrar ServiceCharge

{info} Soporta: Carga dinámica

Mostrar cargo de servicio

Devuelve el ServiceCharge por su id. Endpoint público.

Método URI Cabeceras
GET /service-charges/{serviceChargeId} N/A

Actualizar ServiceCharge

Actualizar cargo de servicio

Modifica name, type y service_type del ServiceCharge.

Método URI Cabeceras
PATCH /service-charges/{serviceChargeId} Authorization 
{
    "name": "string|max:255",
    "type": "integer|min:1|max:2",
    "service_type": "integer|min:1|max:4"
}

Errores de negocio

Código HTTP Cuándo ocurre
ES030 400 No se puede cambiar service_type: el cargo está en uso por una FleetAssociation. Hay que desvincularlo primero.

Eliminar ServiceCharge

Eliminar cargo de servicio

Borra el ServiceCharge junto con sus vínculos de geocerca y tramos de tarifa.

Método URI Cabeceras
DELETE /service-charges/{serviceChargeId} Authorization

Acciones de ServiceCharge

Listar cargos de servicio de una compañía

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

ServiceCharge cuyo owner es la Company indicada.

Método URI Cabeceras
GET /companies/{companyId}/service-charges N/A

Listar cargos de servicio de una sucursal

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

ServiceCharge cuyo owner es la Branch indicada.

Método URI Cabeceras
GET /branches/{branchId}/service-charges N/A

Crear cargo de servicio para una compañía

Crea un ServiceCharge con la Company como owner, para el ServiceType indicado. Se crea como tipo legacy (type = 1).

Método URI Cabeceras
POST /companies/{companyId}/service-charges Authorization 
{
    "name": "required|string|max:255",
    "type": "integer|min:1|max:2",
    "service_type": "required|integer|min:1|max:4"
}

Crear cargo de servicio para una sucursal

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

Método URI Cabeceras
POST /branches/{branchId}/service-charges Authorization 
{
    "name": "required|string|max:255",
    "type": "integer|min:1|max:2",
    "service_type": "required|integer|min:1|max:4"
}

Relaciones