Modelos de operación del customer
Los modelos de operación describen los distintos patrones de uso de Max Pay según el negocio del customer. Entenderlos es necesario para decidir cómo crear cuentas recaudadoras y cómo asignar clientes y asociados. Esta página es la base conceptual del resto de la documentación.
Building blocks
Hay tres entidades involucradas en una recaudación:
| Entidad | Representa | Ejemplo |
|---|---|---|
| Customer | El comercio que usa Max Pay. Implícito en tu API key. | DistribuidoraDemo S.A. |
| Client | Un cliente del customer. Empresa, persona, o entidad lógica como un alumno. | Kiosco Central; Tomás López (alumno) |
| Associate | Un operador del customer. Persona física que opera con la plataforma. | Operario 042 (chofer); Familia López (tutor pagador) |
Sobre estas entidades se construyen las cuentas recaudadoras (receivable-accounts), que son las cuentas con CVU dedicado donde los clientes transfieren para pagar.
Patrones de cuenta recaudadora
Una cuenta recaudadora se ata opcionalmente a un client, opcionalmente a un associate, o a ambos. Estos son los 3 patrones soportados:
| Patrón | clientId | associateId | El customer puede ver lo cobrado por... | Cuándo aplica |
|---|---|---|---|---|
| A Cuenta de cliente sin operador | ✓ | — | Cliente | Cuenta de un kiosco/comercio sin chofer asignado todavía |
| B Cuenta de operador sin discriminar cliente | — | ✓ | Operador | Choferes que recaudan a granel y rinden al customer |
| C Cuenta de cliente con operador asignado | ✓ | ✓ | Cliente + Operador | Chofer que ya escaneó facturas de un cliente; alumno con tutor pagador |
Una cuenta sin client ni associate no es válida para las cuentas recaudadoras. Esa combinación está reservada para la cuenta corriente MAIN del customer.
Patrón A — Cuenta de cliente sin operador
Caso típico: customer B2B que da de alta un cliente nuevo y le registra una factura antes de que ningún chofer haya entregado mercadería en ese punto de venta.
Si el customer es una PyME pequeña donde un único administrador controla todas las cuentas de los clientes, el patrón A puede ser permanente. Si el customer tiene flota, este patrón es transitorio hasta que un chofer escanea la primera factura y la cuenta pasa al patrón C.
Patrón B — Cuenta de operador sin discriminar cliente
Caso típico: customer cuyo modelo operativo es "el chofer va de comercio en comercio y cobra; al cierre del día rinde el total". No interesa identificar cuánto pagó cada cliente final.
Los clientes finales no se modelan en Max Pay para este caso. La identificación del pagador queda en los metadatos del movement (campo counterParty con su taxId y nombre), si el customer la necesita para conciliación.
Patrón C — Cuenta de cliente con operador asignado
Este patrón cubre dos casos de negocio distintos:
Caso C.1 — Cliente con chofer asignado
Caso típico: un chofer del customer escanea una factura emitida a un kiosco. A partir de ese momento, todas las facturas que se emitan a ese kiosco quedan asociadas a su cuenta, y tanto el customer como el chofer pueden ver el detalle de lo cobrado por cliente.
Es habitual que una cuenta arranque como Patrón A y transicione a Patrón C al asignarle un associate. Ver vinculación post-hoc del operador.
Caso C.2 — Cliente y operador son la misma persona real (modelo educativo / clubes)
En instituciones educativas, el alumno se modela como client (entidad cliente con su CUIL/CUIT). El pagador (que puede ser el mismo alumno mayor de edad, o el padre/tutor) se modela como associate vinculado a esa cuenta para que pueda ver el estado de cuenta y operar. El diagrama es el mismo que C.1, cambiando los roles representados.
Es válido que un client y un associate compartan taxId. No es duplicación: representan roles distintos de la misma persona (cliente vs operador). Cuando crees ambos, vas a recibir dos eventos: client.created y associate.created.
¿Cuál patrón es el mío?
Decisión rápida según tu modelo de negocio:
| Pregunta | Sí | No |
|---|---|---|
| ¿Identificás al cliente por su CUIT? | Patrón A o C | Patrón B |
| ¿Hay un operador (chofer, vendedor, tutor) que opera la cuenta? | Patrón C | Patrón A |
| ¿El operador rinde a granel sin discriminar cliente? | Patrón B | Patrón A o C |
| Caso educativo: alumno + tutor (misma persona o no) | Patrón C.2 | — |
Ejemplos:
- Distribuidora B2B que factura a kioscos y rastrea cada cobro contra su cliente → Patrón A.
- Flota de fletes donde el chofer cobra varios servicios en la jornada y los rinde a fin de día → Patrón B.
- Distribuidora con chofer asignado por zona que cobra a kioscos del recorrido → Patrón C.1.
- Instituto educativo donde el alumno es el cliente y el tutor el pagador → Patrón C.2.
Cómo se elige el patrón en la práctica
No tenés que declarar "qué patrón usás" en ningún lado. Cada cuenta recaudadora se crea con los IDs que correspondan, y el sistema deduce el patrón automáticamente. Un mismo customer puede tener cuentas de distintos patrones simultáneamente (por ejemplo, distintas regiones operando distinto).
Algunas operaciones requieren coherencia con la configuración del customer. Por ejemplo, si tu configuración no incluye associates, vas a recibir 403 owner-type-not-supported al intentar pasar un associateId. En ese caso, escalá con tu account manager para revisar la configuración comercial.
Próximos pasos
- Crear cuentas recaudadoras: flujos completos por patrón, con código de ejemplo.
- Emitir comprobantes: cómo registrar deuda y sus modificaciones una vez que la cuenta existe.