Kiipu · facturación v1 vigente

`kiipu.payment_reported`

Deja en la cola de aprobación de Kiipu el aviso de que un cliente (por su nombre) pagó cierto monto de una factura abierta. NO aplica el pago ni toca saldos: una persona lo revisa contra el banco y lo aplica. Si el cliente tiene varias facturas abiertas hay que decir el número.

Última actualización11 sept 2026

POST /api/v1/actions/kiipu.payment_reported

Alcance de la llave: kiipu.payment_reported@1
Permiso del workspace: api.kiipu.payment_reported apagado 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
`amountUsd`	string	obligatorio	`^\d+(\.\d{1,2})?$`
`invoice`	string	opcional	min 1 · max 40

Respuesta — output cuando status es done

campo	tipo
`submissionId`	string	obligatorio
`clientId`	string	obligatorio
`clientName`	string	obligatorio
`invoiceId`	string	obligatorio
`invoiceNumber`	string	obligatorio
`outstandingUsd`	string	obligatorio
`declaredUsd`	string	obligatorio
`status`	"received"	obligatorio
`reviewAt`	"/kiipu/aprobaciones"	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.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 reason

Por 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_factura_abiertavarias_facturasfactura_no_encontradasin_permiso

En los clientes

@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`

Historial

Kiipu: anular un borrador, reportar un pagokiipu.draft_voided anula una factura en borrador (nunca una emitida). kiipu.payment_reported deja un aviso de pago en la cola de aprobación; una persona lo aplica.11 sept 2026