Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Eleazarguitar18/kantuta_pos_front/llms.txt

Use this file to discover all available pages before exploring further.

The Banking Agents module (Agentes) turns Kantuta POS into a banking correspondent terminal. Staff can accept cash deposits, pay out cash withdrawals, and process QR transfers on behalf of partner institutions such as BCP, Tigo Money, Banco Unión, SOLI, and others. Each transaction records the bank name, operation type, amounts, commissions, and a unique bank reference code for reconciliation. The module also integrates a WhatsApp gateway at /whatsapp — a QR-code-based session initialization page that connects the backend’s WhatsApp service so that automated notifications and the intelligent sales agent can be sent to customers over WhatsApp.
Agent transactions require a cash register with especialidad set to SOLO_AGENTES or MIXTA. A caja configured as SOLO_VENTAS cannot be used for banking agent operations. Ensure the correct register type is open before processing any agent transaction.

TransaccionAgente Entity

Banking agent transactions are modelled around a TransaccionAgente record. The fields below represent the full shape of the entity as used throughout the module:
// TransaccionAgente — entity shape (extends BaseEntityAudit)
// BaseEntityAudit provides: estado, id_user_create, id_user_update, created_at, updated_at
export interface TransaccionAgente extends BaseEntityAudit {
  id: number;
  banco: string;                           // Free-text bank name (e.g. "BCP", "Tigo Money")
  tipo_operacion: "DEPOSITO" | "RETIRO" | "TRANSFERENCIA_QR";
  monto: number;                           // Transaction principal in Bs.
  comision_cliente: number;                // Fee charged to the customer in Bs.
  comision_banco: number;                  // Fee paid back by the bank in Bs.
  nro_referencia: string;                  // Unique bank-issued reference code
  url_comprobante: string | null;          // Optional receipt/voucher URL
  fecha: string;                           // Transaction timestamp (ISO string)
  id_sesion_caja: number;
}

export interface CrearTransaccionAgenteRequest {
  banco: string;
  tipo_operacion: "DEPOSITO" | "RETIRO" | "TRANSFERENCIA_QR";
  monto: number;
  comision_cliente?: number;               // Optional fee charged to the customer in Bs.
  nro_referencia: string;
  id_sesion_caja: number;
  id_user_create: number;
}
nro_referencia is the unique bank reference code issued by the partner bank for each transaction (e.g., a receipt number or system-generated reference ID). It must be recorded accurately — it is the primary key used to reconcile agent transactions with the bank’s own records during daily settlement.

Operation Types

The customer hands over cash and the agent credits the equivalent amount to the customer’s bank account at the partner institution.Cash flow: Physical cash enters the caja drawer → an INGRESO of monto is recorded on the session.
FieldNotes
bancoPartner institution name (free text).
montoAmount deposited by the customer in Bs.
comision_clienteService fee charged to the customer in Bs.
comision_bancoCommission received from the bank in Bs.
nro_referenciaBank-issued receipt or transaction reference.

Caja Specialization Requirement

Caja typeCan process agent transactions?
SOLO_VENTAS❌ No
SOLO_AGENTES✅ Yes
MIXTA✅ Yes
Before opening an agent shift, confirm the register’s especialidad in the Caja list at /cajas. If only SOLO_VENTAS cajas are available, contact an Administrador to create or reconfigure a register.

Soft-Delete Behavior

Deleting an agent transaction (DELETE /agentes/:id) does not remove the record from the database. Instead, the backend sets estado to false. The record remains visible in audit logs and reports but is excluded from active balance computations. This preserves the full transaction history for regulatory compliance and bank reconciliation.

WhatsApp Gateway Page

The /whatsapp route (served by WhatsAppMain) connects Kantuta POS to a WhatsApp Business session on the backend. On page load, it calls GET /whatsapp/connect to check the current session state:
ResponseWhat the UI shows
qrBase64 presentA scannable QR code image with “Esperando escaneo…” pulse label.
Session already connectedA green checkmark and the connection confirmation message.
Backend unreachableAn error alert: “Error de conexión al servidor de WhatsApp.”
Click Recargar Estado / QR at any time to re-check the connection or refresh an expired QR code.
Once the WhatsApp session is active, the backend can send automated sale confirmations, low-stock alerts, and agent transaction receipts directly to customer phone numbers — no additional configuration is needed in the frontend.

URL Routes

PagePath
WhatsApp gateway / agent panel/whatsapp

Build docs developers (and LLMs) love