Kiipu · facturación v1 vigente
kiipu.
Deja preparada una factura como BORRADOR para un cliente dicho por su nombre, con sus líneas e impuestos. NO la emite, NO la numera y NO cuenta como deuda: una persona la revisa y la emite en Kiipu. No crea el cliente si no existe.
Última actualización
POST /api/v1/actions/kiipu.invoice_proposed- Alcance de la llave
kiipu.invoice_proposed@1- Permiso del workspace
api.kiipu.invoice_proposedapagado por defecto
Dos permisos, no uno
Hacen falta las dos cosas: una llave con ese alcance, y que el dueño del workspace haya encendido el permiso. Tener la llave no basta — son dos decisiones de personas distintas.
Petición
| campo | tipo | reglas | |
|---|---|---|---|
client | string | obligatorio | min 1 · max 200 |
lines | object[] | obligatorio | |
dueAt | string (date-time) | opcional | |
series | string | opcional | ^[A-Za-z0-9-]{1,12}$ |
lines[]
| campo | tipo | reglas | |
|---|---|---|---|
concept | string | obligatorio | min 1 · max 500 |
quantity | string | obligatorio | ^(?:0*[1-9]\d*(?:\.\d{1,3})?|0+\.(?:[1-9]\d{0,2}|0[1-9]\d?|00[1-9]))$ |
unitPriceUsd | string | obligatorio | ^\d+(\.\d{1,2})?$ |
tax | "exempt" | "itbms_7" | "itbms_10" | "itbms_15" | opcional | = "exempt" |
Respuesta — output cuando status es done
| campo | tipo | reglas | |
|---|---|---|---|
invoiceId | string | obligatorio | |
clientId | string | obligatorio | |
clientName | string | obligatorio | |
status | "draft" | obligatorio | |
subtotalUsd | string | obligatorio | |
taxUsd | string | obligatorio | |
totalUsd | string | obligatorio | |
dueAt | string | obligatorio | |
series | string | obligatorio | |
issueAt | "/kiipu/facturas" | obligatorio |
Ejemplo
# One request, one idempotency key: retrying with the same key never runs twice.
curl -X POST https://niiko.org/api/v1/actions/kiipu.invoice_proposed \
-H "Authorization: Bearer nk_…" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"client": "…",
"lines": [
{
"concept": "…",
"quantity": "1",
"unitPriceUsd": "1"
}
]
}'
# 200 → done · 202 → pending_approval (a person signs later) · 4xx → refused, with a named reasonPor qué puede negarse
Cada motivo dice quién puede arreglarlo y cómo. Con motivo stale, detail.message dice qué hacer.
cliente_no_encontradocliente_ambiguodemasiados_clientessin_permiso
En los clientes
| @vorluno/niiko-sdk | niiko.proposedInvoice() |
| niiko (Python) | niiko.proposed_invoice() |
| niiko-cli | niiko run kiipu.invoice_proposed |
| n8n-nodes-niiko | kiipuInvoiceProposed |
| niiko-mcp-server | kiipu_invoice_proposed |