BalanceMovement

Un asiento en el libro de saldo de un "dueño de balance" (owner: una Account —de clientes o repartidores—, una Branch, una Company o una ciudad City). Es la única fuente de verdad de los saldos: los recursos account-balances, branch-balances, client-balances y city-balances son rutas heredadas que operan sobre esta misma tabla filtrando por dueño.

Montos

Todos en céntimos (× 100). initial_balance_e2 y final_balance_e2 son el saldo del dueño antes y después del asiento; amount_e2 es el delta (positivo suma, negativo resta). number es el correlativo del asiento para ese dueño. currency_iso es la moneda del saldo.

Tipos (type)

giftcard (canje de gift card), recharge (recarga de saldo), withdrawal (retiro), change (vuelto de una compra), purchase (compra), reconciled (pago ya recibido), fee / payment (comisión), delivery (envío), discount, refund (devolución), transfer (transferencia entre dueños), adjustment (ajuste manual de un admin).

Vínculos

related es la entidad que originó el asiento (normalmente una Order); author es la cuenta que lo registró. is_deferred marca los asientos diferidos (aún no aplicados al saldo).

Notas y gotchas

  • owner_type / owner_id y related_type / related_id están en $hidden; la entidad relacionada se expone como related_model.
  • amount, final_balance, related_amount y related_final_balance son objetos Money derivados.

Estructura de Datos

Atributo Tipo Descripción
id int
number int Correlativo del asiento para su dueño de balance
initial_balance_e2 int Saldo del dueño antes del asiento, en céntimos (× 100)
amount_e2 int Delta del asiento, en céntimos (× 100); positivo suma, negativo resta
final_balance_e2 int Saldo del dueño después del asiento, en céntimos (× 100)
type string Tipo de movimiento (ver "Tipos")
description string Descripción del movimiento
is_deferred bool Si el asiento está diferido (aún no aplicado al saldo)
created_at datetime\|null
updated_at datetime\|null
owner_id int Id del dueño de balance (oculto)
owner_type string Tipo del dueño de balance: Account, Branch, Company o City (oculto)
author_id int\|null {@link Account} que registró el asiento
related_type string\|null Tipo de la entidad que originó el asiento (oculto)
related_id int\|null Id de la entidad que originó el asiento (oculto)
currency_iso string Moneda del saldo
admin_url string\|null URL del asiento en el panel de administración
allLogs ApiLog>
amount Money\|null Monto del asiento como objeto Money
author Account\|null {@link Account} que registró el asiento
final_balance Money\|null Saldo final del dueño como objeto Money
logs ApiLog>
order_number string\|null uid de la orden relacionada, si aplica
owner Model\|Eloquent Dueño de balance (Account, Branch, Company o City)
ownerAccount Account\|null {@link Account} dueña, si el dueño es una cuenta
related Model\|Eloquent Entidad que originó el asiento (normalmente una {@link Order})
related_amount Money\|null Monto del asiento espejo del otro dueño (en transferencias)
related_final_balance Money\|null Saldo final del otro dueño (en transferencias)
related_model string\|null Identificador legible de la entidad relacionada 
{
    "id": 1,
    "number": 1,
    "initial_balance_e2": 0,
    "amount_e2": 10000,
    "final_balance_e2": 10000,
    "type": "adjustment",
    "description": "test",
    "is_deferred": false,
    "created_at": "2021-03-05 14:49:48",
    "updated_at": "2021-03-05 14:49:48",
    "author_id": 1,
    "currency_iso": "USD",
    "related_model": null,
    "amount": {
        "amount_e2": 10000,
        "currency_iso": "USD",
        "formatted_iso": "USD 100.00",
        "formatted": "100.00$"
    },
    "related_amount": {
        "amount_e2": 10000,
        "currency_iso": "USD",
        "formatted_iso": "USD 100.00",
        "formatted": "100.00$"
    },
    "final_balance": {
        "amount_e2": 10000,
        "currency_iso": "USD",
        "formatted_iso": "USD 100.00",
        "formatted": "100.00$"
    },
    "related_final_balance": {
        "amount_e2": 10000,
        "currency_iso": "USD",
        "formatted_iso": "USD 100.00",
        "formatted": "100.00$"
    }
}

Endpoints

Listar BalanceMovement

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

Listar movimientos de saldo

Devuelve los BalanceMovement del dueño de balance indicado por type + key (account / branch / company / city y su id). Con report devuelve un resumen agregado en vez del listado.

Método URI Cabeceras
GET /companies/{companyId}/balance-movements Authorization 
{
    "type": "required|string|in:account,client,provider,branch,company,city",
    "key": "required|integer|min:1",
    "target_type": "string|regex:/^\w+(,\w+)*$/",
    "report": "integer"
}

Mostrar BalanceMovement

Mostrar saldo actual

Devuelve el último BalanceMovement del dueño de balance indicado por type + key, es decir su saldo actual.

Método URI Cabeceras
GET /companies/{companyId}/balance-movements/current Authorization 
{
    "type": "required|string|in:account,client,provider,branch,company,city",
    "key": "required|integer|min:1",
    "target_type": "string|regex:/^\w+(,\w+)*$/",
    "report": "integer"
}

Acciones de BalanceMovement

Ajustar saldo

Registra un BalanceMovement de tipo adjustment (ajuste manual, con motivo) sobre el dueño de balance indicado por type + key.

Método URI Cabeceras
POST /companies/{companyId}/balance-movements/adjust Authorization 
{
    "type": "required|string|in:account,client,provider,branch,company,city",
    "key": "required|integer|min:1",
    "amount_e2": "required|int",
    "description": "string|max:128"
}

Listar movimientos de saldo de una entidad

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

BalanceMovement originados por la entidad indicada (p. ej. una Order). Para órdenes solo devuelve los asientos cuyo dueño es una Account.

Método URI Cabeceras
GET /companies/{companyId}/orders/{orderId}/balance-movements Authorization

Registrar vuelto de una orden

Registra el vuelto (change) entregado al cliente en una Order. Opcionalmente carga el vuelto (o retira la comisión) al shopper o al repartidor con is_affecting_provider / remove_provider_fee.

Método URI Cabeceras
POST /companies/{companyId}/orders/{orderId}/balance-movements/give-change Authorization 
{
    "amount_e2": "required|int|min:1",
    "description": "nullable|string|max:128",
    "is_affecting_provider": "nullable|string|in:shopper,deliverer",
    "remove_provider_fee": "nullable|string|in:shopper,deliverer"
}

Errores de negocio

Código HTTP Cuándo ocurre
EF502 400 El monto debe ser positivo.
EF504 400 El vuelto total no puede superar el monto de la orden.

Transferir saldo

Mueve saldo entre dos dueños de balance (un asiento transfer en cada uno), normalmente a raíz de una orden.

Método URI Cabeceras
POST /companies/{companyId}/orders/{orderId}/balance-movements/transfer Authorization 
{
    "type": "required|string|in:account,client,provider,branch,company,city",
    "key": "required|integer|min:1",
    "amount_e2": "required|int",
    "target": "string",
    "target_type": "string|in:account,client,provider,branch,company,city,client_uuid,email",
    "description": "string|max:128"
}

Consultar deudas de una ciudad

Devuelve las deudas de wallet (wallet_debts) de la ciudad City indicada.

Método URI Cabeceras
GET /companies/{companyId}/cities/{cityId}/balance-movements/debt Authorization

Relaciones