Kiipu · invoicing v1 read-only
kiipu.
Reads how much was collected this month so far (as the ledger recorded it), the same stretch of last month to compare, and what is still outstanding. Does not say who owes: that is kiipu.collections_get.
Last updated
POST /api/v1/reads/kiipu.collected_month_get- Token scope
kiipu.collected_month_get@1- Workspace permission
api.kiipu.collected_month_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 | |
collectedThisMonth | string | required | ^-?\d+\.\d{2}$ |
periodStart | string | required | ^\d{4}-\d{2}-\d{2}$ |
periodEnd | string | required | ^\d{4}-\d{2}-\d{2}$ |
collectedSamePeriodLastMonth | string | required | ^-?\d+\.\d{2}$ |
outstandingTotal | string | required | ^-?\d+\.\d{2}$ |
openInvoices | integer | required | ≥ 0 |
incomplete | boolean | required |
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.collected_month_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.getCollectedMonth() |
| niiko (Python) | niiko.get_collected_month() from 0.3.0 · not on the registry yet |
| niiko-cli | niiko read kiipu.collected_month_get |
| n8n-nodes-niiko | No reads: the node holds a key, and reading needs a person through OAuth. |
| niiko-mcp-server | kiipu_collected_month_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.