Skip to main content

Documentation Index

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

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

The Recargas API manages mobile carrier top-ups (recargas) sold through the POS terminal. The store maintains a pre-funded balance with each mobile operator (Tigo, Entel, Viva), and when a client purchases a top-up, the corresponding amount is deducted from that operator’s balance. To replenish an operator’s balance, administrators record a balance injection (inyección) — also debited from a cash register session. This creates a full, trackable loop from cash on hand to operator credit to client top-up delivery.
All endpoints require a valid Authorization: Bearer <access_token> header.

​
Process a Client Top-Up

POST /recargas/cliente
Processes a mobile top-up for a customer. The requested monto is deducted from the store’s current balance for the specified operadora. The transaction is linked to an active cash register session (id_caja_sesion), recording the incoming cash from the customer.
If the store’s saldo_actual for the given operadora is insufficient to cover the requested monto, the request will be rejected. Inject more balance via POST /recargas/inyeccion before retrying.

​
Request Body

​
operadora
string
required
Mobile carrier for the top-up. One of: "Tigo", "Entel", "Viva".
​
numero_cliente
string
required
The client’s mobile phone number to be topped up (e.g., "78945612").
​
monto
number
required
Top-up amount. Minimum 0.1.
​
id_caja_sesion
number
required
ID of the active cash register session where this sale is being processed.
curl -X POST https://api.example.com/recargas/cliente \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "operadora": "Tigo",
    "numero_cliente": "78945612",
    "monto": 10.50,
    "id_caja_sesion": 101
  }'

​
Response — RecargaCliente

​
id
number
Unique identifier of the top-up record.
​
operadora
string
Mobile carrier used: "Tigo", "Entel", or "Viva".
​
numero_cliente
string
Phone number that received the top-up.
​
monto
number
Top-up amount processed.
​
fecha_hora
string
ISO 8601 timestamp of the transaction.
​
id_caja_sesion
number
ID of the session this transaction is linked to.

​
Inject Balance to an Operator

POST /recargas/inyeccion
Injects (adds) balance to a specific mobile operator’s store account. This represents a purchase of operator credit, and the cost is recorded as an EGRESO on the specified cash register session. Use this endpoint whenever the store replenishes its top-up stock with a carrier.

​
Request Body

​
operadora_destino
string
required
The mobile carrier whose balance is being replenished. One of: "Tigo", "Entel", "Viva".
​
monto
number
required
Amount of balance to inject. Minimum 1.
​
id_caja_sesion
number
required
ID of the active session from which the injection cost is deducted.
curl -X POST https://api.example.com/recargas/inyeccion \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "operadora_destino": "Tigo",
    "monto": 100.00,
    "id_caja_sesion": 101
  }'

​
Response — InyeccionOperadora

​
id
number
Unique identifier of the injection record.
​
operadora_destino
string
Mobile carrier whose balance was topped up.
​
monto
number
Injected amount.
​
fecha_hora
string
ISO 8601 timestamp of the injection.
​
id_caja_origen
number
ID of the session from which the cash was deducted.

​
List All Operator Balances

GET /recargas/operadoras/saldos
Returns the current balance (saldo_actual) for each registered mobile operator. Use this before processing a client top-up to verify sufficient funds are available. 
curl https://api.example.com/recargas/operadoras/saldos \
  -H "Authorization: Bearer <access_token>"

​
Response — OperadoraSaldo[]

​
id
number
Unique identifier.
​
nombre_operadora
string
Carrier name: "Tigo", "Entel", or "Viva". Unique per carrier.
​
saldo_actual
number
Current available balance for selling top-ups to clients.

​
List Client Top-Up History

GET /recargas/historial/clientes
Returns the complete history of all client top-up transactions, ordered by date. Useful for shift summaries, reconciliation, and customer lookup. 
curl https://api.example.com/recargas/historial/clientes \
  -H "Authorization: Bearer <access_token>"

​
List Operator Injection History

GET /recargas/historial/inyecciones
Returns the complete history of all operator balance injections. Use this to audit when and how much balance was purchased from each carrier. 
curl https://api.example.com/recargas/historial/inyecciones \
  -H "Authorization: Bearer <access_token>"

​
TypeScript Interfaces

// Supported mobile carriers
type OperadoraNombre = 'Tigo' | 'Entel' | 'Viva';

interface RecargaCliente {
  id: number;
  operadora: OperadoraNombre;
  numero_cliente: string;
  monto: number;               // min: 0.1
  fecha_hora: string;          // ISO 8601 timestamp
  id_caja_sesion: number;
}

interface InyeccionOperadora {
  id: number;
  operadora_destino: OperadoraNombre;
  monto: number;               // min: 1
  fecha_hora: string;          // ISO 8601 timestamp
  id_caja_origen: number;      // Session from which cash was deducted
}

interface OperadoraSaldo {
  id: number;
  nombre_operadora: OperadoraNombre;  // Unique per carrier
  saldo_actual: number;               // Current available balance
}

// POST /recargas/cliente request body
interface CreateRecargaClienteDto {
  operadora: OperadoraNombre;
  numero_cliente: string;
  monto: number;               // min: 0.1
  id_caja_sesion: number;
}

// POST /recargas/inyeccion request body
interface CreateInyeccionDto {
  operadora_destino: OperadoraNombre;
  monto: number;               // min: 1
  id_caja_sesion: number;
}

​
Balance Flow Overview

The recargas module follows a two-step cycle:
  1. Inject balance (POST /recargas/inyeccion) — store purchases credit from a carrier. Cash exits the register (EGRESO), operator saldo_actual increases.
  2. Sell top-up (POST /recargas/cliente) — store sells credit to a client. Cash enters the register, operator saldo_actual decreases.
Monitor GET /recargas/operadoras/saldos regularly to ensure each carrier has sufficient balance before peak selling hours.

Build docs developers (and LLMs) love

Get started for freeTalk to us