Saltar al contenido principal

Operaciones avanzadas sobre cuentas

Esta guía cubre tres operaciones que no son parte del alta simple:

Vinculación post-hoc del operador​

Una cuenta puede crearse inicialmente como Patrón A (solo clientId) y luego transicionar a Patrón C al asignarle un associateId. Esto es útil cuando el operador todavía no está dado de alta al momento de crear la cuenta.

Hay dos caminos para vincular un asociado a una cuenta existente:

Camino A — Especificar associateId al registrar un comprobante​

Si al hacer POST /v1/receivables se incluye associateId y la cuenta destino aún no tiene asociado, el sistema vincula post-hoc al asociado a la cuenta antes de registrar el comprobante. La cuenta queda como Patrón C desde ese momento.

POST /v1/receivables
Content-Type: application/json
Idempotency-Key: rcv-2026-04-01-9001

{
  "receivableAccountId": 5511,
  "associateId": 8821,
  "amount": 12500,
  "dueDate": "2026-04-30",
  "externalId": "FAC-A-0001-00009001"
}

Si la cuenta ya tenía un associateId distinto, la API responde 409 con un código específico. Si el asociado pertenece a otro customer, responde 403.

Camino B — Actualizar la cuenta explícitamente​

PUT /v1/receivable-accounts/{id}
Content-Type: application/json

{
  "associateId": 8821
}

Esto aplica la vinculación sin registrar un comprobante. Si la cuenta ya tenía asociado, ver Reasignación de operador.

Reasignación de operador​

Cuando una cuenta ya tiene un associateId y se necesita cambiarlo (por ejemplo, baja del chofer asignado o cambio de tutor en el modelo educativo), el flujo es:

  1. Deshabilitar la cuenta actual si se quiere cortar el CVU vinculado al asociado anterior (PUT /v1/receivable-accounts/{id}/status con status: DISABLED).
  2. Crear una cuenta nueva apuntando al nuevo asociado (POST /v1/receivable-accounts con el nuevo associateId).

No se permite reemplazar un associateId por otro distinto sobre una cuenta activa con CVU ya provisionado: el CVU está atado a la identidad del owner y reasignar implica generar un CVU nuevo. La API responde 422 con un código específico ante intentos de cambiar el associateId por uno distinto en cuentas activas.

Si el asociado se da de baja (DELETE /v1/associates/{id}), las cuentas que tenían a ese asociado vinculado mantienen el estado ACTIVE pero quedan sin asociado (transicionan a Patrón A — cuenta de cliente). El CVU sigue operando contra el clientId que tenía la cuenta. Si querés re-asignar a un asociado nuevo, podés vincular post-hoc al nuevo (ver Vinculación post-hoc) — esto sí está permitido sobre la cuenta ACTIVE porque no reemplaza un associate existente, lo agrega.

Alta masiva​

Para escenarios donde se necesita dar de alta varias cuentas de una vez, existe POST /v1/receivable-accounts/batches. Procesa de forma asíncrona y notifica el resultado por webhook.

POST /v1/receivable-accounts/batches
Idempotency-Key: erp-batch-rac-2026-05-15
Content-Type: application/json

{
  "items": [
    { "clientId": 5001, "associateId": 6001 },
    { "clientId": 5002, "associateId": 6002 }
  ]
}
202 Accepted
Location: /v1/receivable-accounts/batches/1203

{
  "batchId": 1203,
  "status": "PROCESSING",
  "totalItems": 2
}

Cuando termina el procesamiento, Max Pay emite el evento receivable-account.batch.completed con un reporte detallado (success/failure por item). Ver Catálogo de eventos.