Cobros y Pagos

Estados de pago de documento

Cada documento de venta (factura de cliente) o compra (factura de proveedor) lleva un estado de pago que refleja la situacion real del cobro o pago.

Estados

Estado	Significado
pending	El documento esta pendiente de cobro/pago. No se ha registrado nada aun.
partial	Se ha registrado un pago parcial o un cobro parcial. Queda importe pendiente.
paid	El documento esta completamente pagado/cobrado. El importe registrado >= importe total.
overpaid	El importe registrado supera el total del documento. Solo informativo.

Transiciones validas

pending → partial → paid
pending → paid (pago unico)
partial → paid (se completa el pago)

Tambien puede volver de paid a partial si se elimina o reduce un pago registrado.

---

Registro de cobros

Un cobro es un registro de pago recibido de un cliente. Se vincula a uno o varios documentos (facturas, albaranes, pedidos).

Modelo

interface PaymentIn {
  id: string;
  partner_id: string;
  amount: number;
  payment_date: string;       // YYYY-MM-DD
  payment_method: string;     // "transfer", "cash", "card", "cheque", "effects"
  bank_account_id?: string;
  reference?: string;         // numero de transferencia, cheque, etc.
  notes?: string;
  linked_documents: {
    document_type: string;    // "sales_invoice", "sales_delivery_note"
    document_id: string;
    amount_applied: number;   // importe aplicado a este documento
  }[];
  created_by: string;
  created_at: string;
}

Endpoints

Registrar cobro

POST /api/payments/in
Authorization: Bearer <token>
Content-Type: application/json

{
  "partner_id": "bp_cliente1",
  "amount": 1210.00,
  "payment_date": "2026-05-08",
  "payment_method": "transfer",
  "bank_account_id": "ba_cts1",
  "reference": "TRF-2026-0508-001",
  "linked_documents": [
    {
      "document_type": "sales_invoice",
      "document_id": "inv_2026_0012",
      "amount_applied": 1210.00
    }
  ]
}

Respuesta:

{
  "data": {
    "id": "pay_in_001",
    "partner_id": "bp_cliente1",
    "amount": 1210.00,
    "payment_date": "2026-05-08",
    "status": "linked",
    "linked_documents": [
      {
        "document_type": "sales_invoice",
        "document_id": "inv_2026_0012",
        "previous_status": "pending",
        "new_status": "paid"
      }
    ]
  }
}

El estado del documento inv_2026_0012 pasa automaticamente a paid.

Listar cobros

GET /api/payments/in?partner_id=bp_cliente1&from=2026-01-01&to=2026-12-31
Authorization: Bearer <token>

Obtener un cobro

GET /api/payments/in/:id

Eliminar cobro

DELETE /api/payments/in/:id

Nota: Al eliminar un cobro se recalcula el estado del documento vinculado. Si el documento vuelve a estar pendiente, su estado vuelve a pending o partial segun el importe restante.

---

Registro de pagos

Un pago es un registro de dinero enviado a un proveedor. Funciona igual que los cobros pero en sentido inverso.

Modelo

interface PaymentOut {
  id: string;
  partner_id: string;
  amount: number;
  payment_date: string;
  payment_method: string;
  bank_account_id?: string;
  reference?: string;
  notes?: string;
  linked_documents: {
    document_type: string;    // "purchase_invoice", "purchase_delivery_note"
    document_id: string;
    amount_applied: number;
  }[];
  created_by: string;
  created_at: string;
}

Endpoints

Metodo	Ruta	Descripcion
GET	/api/payments/out	Listar pagos
POST	/api/payments/out	Registrar pago
GET	/api/payments/out/:id	Obtener pago
DELETE	/api/payments/out/:id	Eliminar pago

---

Conciliacion automatica

Keirost puede conciliar automaticamente pagos recibidos con facturas pendientes usando la referencia del pago (numero de transferencia, CCC, etc.) o el importe.

