Skip to main content

​
Visión General

El módulo de Cuentas por Cobrar permite gestionar las facturas pendientes de pago de clientes, incluyendo seguimiento de cuotas, vencimientos y estados de pago. Se basa en el modelo DiaVenta que representa las cuotas de pago de cada venta.
Las cuentas por cobrar se generan automáticamente cuando se crea una venta a crédito. Cada cuota tiene su propio seguimiento de pagos y vencimientos.

​
Estructura de Datos

​
Modelo DiaVenta

La tabla dias_ventas almacena las cuotas de pago: 
protected $fillable = [
    'id_venta',
    'numero_cuota',           // Número de cuota (1, 2, 3...)
    'fecha_vencimiento',      // Fecha límite de pago
    'monto_cuota',            // Monto original de la cuota
    'monto_pagado',           // Monto ya pagado (permite pagos parciales)
    'saldo',                  // Saldo pendiente
    'estado',                 // P=Pendiente, C=Cancelada, V=Vencida
    'fecha_pago',             // Fecha de pago efectivo
    'observaciones',
];

​
Estados de Cuota

  • P (Pendiente): La cuota no ha sido pagada y no está vencida
  • C (Cancelada): La cuota ha sido pagada completamente
  • V (Vencida): La cuota está pendiente y su fecha de vencimiento ya pasó
El sistema actualiza automáticamente el estado a “V” cuando la fecha de vencimiento es anterior a la fecha actual.

​
API Endpoints

​
Listar Cuentas por Cobrar

CuentasPorCobrarController.php:12
GET /api/cuentas-por-cobrar
Filtros disponibles:
​
estado
string
Estado de la cuota: P (Pendiente), C (Cancelada), V (Vencida)
​
fecha_desde
date
Filtrar por fecha de vencimiento desde
​
fecha_hasta
date
Filtrar por fecha de vencimiento hasta
​
cliente
string
Buscar por nombre o documento del cliente
Respuesta: 
{
  "success": true,
  "data": [
    {
      "id_dia_venta": 45,
      "id_venta": 123,
      "documento": "F001-00000123",
      "cliente": "EMPRESA SAC",
      "cliente_documento": "20612706702",
      "fecha_emision": "2026-03-01",
      "numero_cuota": 1,
      "fecha_vencimiento": "2026-04-01",
      "monto_cuota": "1500.00",
      "monto_pagado": "500.00",
      "saldo": "1000.00",
      "estado": "P",
      "fecha_pago": null,
      "observaciones": null
    }
  ],
  "resumen": {
    "total_pendiente": "25000.00",
    "total_vencido": "3500.00",
    "proximas_vencer": 12,
    "total_cobrado_mes": "18000.00"
  }
}

​
Registrar Pago

CuentasPorCobrarController.php:102
POST /api/cuentas-por-cobrar/{id}/pagar
Request Body: 
{
  "monto_pagado": 500.00,
  "fecha_pago": "2026-03-06",
  "observaciones": "Pago parcial - transferencia bancaria"
}
El sistema permite pagos parciales. Si el monto pagado no cubre el saldo total, la cuota permanecerá en estado “P” (Pendiente).
Lógica de pagos parciales:
CuentasPorCobrarController.php:123
$montoPago = $request->monto_pagado;
$nuevoMontoPagado = $cuota->monto_pagado + $montoPago;
$nuevoSaldo = $cuota->monto_cuota - $nuevoMontoPagado;

$cuota->monto_pagado = $nuevoMontoPagado;
$cuota->saldo = max(0, $nuevoSaldo);

if ($nuevoSaldo <= 0) {
    $cuota->estado = 'C';  // Marcar como Cancelada
}

​
Scopes de Consulta

El modelo DiaVenta incluye scopes útiles para filtrar cuotas:
DiaVenta.php:41
public function scopePendientes($query)
{
    return $query->where('estado', 'P');
}

public function scopeCanceladas($query)
{
    return $query->where('estado', 'C');
}

public function scopeVencidas($query)
{
    return $query->where('estado', 'V');
}

public function scopeProximasVencer($query, int $dias = 7)
{
    return $query->where('estado', 'P')
        ->whereBetween('fecha_vencimiento', [now(), now()->addDays($dias)]);
}
Uso en controladores: 
// Obtener cuotas pendientes
$pendientes = DiaVenta::pendientes()->get();

// Obtener cuotas que vencen en los próximos 7 días
$proximasVencer = DiaVenta::proximasVencer(7)->get();

// Total de saldo vencido
$totalVencido = DiaVenta::vencidas()->sum('saldo');

​
Relaciones de Base de Datos

​
Permisos Requeridos

Para acceder a este módulo, el usuario necesita:
  • Ver cuentas por cobrar: cuentas-cobrar.view
  • Registrar pagos: cuentas-cobrar.edit
  • Generar reportes: cuentas-cobrar.report
Los usuarios con rol_id = 1 (Administrador) tienen acceso completo sin necesidad de permisos específicos.

​
Integración con Frontend

El componente React de cuentas por cobrar se encuentra en: 
resources/js/components/Finanzas/CuentasPorCobrar/
├── page.jsx              # Lista principal con DataTable
├── columns/              # Definición de columnas
└── hooks/                # useObtenerCuentasCobrar
Patrón de llamada API: 
import { obtenerCuentasCobrar, registrarPago } from '@/services/finanzas';

const { data: cuentas, isLoading } = useQuery({
  queryKey: ['cuentas-cobrar', filtros],
  queryFn: () => obtenerCuentasCobrar(filtros),
  staleTime: 5 * 60 * 1000,
});

​
Reportes y Exportación

El módulo incluye opciones de exportación:
  • Excel: Lista de cuentas con filtros aplicados
  • PDF: Reporte de antigüedad de saldos
  • Dashboard: Métricas de cobranza en tiempo real
// Resumen de cobranza mensual
$totalCobradoMes = DiaVenta::canceladas()
    ->whereMonth('fecha_pago', now()->month)
    ->whereYear('fecha_pago', now()->year)
    ->sum('monto_pagado');

Build docs developers (and LLMs) love

Get started for freeTalk to us