Lock a proforma's content
Freezes the proforma’s content by stamping locked_at. This
is not a lifecycle transition: status is unchanged, and lock
travels its own axis — read it from
status_transitions.locked_at, not from status.
Idempotent. Calling it on an already-locked proforma returns 200 with the unchanged document and writes nothing.
Locking also happens on its own at the first accounting effect (a payment lands, or the document is transmitted), so a paid proforma is normally already locked before any client calls this.
Required scope: manage:proformas.
Authentication
JWT issued via POST /api/v1/auth/sign_in. Used by mobile and SPA clients. Revoked tokens are rejected.
Lucanto API key. Two prefixes:
lct_pat_<random><checksum>— personal access token (owner: User)lct_live_<random><checksum>— workspace token, live data
Issue keys at /settings/api_keys (personal) or
/:workspace_id/settings/api_keys (workspace). Plaintext token is
shown once and never again.
Path parameters
Proforma ID. Either the numeric id or the public_id (doc_…).
Headers
Client-supplied unique key (recommended: UUID v4) for safe
retries. Within 24 hours, repeating the same key with the same
request (method, path, query, body) replays the original
response instead of re-executing the action — once the action
has run, a 5xx included; a request stopped before it ran is not
stored. Reusing
a key with a different request returns
422 idempotency_key_conflict (IETF draft §2.7).
Response
OK. The proforma with status_transitions.locked_at set.
status is unchanged.
Stable public identifier of this record. Never changes once assigned.
Its prefix names the entity: doc_ document (invoice, proforma, credit
note, quote, sales order), exp_ expense, cnt_ contact, prj_
project, ba_ bank account or cash register, txn_ transaction,
lon_ loan, bst_ bank statement. Accepted in place of the numeric
id in this resource’s path parameters and in request fields that
reference it (customer_id, bank_account_id, …).
Proforma lifecycle state. Settlement degree is reported
separately by payment_status; settled is the explicit
lifecycle state after downstream settlement handling.
reopened is where
reopenProforma lands a
previously locked proforma; it is editable again and must be
re-issued.
Derived settlement degree (money is the source of truth). Null for non-payable document types, drafts, canceled documents, and rows created before the payment_status backfill ran.
Tax scheme (UNCL 5153), e.g. “VAT”.
Delivery/carrier mode
What happens when a payment lands on this proforma: regular_invoice_paid
(delivered at payment: one paid invoice for a payment that covers it,
a tax document for a part-payment), tax_document (a tax document for
every payment), nothing, or the legacy regular_invoice. NULL on
older proformas, read as nothing. When converting via
/convert_to_invoice, this value is overridden to
regular_invoice regardless of the stored setting.
Amount settled so far (payments + advance deductions).
Outstanding amount (tax_inclusive − amount_paid).
Origin of the document. null when it was created in Lucanto, in which case totals are Lucanto’s EN 16931 calculation. A non-null value means the document was imported from that system and initially carries the source system’s own figures, preserved verbatim; those may differ by cents from Lucanto’s calculation because systems round VAT at different levels (line vs. category). insight means AI extraction from an uploaded file, not an import from another vendor. This records provenance only, not which calculation is currently in effect — editing line items or document discounts recomputes totals in Lucanto while leaving import_source set. In practice a document only ever carries kros_developer, isdoc, superfaktura or null. kros appears only on rows imported before the writer was renamed, and insight is written by the expense path only. The enum is kept as the union across resources rather than narrowed, so a legacy row cannot fail validation.
The party identity as it appears on a document. On an ISSUED document this is the identity the document was issued with — a snapshot pinned at issue, which does NOT change when the legal entity is later renamed, re-registered, or moved. A draft follows the entity’s current identity. id is the legal entity’s id and is stable across identity changes, so a stored reference keeps resolving. This matches the PDF and the ISDOC export of the same document. vat_period is not part of this projection — a counterparty’s filing period is not knowable.
The party identity as it appears on a document. On an ISSUED document this is the identity the document was issued with — a snapshot pinned at issue, which does NOT change when the legal entity is later renamed, re-registered, or moved. A draft follows the entity’s current identity. id is the legal entity’s id and is stable across identity changes, so a stored reference keeps resolving. This matches the PDF and the ISDOC export of the same document. vat_period is not part of this projection — a counterparty’s filing period is not knowable.
