Kiipu · facturación v1 solo lectura
kiipu.
Lista las últimas facturas y pagos de UN cliente dicho por su nombre: número, estado, total, saldo, y cuándo y cómo pagó. Con varios que coinciden se niega con ambiguous y los candidatos; sin ninguno, not_found.
Última actualización
POST /api/v1/reads/kiipu.client_invoices_list- Alcance del token
kiipu.client_invoices_list@1- Permiso del workspace
api.kiipu.client_invoices_listapagado 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 | |
owedTotal | string | obligatorio | ^-?\d+\.\d{2}$ |
invoices | object[] | obligatorio | |
payments | object[] | obligatorio |
invoices[]
| campo | tipo | reglas | |
|---|---|---|---|
number | string | null | obligatorio | |
status | string | obligatorio | |
total | string | obligatorio | ^-?\d+\.\d{2}$ |
balance | string | obligatorio | ^-?\d+\.\d{2}$ |
currency | string | obligatorio | |
createdOn | string | obligatorio | ^\d{4}-\d{2}-\d{2}$ |
dueOn | string | null | obligatorio | |
daysOverdue | integer | null | obligatorio |
payments[]
| campo | tipo | reglas | |
|---|---|---|---|
invoice | string | null | obligatorio | |
paidOn | string | obligatorio | ^\d{4}-\d{2}-\d{2}$ |
amount | string | obligatorio | ^-?\d+\.\d{2}$ |
method | string | obligatorio | |
reversed | boolean | obligatorio |
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_invoices_list \
-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.listClientInvoices() |
| niiko (Python) | niiko.list_client_invoices() desde 0.3.0 · aún no está en el registro |
| niiko-cli | niiko read kiipu.client_invoices_list |
| n8n-nodes-niiko | Sin lecturas: el nodo lleva una llave, y leer pide una persona por OAuth. |
| niiko-mcp-server | kiipu_client_invoices_list readOnlyHint |
Historial
- Los SDK y la CLI leen
@vorluno/niiko-sdk,niikoyniiko-cli0.3.0 aceptan un token de acceso OAuth (accessToken,access_token=,niiko login --token) y tienen un método de solo lectura por lectura:getCollections(),get_collections(),niiko read kiipu.collections_get. Una lectura tiene dos desenlaces, hecha o negada, y no lleva clave de idempotencia. - Lecturas declaradas, solo con OAuth
POST /api/v1/reads/{id}contesta nueve lecturas declaradas —lo que se debe, lo cobrado, la agenda, el embudo, el mes—, nunca tablas ni texto que alguien escribió. Solo con un token OAuth, en nombre de una persona y con su rol (una llave de API recibereads_need_a_person); cada lectura tiene su interruptor en el workspace, apagado por defecto. El servidor MCP las lista como herramientas de solo lectura.