Pagos

Endpoints para gestionar pagos, consultar métricas del dashboard y registrar cobros.

Cuando todos los pagos de una venta alcanzan el estado pagado, la venta cambia automáticamente a estado completada.

GET/pagos/dashboard

Dashboard de pagos

Devuelve métricas agregadas para el dashboard de pagos: totales cobrados, pendientes, pagos del día, y más.

Response

{
  "total_cobrado": 125000.00,
  "total_pendiente": 48000.00,
  "pagos_hoy": 5,
  "pagos_vencidos": 3,
  "ventas_activas": 12,
  "ventas_completadas": 45,
  "cobranza_mes": 32000.00
}

GET/pagos

Listar pagos

Devuelve la lista de pagos. Se puede filtrar por estado, venta o rango de fechas.

Name
venta_id
Type
number
Description
Filtra pagos por ID de venta.
Name
estado
Type
string
Description
Filtra por estado: pendiente, pagado, fallido, cancelado.
Name
fecha_desde
Type
string
Description
Fecha inicial del rango (formato YYYY-MM-DD).
Name
fecha_hasta
Type
string
Description
Fecha final del rango (formato YYYY-MM-DD).

Request con filtros

curl -H "Authorization: Bearer TOKEN" \
  "https://api.mundodelentes.com/pagos?estado=pendiente&fecha_hasta=2025-03-15"

Response

[
  {
    "id": 3,
    "venta_id": 1,
    "tipo": "quincenal",
    "estado": "pendiente",
    "monto": 500.00,
    "fecha_esperada": "2025-03-15",
    "fecha_pago": null,
    "metodo_pago": null,
    "referencia": null
  }
]

GET/pagos/:id

Obtener pago

Devuelve los detalles de un pago específico, incluyendo la información de la venta asociada.

Response

{
  "id": 2,
  "venta_id": 1,
  "venta": {
    "id": 1,
    "cliente": {
      "id": 1,
      "nombre": "Juan Pérez"
    },
    "monto_total": 5000.00,
    "saldo_pendiente": 3000.00
  },
  "tipo": "quincenal",
  "estado": "pagado",
  "monto": 500.00,
  "metodo_pago": "transferencia",
  "referencia": "REF-20250301-001",
  "fecha_esperada": "2025-03-01",
  "fecha_pago": "2025-03-01T10:30:00Z"
}

PUT/pagos/:id

Actualizar pago

Actualiza los datos de un pago. Útil para corregir información antes de registrar el cobro.

Name
monto
Type
number
Description
Monto del pago en MXN.
Name
fecha_esperada
Type
string
Description
Fecha esperada de pago (formato YYYY-MM-DD).

Request body

{
  "monto": 550.00,
  "fecha_esperada": "2025-03-20"
}

Response

{
  "id": 3,
  "venta_id": 1,
  "tipo": "quincenal",
  "estado": "pendiente",
  "monto": 550.00,
  "fecha_esperada": "2025-03-20",
  "fecha_pago": null
}

POST/pagos/:id/registrar

Registrar pago

Registra el cobro de un pago pendiente o fallido. Cambia el estado del pago a pagado y reduce el saldo_pendiente de la venta asociada.

Name
metodo_pago
Type
string
Description
Método de pago: efectivo, transferencia o tarjeta.
Name
monto
Type
number
Description
Monto cobrado en MXN.
Name
referencia
Type
string
Description
Referencia o folio del pago (opcional).

Al registrar un pago, el sistema automáticamente reduce el saldo_pendiente de la venta. Si todos los pagos quedan en estado pagado, la venta cambia a completada.

Request body

{
  "metodo_pago": "efectivo",
  "monto": 500.00,
  "referencia": "REC-20250315-042"
}

Response

{
  "id": 3,
  "venta_id": 1,
  "tipo": "quincenal",
  "estado": "pagado",
  "monto": 500.00,
  "metodo_pago": "efectivo",
  "referencia": "REC-20250315-042",
  "fecha_esperada": "2025-03-15",
  "fecha_pago": "2025-03-15T16:45:00Z",
  "venta": {
    "id": 1,
    "saldo_pendiente": 2500.00,
    "estado": "activa"
  }
}

Estados de pago

Estado	Descripción	Transiciones posibles
pendiente	Pago aún no realizado	pagado, fallido, cancelado
pagado	Pago registrado exitosamente	— (estado final)
fallido	Intento de pago fallido	pagado (reintento)
cancelado	Cancelado por cancelación de venta	— (estado final)

Un pago con estado fallido puede reintentarse usando el endpoint POST /pagos/:id/registrar. Esto permite corregir y registrar el cobro nuevamente.