Saltar al contenido principal

Imputar cobros entrantes a comprobantes

Cuando llega un cobro a una cuenta recaudadora, Max Pay registra un movement pero no lo vincula automáticamente a un comprobante específico. La decisión de "este pago cancela esta factura" la toma siempre el integrador, porque solo el ERP conoce la lógica contable del customer.

Esta guía cubre el patrón típico de imputación: recibir un webhook de cobro, identificar a qué comprobante corresponde, y marcarlo como pagado.

Para entender por qué Max Pay no vincula automáticamente, ver Comprobantes, Movements y Liquidaciones.

Flujo​

1. Recibir el movement​

Cuando un cliente transfiere a una cuenta recaudadora, Max Pay emite movement.created:

{
  "type": "movement.created",
  "data": {
    "movement": {
      "id": 88123,
      "receivableAccountId": 4242,
      "movementType": "CREDIT",
      "operationType": "DEPOSIT",
      "amount": 45000.00,
      "counterParty": {
        "name": "Kiosco Central",
        "taxId": "30998888887"
      }
    }
  }
}

El counterParty.taxId es la clave para identificar al cliente. El receivableAccountId indica sobre qué cuenta se acreditó.

2. Buscar comprobantes candidatos​

Listar los comprobantes PENDING del cliente (o de la cuenta) que podrían corresponder al cobro:

GET /v1/receivables?receivableAccountId=4242&status=PENDING

Si el customer opera con cuentas en Patrón A (una cuenta por cliente), basta con filtrar por receivableAccountId. En Patrón B o C donde una misma cuenta tiene varios clientes, se filtra adicionalmente por clientId resuelto a partir del taxId.

3. Decidir el match​

La estrategia depende del modelo del customer:

  • Match exacto por monto: si el movement.amount matchea exactamente con un único comprobante PENDING, se imputa directo.
  • Match por externalId: si tu ERP envía el número de factura del lado del cliente (por DEBIN o por referencia bancaria) y lo guardaste en externalId al crear el comprobante, el match es trivial.
  • Match parcial: si entró menos plata de la facturada, el integrador puede registrar un RETENTION o ADJUSTMENT por la diferencia (ver Notas de crédito y ajustes) y marcar el comprobante como PAID.
  • Cobro adelantado / múltiple: si entra más plata que la facturada, queda como saldo a favor sin comprobante asociado. Se imputa cuando aparezca el próximo comprobante.

4. Marcar como PAID​

Una vez identificado el comprobante:

PATCH /v1/receivables/99001/status
Idempotency-Key: erp-mark-paid-99001
Content-Type: application/json

{ "status": "PAID" }

Max Pay emite receivable.paid. El comprobante queda contabilizado como cobrado.

Conciliación al cierre​

El cambio a PAID es decisión administrativa del integrador, no implica que el dinero haya entrado a la cuenta corriente del customer. La transferencia efectiva del dinero ocurre en el ciclo de liquidación, que mueve los montos cobrados desde la cuenta recaudadora hacia la cuenta corriente del customer.

El reporte de liquidación muestra la diferencia entre el monto liquidado (lo que efectivamente entró) y los comprobantes marcados como PAID/SETTLED (lo que el ERP declaró). Esa diferencia ayuda a detectar imputaciones erradas o cobros sin comprobante.

Caso especial: rollback​

Si un movement entrante se revierte (rechazo del banco después de acreditado), Max Pay emite un nuevo movement.created con operationType: ROLLBACK que referencia al movement original. Si el integrador ya había marcado el comprobante como PAID por ese cobro, debe revertir la imputación anulando el comprobante y emitiendo uno nuevo si corresponde (ver Lifecycle — no hay rollback nativo de PAID a PENDING).