Kiipu · facturación v1 solo lectura
kiipu.
Lee cuánto debe en total UN cliente dicho por su nombre, según el libro, y su próxima cuota. Un cliente al que nunca se le facturó vuelve como never_invoiced, nunca como al día; un lead o un cliente perdido, como not_a_client. Con varios que coinciden se niega con ambiguous; sin ninguno, not_found.
Última actualización
POST /api/v1/reads/kiipu.client_balance_get- Alcance del token
kiipu.client_balance_get@1- Permiso del workspace
api.kiipu.client_balance_getapagado por defecto- Quién lee
- La persona detrás del token, con su rol. Quien deja el workspace deja de leer.
Tres permisos
Un token con ese alcance, que el dueño del workspace haya encendido la lectura, y que el rol de la persona la vea en el producto. Ninguna basta sola. Solo con OAuth →
Petición
| campo | tipo | reglas | |
|---|---|---|---|
client | string | obligatorio | min 1 · max 200 |
Respuesta — output cuando status es done
| campo | tipo | reglas | |
|---|---|---|---|
client | string | obligatorio | |
standing | "owes" | "up_to_date" | "never_invoiced" | "not_a_client" | obligatorio | |
outstandingTotal | string | null | obligatorio | |
currency | string | null | obligatorio | |
nextInstallment | object | null | obligatorio |
nextInstallment
| campo | tipo | reglas | |
|---|---|---|---|
dueOn | string | obligatorio | ^\d{4}-\d{2}-\d{2}$ |
amount | string | obligatorio | ^-?\d+\.\d{2}$ |
Ejemplo
# Reads take an OAuth access token, not an API key, and no idempotency key: reading changes nothing.
curl -X POST https://niiko.org/api/v1/reads/kiipu.client_balance_get \
-H "Authorization: Bearer $NIIKO_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"client": "…"
}'
# 200 → done · 4xx → refused, with a named reasonPor qué puede negarse
Cada motivo dice quién puede arreglarlo y cómo; detail.message, cuando viene, dice qué hacer. Negativas y códigos HTTP →
invalid_inputrole_forbiddengrant_offreads_need_a_personambiguousnot_found
En los clientes
| @vorluno/niiko-sdk | niiko.getClientBalance() |
| niiko (Python) | niiko.get_client_balance() desde 0.4.0 · aún no está en el registro |
| niiko-cli | niiko read kiipu.client_balance_get |
| n8n-nodes-niiko | Sin lecturas: el nodo lleva una llave, y leer pide una persona por OAuth. |
| niiko-mcp-server | kiipu_client_balance_get readOnlyHint |