Skip to main content
GET
/
api
/
cuentas-por-cobrar
Cuentas por Cobrar
curl --request GET \
  --url https://api.example.com/api/cuentas-por-cobrar \
  --header 'Content-Type: application/json' \
  --data '
{
  "monto_pagado": 123,
  "fecha_pago": "<string>",
  "observaciones": "<string>"
}
'
{
  "400": {},
  "404": {},
  "422": {},
  "success": true,
  "data": [
    {
      "id_dia_venta": 123,
      "id_venta": 123,
      "documento": "<string>",
      "cliente": "<string>",
      "cliente_documento": "<string>",
      "fecha_emision": "<string>",
      "numero_cuota": 123,
      "fecha_vencimiento": "<string>",
      "monto_cuota": 123,
      "monto_pagado": 123,
      "saldo": 123,
      "estado": "<string>",
      "fecha_pago": "<string>",
      "observaciones": "<string>"
    }
  ],
  "resumen": {
    "total_pendiente": 123,
    "total_vencido": 123,
    "proximas_vencer": 123,
    "total_cobrado_mes": 123
  }
}

​
Autenticación

Este endpoint requiere autenticación mediante token Bearer y el permiso cuentas-cobrar.view.

​
Listar Cuentas por Cobrar

GET /api/cuentas-por-cobrar Retorna todas las cuotas de ventas a crédito con información del cliente y resumen financiero.

​
Parámetros de Query

​
estado
string
Filtrar por estado: ‘P’ (Pendiente), ‘C’ (Cancelada), ‘V’ (Vencida)
​
fecha_desde
date
Fecha de vencimiento desde (formato: Y-m-d)
​
fecha_hasta
date
Fecha de vencimiento hasta (formato: Y-m-d)
​
cliente
string
Buscar por nombre o documento del cliente (búsqueda parcial)

​
Respuesta

​
success
boolean
Indica si la operación fue exitosa
​
data
array
Lista de cuotas pendientes de cobro
​
resumen
object
Resumen financiero de las cuentas por cobrar

​
Ejemplo de Respuesta

{
  "success": true,
  "data": [
    {
      "id_dia_venta": 15,
      "id_venta": 89,
      "documento": "F001-00000089",
      "cliente": "CORPORACION XYZ S.A.C.",
      "cliente_documento": "20612706702",
      "fecha_emision": "2024-02-15",
      "numero_cuota": 1,
      "fecha_vencimiento": "2024-03-15",
      "monto_cuota": "2500.00",
      "monto_pagado": "1000.00",
      "saldo": "1500.00",
      "estado": "P",
      "fecha_pago": "2024-03-01",
      "observaciones": "Pago parcial recibido"
    },
    {
      "id_dia_venta": 16,
      "id_venta": 89,
      "documento": "F001-00000089",
      "cliente": "CORPORACION XYZ S.A.C.",
      "cliente_documento": "20612706702",
      "fecha_emision": "2024-02-15",
      "numero_cuota": 2,
      "fecha_vencimiento": "2024-04-15",
      "monto_cuota": "2500.00",
      "monto_pagado": "0.00",
      "saldo": "2500.00",
      "estado": "P",
      "fecha_pago": null,
      "observaciones": null
    },
    {
      "id_dia_venta": 8,
      "id_venta": 72,
      "documento": "F001-00000072",
      "cliente": "COMERCIAL ANDES S.A.",
      "cliente_documento": "20543210987",
      "fecha_emision": "2024-01-20",
      "numero_cuota": 3,
      "fecha_vencimiento": "2024-02-28",
      "monto_cuota": "1800.00",
      "monto_pagado": "0.00",
      "saldo": "1800.00",
      "estado": "V",
      "fecha_pago": null,
      "observaciones": null
    }
  ],
  "resumen": {
    "total_pendiente": "45380.50",
    "total_vencido": "8950.00",
    "proximas_vencer": 5,
    "total_cobrado_mes": "12340.00"
  }
}

​
Registrar Pago de Cuota

POST /api/cuentas-por-cobrar/{id}/pagar - Requiere permiso cuentas-cobrar.edit Registra un pago (total o parcial) de una cuota.

​
Parámetros del Body

​
monto_pagado
decimal
required
Monto del pago recibido (debe ser mayor a 0.01)
​
fecha_pago
date
required
Fecha en que se recibió el pago (formato: Y-m-d)
​
observaciones
string
Notas sobre el pago (máximo 500 caracteres)

​
Ejemplo de Solicitud

curl -X POST \
  https://tudominio.com/api/cuentas-por-cobrar/15/pagar \
  -H 'Authorization: Bearer TU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "monto_pagado": 1500.00,
    "fecha_pago": "2024-03-05",
    "observaciones": "Pago mediante transferencia bancaria"
  }'

​
Respuesta

{
  "success": true,
  "message": "Pago registrado exitosamente"
}

​
Lógica de Pago

Cuando se registra un pago:
  1. Se suma el monto_pagado nuevo al monto_pagado existente
  2. Se recalcula el saldo = monto_cuota - monto_pagado_total
  3. Si el saldo llega a 0 o menos, la cuota cambia a estado ‘C’ (Cancelada)
  4. Los pagos parciales mantienen el estado ‘P’ (Pendiente) hasta cubrir el monto total

​
Estados de Cuotas

  • P (Pendiente) - Cuota no pagada o parcialmente pagada, aún no vencida
  • C (Cancelada) - Cuota totalmente pagada
  • V (Vencida) - Cuota pendiente con fecha de vencimiento pasada
Los estados ‘P’ y ‘V’ se determinan automáticamente usando scopes del modelo DiaVenta:
  • pendientes() - Cuotas con estado ‘P’ y saldo > 0
  • vencidas() - Cuotas pendientes con fecha_vencimiento < hoy
  • proximasVencer(7) - Cuotas que vencen en los próximos 7 días

​
Exportar a Excel

GET /api/cuentas-por-cobrar/exportar-excel - Requiere permiso cuentas-cobrar.view Genera un archivo Excel con todas las cuentas por cobrar filtradas.

​
Relación con Ventas

Las cuentas por cobrar se generan automáticamente cuando se crea una venta a crédito:
  1. Al crear una venta con forma_pago = ‘Credito’
  2. El sistema crea registros en la tabla dias_ventas según el plan de cuotas
  3. Cada cuota tiene: monto, fecha_vencimiento, estado inicial ‘P’
  4. Solo las ventas con estado = '1' (activas) se consideran para cuentas por cobrar

​
Códigos de Error

​
400
object
Cuota ya cancelada
{
  "success": false,
  "message": "Esta cuota ya está cancelada"
}
​
404
object
Cuota no encontrada
{
  "success": false,
  "message": "Cuota no encontrada"
}
​
422
object
Error de validación
{
  "success": false,
  "message": "Error de validación",
  "errors": {
    "monto_pagado": ["El campo monto pagado es obligatorio"],
    "fecha_pago": ["El campo fecha pago es obligatorio"]
  }
}

Build docs developers (and LLMs) love

Get started for freeTalk to us