BalanceModifier

Un saldo promocional con caducidad para un dueño de balance (owner, normalmente una Account). Se otorga initial_amount_e2 de saldo; active_amount_e2 es la parte aún sin usar. Al llegar active_until se revierte automáticamente el monto no consumido (un asiento BalanceMovement negativo).

Ciclo de vida

  • Se crea inactivo. Con active_since en el futuro, un job lo activa a esa hora; si no, se activa de inmediato.
  • is_active indica si está vigente.
  • expire() (o el job programado a active_until) lo cierra y revierte el remanente.
  • Mientras está activo solo se pueden editar active_until y description.

Configuración (config, oculto)

group_name (agrupa promociones), refs (ids de los BalanceMovement generados), related_to (Clase:id de la entidad asociada) e is_withdrawal_locked (si el saldo promocional no se puede retirar, solo gastar) — expuesto como is_withdrawal_locked.

Montos en céntimos (× 100).

Estructura de Datos

Atributo Tipo Descripción
id int
created_at datetime\|null
updated_at datetime\|null
company_id int {@link Company} dueña de la promoción
is_active bool Si la promoción está vigente
active_since datetime Momento en que empieza a estar vigente
active_until datetime\|null Momento en que caduca; al llegar se revierte el remanente
initial_amount_e2 int Saldo promocional otorgado, en céntimos (× 100)
active_amount_e2 int Saldo promocional aún sin usar, en céntimos (× 100)
description string Descripción de la promoción
config array Configuración interna de la promoción (oculto; ver "Configuración")
owner_type string Tipo del dueño de balance de la promoción (oculto)
owner_id int Id del dueño de balance de la promoción (oculto)
author_id int {@link Account} que creó la promoción
group_name string\|null Nombre del grupo de la promoción
is_withdrawal_locked bool Si el saldo promocional no se puede retirar (solo gastar)
refs array Ids de los {@link BalanceMovement} asociados a la promoción
related_to Model\|null Entidad asociada a la promoción (Clase:id)
allLogs ApiLog>
balance_movements Collection Asientos {@link BalanceMovement} generados por esta promoción
logs ApiLog>
owner EloquentModel\|Eloquent Dueño de balance de la promoción
related_model string\|null Identificador legible del dueño de balance 
{
    "id": 2,
    "created_at": "2025-05-29 20:33:19",
    "updated_at": "2025-06-05 13:58:57",
    "company_id": 116,
    "is_active": false,
    "active_since": "2025-05-29 20:33:19",
    "active_until": "2025-06-05 13:58:57",
    "initial_amount_e2": 1000,
    "active_amount_e2": 0,
    "description": "Premio Gordo",
    "owner_type": "App\Account",
    "owner_id": 753,
    "author_id": 175,
    "related_model": "accounts:753",
    "is_withdrawal_locked": true
}

Endpoints

Insertar BalanceModifier

Crear saldo promocional

Otorga un BalanceModifier (saldo promocional con caducidad) a la cuenta account_id. Se activa de inmediato o, si se envía active_since, en esa fecha (vía job).

Método URI Cabeceras
POST /companies/{companyId}/balance-modifiers Authorization 
{
    "account_id": "required|integer|exists:accounts,id",
    "active_since": "nullable|date",
    "active_until": "nullable|date",
    "initial_amount_e2": "required|integer|min:1",
    "description": "required|string|max:128",
    "is_withdrawal_locked": "nullable|boolean"
}

Listar BalanceModifier

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

Listar saldos promocionales

Devuelve los BalanceModifier (saldos promocionales con caducidad) de la company.

Método URI Cabeceras
GET /companies/{companyId}/balance-modifiers Authorization

Mostrar BalanceModifier

{info} Soporta: Carga dinámica

Mostrar saldo promocional

Devuelve el BalanceModifier por su id.

Método URI Cabeceras
GET /companies/{companyId}/balance-modifiers/{balanceModifierId} Authorization

Actualizar BalanceModifier

Actualizar saldo promocional

Modifica el BalanceModifier. Si ya está activo, solo se pueden cambiar active_until y description. Cambiar active_since reprograma la activación; cambiar active_until reprograma la caducidad.

Método URI Cabeceras
PATCH /companies/{companyId}/balance-modifiers/{balanceModifierId} Authorization 
{
    "active_since": "nullable|date",
    "active_until": "nullable|date",
    "initial_amount_e2": "required|integer|min:1",
    "description": "required|string|max:128",
    "is_withdrawal_locked": "nullable|boolean"
}

Relaciones