Optimistic Locking

The Gesvision API uses optimistic concurrency control to prevent lost updates when multiple clients modify the same resource simultaneously.

This is essential for integrations where the Gesvision web application and the API (or multiple API consumers) may edit the same invoices, orders, or customers.

How it works

Client A reads invoice (version: 3)
Client B reads invoice (version: 3)
Client A updates with If-Match: 3  →  ✅ Success (version becomes 4)
Client B updates with If-Match: 3  →  ❌ 409 Conflict (version is now 4)

1. Every resource has a version field (integer, starts at 0)
2. When updating or deleting, send the current version in the If-Match header
3. If the version matches the server, the operation succeeds and version is incremented
4. If the version doesn't match (another client changed it), you get 409 Conflict

Example: safe update flow

Read the current state

curl https://app.gesvision.com/gesmo/rest/api/v1/invoices/123 \
  -H "Authorization: Bearer $TOKEN"

Note the version field in the response:

{
  "id": 123,
  "version": 3,
  "code": "A-0123",
  "total": 150.00
}

Update with version check

curl -X PUT https://app.gesvision.com/gesmo/rest/api/v1/invoices/123 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "If-Match: 3" \
  -d '{
    "counterpartyId": 55,
    "companyId": 1,
    "branchId": 1,
    "lines": [...]
  }'

Handle the conflict

If another user modified the invoice between your read and update, you'll receive:

{
  "status": 409,
  "error": "Conflict",
  "message": "Row was updated or deleted by another transaction"
}

The recommended recovery strategy:

1. Re-fetch the resource → get the new version and current data
2. Merge your changes with the latest state (decide which fields to keep)
3. Retry with the new version number

Delete with version check

The same mechanism applies to deletions:

curl -X DELETE https://app.gesvision.com/gesmo/rest/api/v1/invoices/123 \
  -H "Authorization: Bearer $TOKEN" \
  -H "If-Match: 4"

When is If-Match optional?

The If-Match header is optional. If omitted, the update or delete proceeds without version checking.

Scenario	Recommendation
Interactive apps (user edits)	Always use If-Match
Automated imports (bulk sync)	Can omit if you control the data flow
Single-writer systems	Can omit if only one system writes

caution

Omitting If-Match in multi-writer scenarios can lead to silent data loss (last writer wins). Always use it when multiple systems or users can edit the same records.