PARCIAL Verificado contra producción · wb-services v3.53.0 · 24 ago 2026
Lealtad

Puntos y Ledger

El saldo de puntos de un cliente es la suma de un ledger de solo-anexado. Nada edita el saldo directamente. El sistema escribe un asiento, y el saldo se actualiza desde ese asiento.

Pedido o stafforigina la acción
→
Asiento en el ledgerganado · ajuste · quema · reversa
→
Saldo actualizadomáx(0, antes ± monto)
→
Billetera + eventorefresco · CUSTOMER_CARD_UPDATED

Solo se anexa. Nunca se edita ni se borra un asiento.

PARCIAL — Ajuste manual y Reversa están trazados y verificados. Ganar (desde pedidos), canje y expiración están sin trazar.

Preguntas frecuentes

¿Ajustar puntos le avisa al cliente?
No. La billetera actualiza el saldo en silencio. El sistema emite un evento interno para otros servicios. Ese evento no es un aviso al cliente. </>
Quemé puntos pero el tier del cliente no bajó, ¿es un error?
Funciona así por diseño. El tier usa los puntos de por vida acumulados. Una quema manual no baja ese acumulado. </>
¿Se puede deshacer un ajuste equivocado?
Sí. Revierte ese asiento. La reversa escribe un asiento opuesto. No borra el original: el ledger es solo-anexado. </>
¿Por qué mi ajuste «no pasó» la segunda vez?
Sí pasó, la primera vez. El sistema descarta un envío repetido idéntico. Así no aplica el ajuste dos veces. </>

Bueno saber

⚠️ Los ajustes manuales no registran quién los hizo. El asiento guarda el tipo de actor. Deja el usuario en nulo. Hoy nadie puede auditar qué persona ajustó los puntos.
Hallazgo · candidato a ticket </>
Las quemas nunca bajan el total de por vida ni el tier. Es intencional. También es una sorpresa común en soporte.

Comportamientos

Ajuste manual POST /v2/ledger/adjust

Un miembro del staff agrega o quita puntos a mano. El motivo es obligatorio. Todo ajuste queda registrado en el ledger.

El modal muestra el comportamiento: **Agregar / Quitar** es el signo del asiento, **Motivo** es obligatorio (0/500), y **Saldo actual → Saldo nuevo** es el tope en cero.
El modal muestra el comportamiento: Agregar / Quitar es el signo del asiento, Motivo es obligatorio (0/500), y Saldo actual → Saldo nuevo es el tope en cero.
  • Monto con signo → tipo de asiento. Positivo escribe MANUAL_ADD, negativo MANUAL_BURN. Cero se rechaza. </>
  • Saldo = máx(0, antes ± monto). Un «agregar» también sube el acumulado de por vida; una «quema» no lo baja. </>
  • Reglas. El motivo es obligatorio (≤500 caracteres). Una quema no puede bajar del saldo. La tarjeta debe ser del negocio y estar activa. El sistema descarta envíos repetidos idénticos. </>
  • Efectos. Recalcula el tier solo al agregar. Refresca la billetera. No avisa al cliente. Emite el evento interno CUSTOMER_CARD_UPDATED. </>

Acceso: cualquier usuario de negocio (dueño o secundario) con el sistema de tarjetas. Sin control por rol de staff.

Reversa POST /v2/ledger/entries/:uuid/reverse

Deshace un asiento concreto. Escribe un asiento opuesto y enlaza los dos. Ese enlace es la «cadena de reversa». Un ajuste crea un asiento nuevo; una reversa apunta a uno pasado.

  • Dirección. Revertir un asiento de suma resta; revertir una quema o canje devuelve. Se rechaza si dejaría el saldo negativo. </>
  • Cadena de reversa. Escribe un asiento REVERSAL ligado al original, y marca el original como revertido. Se puede seguir la cadena. </>
  • Límites. No se puede revertir un asiento ya revertido ni un asiento de reversa. </>
Mapa de código — para ingeniería