Clientes

Los clientes representan a los clientes finales del customer: empresas, comercios, o personas físicas a quienes el customer factura. En el modelo educativo, los alumnos también se modelan como clientes (ver modelos de operación).

Modelo

{
  "id": 1042,
  "businessName": "Kiosco Central",
  "taxId": "30998888887",
  "documentType": "CUIT",
  "email": "[email protected]",
  "branchExternalCode": null,
  "branchDescription": null,
  "branchReferenceAddress": null,
  "externalId": "ERP-CLI-12345"
}

Campo	Tipo	Requerido	Descripción
id	int64	(response)	ID asignado por Max Pay
businessName	string	Sí	Razón social o nombre completo
taxId	string	Sí	CUIT/CUIL, 11 dígitos sin guiones
documentType	enum	Sí	CUIT o CUIL
email	string	No	Email de contacto del cliente
branchExternalCode	string	Solo si tiene sucursal	Código identificador de sucursal
branchDescription	string	Solo si tiene sucursal	Descripción de la sucursal
branchReferenceAddress	string	Solo si tiene sucursal	Dirección de la sucursal
externalId	string	No	ID del cliente en el ERP del integrador

Sucursales

Un cliente con varias sucursales se modela como una fila por sucursal, con el mismo taxId y distinto branchExternalCode. Cada sucursal es un cliente separado a efectos de comprobantes y cuentas recaudadoras.

Ejemplo: BebidasPyme S.R.L. con 3 sucursales:

// Las 3 filas comparten taxId, varían en branchExternalCode
[
  { id: 1101, businessName: "BebidasPyme S.R.L.", taxId: "30997777776", branchExternalCode: "01", branchDescription: "Centro"   },
  { id: 1102, businessName: "BebidasPyme S.R.L.", taxId: "30997777776", branchExternalCode: "02", branchDescription: "Norte"    },
  { id: 1103, businessName: "BebidasPyme S.R.L.", taxId: "30997777776", branchExternalCode: "03", branchDescription: "Belgrano" }
]

Para listar todas las sucursales de un mismo CUIT:

GET /v1/clients?taxId=30997777776

Endpoints

Método	Path	Descripción
GET	/v1/clients	Lista con filtros
POST	/v1/clients	Crea (upsert por taxId + branch)
GET	/v1/clients/{id}	Detalle
PUT	/v1/clients/{id}	Actualiza
GET	/v1/clients/{id}/receivable-accounts	Cuentas recaudadoras del cliente
GET	/v1/clients/{id}/associates	Asociados que comparten cuentas recaudadoras con este cliente (derivado)

POST es upsert

POST /v1/clients tiene comportamiento upsert por la clave de unicidad (customer, documentType, documentNumber, branchExternalCode). Si el cliente ya existe con esa combinación, devuelve 200 OK con el cliente existente (no 201 Created). Esto permite hacer sincronización inicial idempotente sin manejar errores de duplicado.

POST /v1/clients
Idempotency-Key: erp-cli-12345
Content-Type: application/json

{
  "businessName": "Kiosco Central",
  "taxId": "30998888887",
  "documentType": "CUIT",
  "email": "[email protected]",
  "externalId": "ERP-CLI-12345"
}

Status	Significa
201 Created	Cliente creado por primera vez
200 OK	Cliente ya existía y se devuelve tal cual está en el sistema

Filtros de búsqueda

GET /v1/clients

Parámetro	Tipo	Descripción
customerId	int64	(no aplica vía API pública — el customer es implícito)
taxId	string	CUIT/CUIL exacto, 11 dígitos sin guiones
branchExternalCode	string	Código de sucursal
ids	array de int64	Lista de IDs específicos
externalId	string	ID del integrador
page, count	int	Paginación

Actualización

PUT /v1/clients/1042
Content-Type: application/json

{
  "businessName": "Kiosco Central S.R.L.",
  "email": "[email protected]",
  "taxId": "30998888887",
  "documentType": "CUIT"
}

No se puede modificar taxId, documentType ni branchExternalCode (son parte de la identidad del cliente). Para "renombrar" un cliente con CUIT distinto, hay que crear uno nuevo.

Errores comunes

Escenario	HTTP	code
taxId con formato inválido	400	validation
Cliente con sucursal sin branchDescription o branchReferenceAddress	422	incomplete-branch
Cliente sin sucursal con branchExternalCode setteado	422	incomplete-branch
documentType no soportado	400	validation

Sin alta masiva por ahora

El alta masiva de clientes no está expuesta por el momento; la exposición pública se está evaluando para futuras versiones. Si tu integración requiere alta masiva de clientes (más de 50 por día), contactá a tu account manager para evaluar opciones.

Para alta masiva de cuentas recaudadoras vinculadas a clientes ya existentes, ver Alta masiva de receivable-accounts.