Modos de conciliacion

Modo	Descripcion
by_reference	Busca facturas pendientes del partner cuya referencia coincida con la del pago
by_amount	Busca facturas pendientes del partner con el mismo importe total
by_date	Busca facturas pendientes en un rango de fechas del partner
manual	El usuario selecciona manualmente que facturas pagar

Conciliacion por referencia

Cuando se registra un cobro con reference y auto_reconcile: true:

POST /api/payments/in
Authorization: Bearer <token>
Content-Type: application/json

{
  "partner_id": "bp_cliente1",
  "amount": 1210.00,
  "payment_date": "2026-05-08",
  "payment_method": "transfer",
  "reference": "F-2026-0012",
  "auto_reconcile": true
}

El sistema:

1. Busca facturas pendientes del partner bp_cliente1
2. Busca una con referencia interna que coincida con F-2026-0012
3. Si la encuentra y el importe coincide, la enlaza automaticamente
4. Actualiza el estado del documento a paid

Ver estado de conciliacion

GET /api/payments/reconciliation/:documentType/:documentId

Devuelve el detalle de todos los cobros/pagos aplicados a un documento:

{
  "document_id": "inv_2026_0012",
  "document_total": 1210.00,
  "total_applied": 1210.00,
  "remaining": 0.00,
  "status": "paid",
  "payments": [
    {
      "payment_id": "pay_in_001",
      "payment_date": "2026-05-08",
      "amount_applied": 1210.00,
      "payment_method": "transfer"
    }
  ]
}

---

Metodos de pago

Modelos soportados

Metodo	Descripcion
transfer	Transferencia bancaria SEPA
cash	Efectivo
card	Tarjeta de credito o debito
cheque	Cheque empresarial
effects	Efectos comerciales (letras, pagarés)
direct_debit	Domiciliacion bancaria
voucher	Bono o vale

Cuentas bancarias

Cada empresa puede registrar multiples cuentas bancarias propias para pagar o recibir:

GET  /api/config/bank-accounts
POST /api/config/bank-accounts

{
  "name": "Cuenta principal",
  "iban": "ES9121000418450200051332",
  "bank_name": "Santander",
  "is_default": true
}

---

Informes de cobros y pagos

Aging (antiguedad de deuda)

GET /api/reports/aging
Authorization: Bearer <token>

Devuelve la deuda pendiente de clientes y proveedores segmentada por antiguedad:

{
  "customers": [
    {
      "partner_id": "bp_cliente1",
      "partner_name": "Acme S.L.",
      "total_debt": 3500.00,
      "current": 1000.00,
      "30_days": 1500.00,
      "60_days": 500.00,
      "90_plus": 500.00
    }
  ],
  "generated_at": "2026-05-08T10:00:00Z"
}

Resumen de pagos por periodo

GET /api/reports/payments-summary?from=2026-01-01&to=2026-03-31

{
  "period": "2026Q1",
  "total_in": 125000.00,
  "total_out": 89000.00,
  "net": 36000.00,
  "by_method": {
    "transfer": { "in": 110000, "out": 85000 },
    "cash": { "in": 10000, "out": 3000 },
    "card": { "in": 5000, "out": 1000 }
  }
}

---

Webhooks de pago

Puedes registrar webhooks para recibir notificaciones cuando se registra un cobro o pago:

{
  "event": "payment.registered",
  "url": "https://tu-sistema.com/webhook/payment",
  "method": "POST",
  "active": true
}

Payload del webhook:

{
  "event": "payment.registered",
  "timestamp": "2026-05-08T10:00:00Z",
  "data": {
    "payment_id": "pay_in_001",
    "type": "in",
    "partner_id": "bp_cliente1",
    "amount": 1210.00,
    "payment_date": "2026-05-08",
    "linked_documents": [
      {
        "document_type": "sales_invoice",
        "document_id": "inv_2026_0012",
        "new_document_status": "paid"
      }
    ]
  }
}