Asociados

Los asociados representan operadores del customer: choferes, distribuidores, alumnos pagadores, tutores, socios de un club. Son personas físicas vinculadas a la operatoria del customer.

Modelo

{
  "id": 88,
  "type": "DRIVER",
  "name": "Operario",
  "lastName": "042",
  "taxId": "20999999999",
  "documentNumber": "99999999",
  "email": "[email protected]",
  "phone": "+541111000042",
  "address": "Av. Las Heras 2000, CABA",
  "parentAssociateId": null,
  "status": "ACTIVE",
  "creationDate": "2026-04-10T10:00:00-03:00",
  "modificationDate": "2026-04-10T10:00:00-03:00"
}

Campo	Tipo	Requerido	Descripción
id	int64	(response)	ID asignado por Max Pay
type	string	Sí	Tipo libre. Convenciones: DRIVER, DISTRIBUTOR, STUDENT, GUARDIAN, MEMBER, OTHER
name	string	Sí	Nombre
lastName	string	Sí	Apellido
taxId	string	Sí	CUIT/CUIL, 11 dígitos sin guiones
documentNumber	string	Sí	DNI
email	string	Sí	Email de contacto
phone	string	Sí	Teléfono con código de país
address	string	No	Dirección
parentAssociateId	int64	No	Para jerarquías (asociado supervisor)
status	enum	(response)	ACTIVE o DISABLED

Sobre el campo type

type es un string libre, no un enum cerrado. El customer puede usar cualquier valor que tenga sentido para su modelo de negocio. La convención recomendada es usar valores en mayúsculas con guiones bajos (DRIVER, GUARDIAN, STUDENT_PAYER, etc.). Esto permite agregar tipos nuevos sin breaking changes.

Endpoints

Método	Path	Descripción
GET	/v1/associates	Lista con filtros
POST	/v1/associates	Crea un asociado
GET	/v1/associates/{id}	Detalle
PUT	/v1/associates/{id}	Actualiza
DELETE	/v1/associates/{id}	Deshabilita (soft delete)
POST	/v1/associates/{id}/activations	Rehabilita
GET	/v1/associates/{id}/receivable-accounts	Cuentas recaudadoras del asociado
GET	/v1/associates/{id}/route-settlements	Rendiciones por hoja de ruta del asociado

Crear un asociado

POST /v1/associates
Idempotency-Key: erp-asc-12345
Content-Type: application/json

{
  "type": "DRIVER",
  "name": "Operario",
  "lastName": "042",
  "taxId": "20999999999",
  "documentNumber": "99999999",
  "email": "[email protected]",
  "phone": "+541111000042"
}

El alta no crea cuenta recaudadora

POST /v1/associates crea solo la entidad del asociado. Si el asociado necesita cuenta recaudadora propia (modelo B o C), hay que crearla por separado con POST /v1/receivable-accounts. Ver Cómo crear cuentas recaudadoras.

Respuesta

201 Created
Location: /v1/associates/88

{
  "id": 88,
  "type": "DRIVER",
  ...
  "status": "ACTIVE",
  "creationDate": "2026-05-15T10:00:00-03:00"
}

Upsert por taxId

POST /v1/associates también es upsert por la clave (customer, taxId). Si ya existe un asociado activo con ese taxId para el customer, devuelve 200 OK con el existente.

Filtros del listado

GET /v1/associates

Parámetro	Tipo	Descripción
taxId	string	CUIT/CUIL exacto
documentNumber	string	DNI exacto
type	string	Tipo específico
parentAssociateId	int64	Asociados que reportan a uno padre
status	enum	Default ACTIVE
ids	array de int64	Lista de IDs específicos
page, count	int	Paginación

Deshabilitar

DELETE /v1/associates/88

204 No Content

Es soft delete: el asociado queda con status: DISABLED. Sus datos históricos siguen accesibles. Las cuentas recaudadoras vinculadas a este asociado pueden quedar inválidas o requerir reasignación (ver reasignación de operador).

Rehabilitar

POST /v1/associates/88/activations

200 OK
{
  "id": 88,
  "status": "ACTIVE",
  ...
}

Jerarquías de asociados

Para modelos donde unos asociados reportan a otros (ej. un supervisor sobre choferes), usar parentAssociateId:

POST /v1/associates
{
  "type": "DRIVER",
  "name": "Operario",
  "lastName": "100",
  "taxId": "20888888880",
  ...
  "parentAssociateId": 50    // ID del supervisor
}

Listar los subordinados de un supervisor:

GET /v1/associates?parentAssociateId=50

Errores comunes

Escenario	HTTP	code
Asociado duplicado por taxId	200	(upsert, devuelve existente)
taxId con formato inválido	400	validation
Falta algún campo obligatorio	400	validation
Operación sobre asociado DISABLED	422	associate-disabled

Sin alta masiva por ahora

Igual que clients, el alta masiva de asociados se está evaluando para futuras versiones.