Kiipu · invoicing v1 read-only
kiipu.
Reads what is owed: the outstanding total, what is overdue by age bucket, the 15 clients who owe the most with their overdue amount and since when, and the next installments due. Changes nothing and contacts no one.
Last updated
POST /api/v1/reads/kiipu.collections_get- Token scope
kiipu.collections_get@1- Workspace permission
api.kiipu.collections_getoff by default- Who reads
- The person behind the token, with their role. Someone who leaves the workspace stops reading.
Three permissions
A token with that scope, the workspace owner having switched the read on, and the person's role seeing it in the product. None of them is enough alone. OAuth only →
Request
No fields.
Response — output when status is done
| field | type | rules | |
|---|---|---|---|
currency | string | required | |
outstandingTotal | string | required | ^-?\d+\.\d{2}$ |
openInvoices | integer | required | ≥ 0 |
overdueTotal | string | required | ^-?\d+\.\d{2}$ |
agingBuckets | object[] | required | |
debtors | object[] | required | |
upcoming | object[] | required | |
incomplete | boolean | required |
agingBuckets[]
| field | type | rules | |
|---|---|---|---|
bucket | "d1_30" | "d31_60" | "d61_90" | "d90_plus" | required | |
amount | string | required | ^-?\d+\.\d{2}$ |
installments | integer | required | ≥ 0 |
clients | integer | required | ≥ 0 |
debtors[]
| field | type | rules | |
|---|---|---|---|
client | string | null | required | |
overdue | string | required | ^-?\d+\.\d{2}$ |
oldestDueOn | string | required | ^\d{4}-\d{2}-\d{2}$ |
daysOverdue | integer | required | ≥ 0 |
bucket | "d1_30" | "d31_60" | "d61_90" | "d90_plus" | required | |
invoices | integer | required | ≥ 0 |
upcoming[]
| field | type | rules | |
|---|---|---|---|
client | string | null | required | |
invoice | string | null | required | |
dueOn | string | required | ^\d{4}-\d{2}-\d{2}$ |
amount | string | required | ^-?\d+\.\d{2}$ |
Example
# 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.collections_get \
-H "Authorization: Bearer $NIIKO_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{}'
# 200 → done · 4xx → refused, with a named reasonWhy it may refuse
Each reason names who can fix it and how; detail.message, when present, says what to do. Refusals & HTTP codes →
invalid_inputrole_forbiddengrant_offreads_need_a_person
In the clients
| @vorluno/niiko-sdk | niiko.getCollections() |
| niiko (Python) | niiko.get_collections() from 0.3.0 · not on the registry yet |
| niiko-cli | niiko read kiipu.collections_get |
| n8n-nodes-niiko | No reads: the node holds a key, and reading needs a person through OAuth. |
| niiko-mcp-server | kiipu_collections_get readOnlyHint |
History
- The SDKs and the CLI read
@vorluno/niiko-sdk,niikoandniiko-cli0.3.0 take an OAuth access token (accessToken,access_token=,niiko login --token) and have one read-only method per read:getCollections(),get_collections(),niiko read kiipu.collections_get. A read has two outcomes, done or refused, and takes no idempotency key. - Declared reads, OAuth only
POST /api/v1/reads/{id}answers nine declared reads — what is owed, what was collected, the agenda, the funnel, the month — never raw tables and never text someone wrote. Only with an OAuth token, on behalf of a person and with their role (an API key getsreads_need_a_person); each read has its own workspace switch, off by default. The MCP server lists them as read-only tools.