Buscar cuenta por CUIT del cliente
Cuando el ERP necesita emitir un comprobante y solo conoce el CUIT del cliente final, necesita resolver primero la receivableAccountId correspondiente.
El objetivo del flujo es, dado un CUIT, encontrar la(s) cuenta(s) recaudadora(s) candidata(s) sobre la(s) que cobrar.
Endpoint
Es el listado general filtrado por clientTaxId (y opcionalmente branchExternalCode):
GET /v1/receivable-accounts?clientTaxId=30998888887&branchExternalCode=01
| Parámetro | Tipo | Descripción |
|---|---|---|
clientTaxId | string | CUIT/CUIL del cliente, 11 dígitos sin guiones |
branchExternalCode | string | Opcional, si el cliente tiene sucursales |
status | enum | Default ACTIVE |
expand | string | owner para incluir displayName |
Casos de respuesta
Match único
El caso ideal. X-Total-Count: 1 y un único item:
200 OK
X-Total-Count: 1
Content-Type: application/json
[
{
"id": 4242,
"cvu": "0000000099887766554433",
"alias": "distribuidora.demo.kiosco.central",
"currencyCode": "ARS",
"status": "ACTIVE",
"owner": { "type": "CLIENT", "id": 1042 },
"stats": { ... }
}
]
Múltiples matches
El cliente tiene varias sucursales o varios patrones operativos. X-Total-Count > 1. El ERP debe elegir:
200 OK
X-Total-Count: 3
[
{ "id": 4242, "owner": { "type": "CLIENT", "id": 1042 }, ... },
{ "id": 4250, "owner": { "type": "CLIENT_AND_ASSOCIATE", "clientId": 1043, "associateId": 88 }, ... },
{ "id": 4251, "owner": { "type": "CLIENT_AND_ASSOCIATE", "clientId": 1043, "associateId": 89 }, ... }
]
Pasando expand=owner se devuelve el displayName y taxId del owner en cada candidato, para mostrar al usuario un selector si el ERP tiene UI:
GET /v1/receivable-accounts?clientTaxId=30998888887&expand=owner
[
{
"id": 4250,
"owner": {
"type": "CLIENT_AND_ASSOCIATE",
"clientId": 1043,
"associateId": 88,
"client": { "displayName": "Kiosco Central - Suc Centro", "taxId": "30998888887", "branchExternalCode": "01" },
"associate": { "displayName": "Operario 042", "taxId": "20999999999" }
},
...
},
...
]
Sin matches
X-Total-Count: 0, status 204 No Content (sin body).
Para distinguir "el cliente no existe" vs "el cliente existe pero no tiene cuenta recaudadora", hacé un GET /v1/clients?taxId=... adicional.