update_statements_status - Qobra public API documentation

Lock, unlock, pay or unpay statements, and request their validation when locking. Locking freezes a statement’s amounts, the step before it can be approved and paid. Paying marks a locked statement as sent to payroll, and unpaying cancels that payment. Pass the statement ids list_statements returns, at most 50 per call. Only statements you can see can be changed. Each statement sent gets one row saying what happened to it:

Changed: locked, locked_and_validation_requested, validation_requested, unlocked, paid or unpaid.
Skipped, with the reason in reason: already locked, paid, in error, still being calculated, or a validation already requested.
Failed on Qobra’s side, in which case it may be changed in part. reason says what to do.

A row may carry a warning, such as the previous period of that user left unlocked. Sending a state already there skips the statement, so you can send the same call again. Unlocking is destructive. Qobra recalculates the statement’s amounts. For a company that has validation workflows, Qobra also clears the statement’s validation workflow with every approval already given, even while the module is switched off in the settings. A paid statement cannot be unlocked: unpay it first. Paying needs a locked statement with no calculation error, and none of its validation workflow’s mandatory stages still awaiting approval. Paying is an outbound action. Qobra notifies the owner of each statement paid and, where the company has a live payroll webhook, sends the statement to it, as from the web app. No payment date is recorded. To approve the stages a payment waits on, use approve_statements. Unpaying cancels the payment in Qobra only: it recalls nothing already sent to payroll, and leaves the statement locked. It refuses a statement whose last validation is not its payment. To request a validation, pass validation_workflow_template_id with lock. Read the template ids with list_validation_workflow_templates. A statement still open is locked first when your role may lock; one already locked gets the workflow only. Qobra assigns the template’s workflow and notifies its approvers, as the web app does. The whole call is refused before anything changes when one id names no statement you can see, or when the validation workflow is switched off and a template is passed. Each statement changes in the environment it lives in. Locking and unlocking require the lock permission on statements. Paying and unpaying require the payment permission. Requesting a validation on a statement already locked requires only the permission to request one. Available only where the Qobra write tools beta is enabled. Every write to the live environment is recorded in the audit trail as the Qobra MCP agent; writes to a sandbox are not audited.

Parameters

Body

string[]

required

Ids of the statements to change — the ids list_statements returns. At most 50 per call.

string

required

lock freezes the statements’ amounts, the step before they can be approved and paid. unlock reopens locked statements. pay marks locked statements as sent to payroll. unpay cancels that payment, leaving them locked. One of: lock, unlock, pay, unpay.

string

With lock only: the id of the validation workflow to request on each statement, one of list_validation_workflow_templates’ ids. A statement still open is locked first when your role may lock; one already locked gets the workflow only. Omit it to lock without requesting a validation.

Example

Lock two statements and request their validation:

{
  "statement_ids": ["66a0b1c2d3e4f50012345678", "66a0b1c2d3e4f50012345679"],
  "action": "lock",
  "validation_workflow_template_id": "66a0b1c2d3e4f50012349999"
}

Mark locked statements as paid:

{
  "statement_ids": ["66a0b1c2d3e4f50012345678"],
  "action": "pay"
}

Response

Body

object[]

One row per statement, in the order first sent: an id sent twice is changed and reported once.

Show object properties

string

Deep link to open this statement in the Qobra web app.

object

Show object properties

string

What the call did to this statement:

locked: locked, its amounts frozen.
locked_and_validation_requested: locked, then the validation workflow of the template was assigned.
validation_requested: already locked, the workflow was assigned.
unlocked: unlocked, and its calculation relaunched.
paid: marked as sent to payroll.
unpaid: its payment cancelled, still locked.
skipped: left as it was, reason says why.
failed: an error on our side interrupted it, so it may be changed in part; reason says what to do. One of: locked, locked_and_validation_requested, validation_requested, unlocked, paid, unpaid, skipped, failed.

string

Why the statement was skipped or failed; null otherwise.

string

Something to tell the user about a statement that did change, such as an earlier period of theirs left unlocked; null when there is nothing to flag.

string

After the call. What the statement’s payment is waiting on:

blocked_by_error: a calculation error blocks locking and payment until it is fixed.
awaiting_lock: still open, its amounts can change; a statement is locked before it can be paid.
awaiting_approval: locked, but a mandatory stage of its validation workflow is still waiting on an approver (see validation_workflow.blocking_stage).
awaiting_payroll: locked and nothing blocks it, not yet sent to payroll.
paid: sent to payroll. One of: blocked_by_error, awaiting_lock, awaiting_approval, awaiting_payroll, paid.

object[]

After the call, the approvers whose turn it is. Empty when nothing awaits an approval.

Show object properties

object

Show object properties

string

When they were last reminded to approve; null if never.

​Parameters

​Example

​Response

Parameters

Example

Response