Kiipu · invoicing v1 current
kiipu.
Leaves in the Kiipu approval queue the notice that a client (by name) paid a given amount of an open invoice. Does NOT apply the payment and touches no balances: a person checks it against the bank and applies it. If the client has several open invoices the number must be given.
Last updated
POST /api/v1/actions/kiipu.payment_reported- Key scope
kiipu.payment_reported@1- Workspace permission
api.kiipu.payment_reportedoff by default
Two permissions, not one
Both are needed: a key with that scope, and the workspace owner having switched the permission on. Holding the key is not enough — they are two decisions made by different people.
Request
| field | type | rules | |
|---|---|---|---|
client | string | required | min 1 · max 200 |
amountUsd | string | required | ^\d+(\.\d{1,2})?$ |
invoice | string | optional | min 1 · max 40 |
Response — output when status is done
| field | type | rules | |
|---|---|---|---|
submissionId | string | required | |
clientId | string | required | |
clientName | string | required | |
invoiceId | string | required | |
invoiceNumber | string | required | |
outstandingUsd | string | required | |
declaredUsd | string | required | |
status | "received" | required | |
reviewAt | "/kiipu/aprobaciones" | required |
Example
# One request, one idempotency key: retrying with the same key never runs twice.
curl -X POST https://niiko.org/api/v1/actions/kiipu.payment_reported \
-H "Authorization: Bearer nk_…" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"client": "…",
"amountUsd": "1"
}'
# 200 → done · 202 → pending_approval (a person signs later) · 4xx → refused, with a named reasonWhy it may refuse
Each reason names who can fix it and how. With reason stale, detail.message says what to do.
cliente_no_encontradocliente_ambiguodemasiados_clientessin_factura_abiertavarias_facturasfactura_no_encontradasin_permiso
In the clients
| @vorluno/niiko-sdk | niiko.reportedPayment() |
| niiko (Python) | niiko.reported_payment() |
| niiko-cli | niiko run kiipu.payment_reported |
| n8n-nodes-niiko | kiipuPaymentReported |
| niiko-mcp-server | kiipu_payment_reported |