A locked record cannot be modified — changes are only possible after unlocking. Via the REST API, locking and unlocking is done through actions in the action attribute, either on a single record or in batch over a group of records.

Lock states

The lock state is visible in the zamekK property. This is read-only — it is set exclusively by the corresponding action.

`zamekK` value	Description	Set by action
`zamek.otevreno`	Open	`unlock`
`zamek.prohlednuto`	Viewed	none of the locking actions
`zamek.polozamceno`	Locked outside of accounting	`lock-for-ucetni`
`zamek.zamceno`	Locked	`lock`

🚨 The zamekK property specified in an import is silently ignored — the import completes successfully, but the lock state does not change. Always set the lock via an action, never by importing the property.

Locking a record

The lock action is used to lock a record:

<?xml version="1.0"?>
<winstrom version="1.0">
  <faktura-vydana action="lock">
    <id>1</id>
  </faktura-vydana>
</winstrom>

The record ends up in the zamek.zamceno state. Calling the action again on an already locked record does not raise an error.

Locking outside of accounting

The lock-for-ucetni action sets the record to the zamek.polozamceno state, i.e. Locked outside of accounting:

<?xml version="1.0"?>
<winstrom version="1.0">
  <faktura-vydana action="lock-for-ucetni">
    <id>1</id>
  </faktura-vydana>
</winstrom>

Unlocking a record

The unlock action is used to unlock a record. It returns the record to the zamek.otevreno state from either of the two locked states:

<?xml version="1.0"?>
<winstrom version="1.0">
  <faktura-vydana action="unlock">
    <id>1</id>
  </faktura-vydana>
</winstrom>

Batch locking and unlocking

The action can also be invoked on a group of records. Instead of the id element, use the filter attribute with a filter:

<?xml version="1.0"?>
<winstrom version="1.0">
  <faktura-vydana action="lock" filter="stavUhrK = 'stavUhr.uhrazeno' and typDokl = 'code:INTERNET'"></faktura-vydana>
</winstrom>

In the return values, updated contains the number of processed records, and results contains their IDs. A filter that finds nothing returns success and a updated equal to zero — always read the actual number of locked documents from updated.

⚠️ Before running the batch, verify the same filter with a plain GET query on the given evidence. A filter with a nonexistent property will fail with the 400 error and the message Property … does not exist, but a filter written differently than you intended will lock documents you did not want to lock as well.

An import with the ?dry-run=true parameter only checks the input without changing the lock, so it can be used to do a dry-run validation of the batch.

Evidences where locking works

The lock, lock-for-ucetni, and unlock actions are available on document evidences:

Area	Evidence
Invoices and other receivables and payables	`faktura-vydana`, `faktura-prijata`, `pohledavka`, `zavazek`
Sales documents	`objednavka-prijata`, `objednavka-vydana`, `nabidka-vydana`, `poptavka-prijata`
Cash and internal documents	`banka`, `pokladni-pohyb`, `interni-doklad`
Warehouse	`skladovy-pohyb`

Code lists and other non-document evidences — for example adresar, cenik, smlouva, or zakazka — cannot be locked. Attempting to do so will fail with the importXmlActionNotSupported error and a message listing the actions allowed on that evidence.

Error states

Error code	Cause
`importXmlJeZamceno`	The import attempted to change a locked record. This applies to both locked states — the record must first be unlocked.
`importXmlActionNotSupported`	The `action` attribute contains an action that the given evidence does not support, or there is an error in the action name.

Both errors return 400 and the entire import is not performed.

ℹ️ Only a user with the Right to lock documents and periods permission (the pravoZamykat property in the uzivatel evidence) can lock documents.

Locking and Unlocking Records