# ConnectCloud Workflow API (v1.0.0)

Approval workflows: blueprints, the tasks of a person, running instances and the tenant's workflow configuration.

Base URLs:

- Production: `https://api.mbcom.cloud/api/workflow/v1`
- Staging: `https://api.mbcom.cloud/api/workflow/v1`
- Sandbox: `https://developers.mbcom.cloud/sandbox/workflow`

Workflow runs approval and review processes ("Workflows") on the tenant's trade transactions
(offers, orders, incoming invoices, …). A tenant describes each process as a **blueprint**; the
service starts an **instance** of it for every matching transaction, routes it through user and
system steps and writes the outcome back to trade.

## Model
- **Blueprints** (`WorkflowBlueprint`) are tenant configuration, identified by a free `id`. The
  **trigger** names the object type (`transaction`), the trade transaction types
  (`transactionTypes`, e.g. `INBOUND_INVOICE`) and statuses (`statuses`, e.g. `IN_REVIEW`) it starts
  on, an optional start `condition` and the first step (`trigger.nextStep.step`, else the first
  step of `steps`). Only an **active** blueprint starts workflows (`active` missing means active);
  switching it off never touches running instances. If the tenant has no blueprint of that id,
  reading falls back to a platform template of the same id.
- **Steps** are `UserStep`s (a person decides) or `SystemStep`s (the engine decides). A user step is
  assigned to an HR group (`group`, an HR group UUID, required) and optionally a person (`user`,
  e-mail); it shows `fields` (trade field names as listed by `GET /blueprints/fields`, line fields
  as `lines.<field>`, everything else is a workflow-local input field) and offers its `nextSteps` as
  buttons. A system step follows the first `nextSteps` entry whose `condition` (an
  [expr](https://expr-lang.org) expression over the transaction data) holds, else the one with
  `condition: default`. A step without a next step ends the instance: `APPROVED` when its `action`
  is `approve` (also `freigeben`, `freigabe`, `genehmigen`, `genehmigt`), `REJECTED` for `reject`
  (also `ablehnen`, `abgelehnt`, `ablehnung`), otherwise `COMPLETED`.
- **Instances** (`WorkflowInstance`) keep a snapshot of the blueprint they started with, the
  transaction data at start (`data`) and an append-only `history`. States:
  `OPEN` (running), `RETRYING_SYNC` (waiting for trade: the start or the status write-back is retried
  automatically, read-only meanwhile), and the end states `APPROVED`, `REJECTED`, `COMPLETED`,
  `CANCELLED`, `TRIGGER_NOT_MATCHED` (start condition false), `TECHNICALLY_FAILED` (invalid blueprint at
  start). At most one active instance exists per transaction and blueprint.
- **Tasks** are the open user steps of instances. A task is assigned to the caller when the step's
  `user` is the caller's e-mail or the caller is a member of the step's HR group (personal API keys
  act for their owner with the owner's groups; service accounts have no groups and are assigned
  nothing). A person **claims** a task to work on it (completing an unclaimed task claims it);
  claims and open inquiries are released automatically after 24 hours.
- **Inquiries** (`Rückfrage`): in a step with `allowInquiry`, the assignee can ask another person
  (`inquiry_to`, see `GET /users`) a question; until it is answered or pulled back, only the
  recipient may answer and the sender may only pull it back.
- **Trade write-back:** while an instance is `OPEN` or `RETRYING_SYNC`, trade locks its transaction
  against other changes (trade answers `423`). A user step may change trade fields it marks
  `editable` and duplicate or delete lines (`lines.allowDuplicate`, `lines.allowDelete`); the changes
  are sent with the completion (`changes`) and written to trade before the step is saved.
- **Notifications** (e-mail, Teams channels, the blueprint's inquiry webhook) are sent by the comms
  module after the transition is stored. Webhook URLs carry credentials: responses replace them
  with `********`; send the placeholder back unchanged to keep the stored URL.

## Authentication
Send an access token as `Authorization: Bearer <accessToken>`. Get it by exchanging an API key at
`POST https://api.mbcom.cloud/api/hr/v1/auth/token`; it lives 15 minutes and carries the key's permissions.
The tenant is always the one of the token. Guide: https://developers.mbcom.cloud/guides/authentication

## Permissions
| Permission | Grants |
|---|---|
| `tenant:access` | own tasks (list, details, claim, complete, notes, inquiries), instances by id or object number, inquiry recipients |
| `tenant:dms:read` | additionally: the document of a task (`GET /tasks/{instanceId}/document`) |
| `tenant:settings:read` | workflow configuration and status, blueprints and their fields, comms channels, state versions of an instance |
| `tenant:settings:write` | switch workflows on/off, check the configuration, save/validate/switch/delete blueprints, start a workflow manually, force-unclaim tasks, restore state versions |
| `workflow:admin` | all instances of the tenant, cancel an instance, resend its state to trade |
| `portal:admin` | platform operators only: list customers and tenants |

## Conventions
- Errors have the shape `{error, code, field?, details?}` (see the errors guide); branch on `code`, the
  codes are listed in the `Error` response. A refused blueprint lists its problems in `details.problems`,
  invalid input every field in `details.fields`. Upstream answers (trade, HR, comms, DMS) are never passed on:
  trade's refusal of a step's changes is `422 trade_rejected` with trade's `field` and `details.tradeCode`.
- Lists answer `{items, total?, nextCursor?}`. `GET /instances` pages by cursor (`limit`, `cursor` =
  the previous page's `nextCursor`), `GET /tasks` by `limit` and `offset` with `total`; the other lists
  are bounded and returned whole with `total`.
- Instance changes are serialised per instance and revision-checked: a concurrent change answers
  `409 version_conflict`, another change running at the same moment `409 locked`; reload and try again. There are no idempotency keys; retrying a step completion applies
  its trade changes only once (the change set id is derived from instance, revision and content).
- Blueprints have no optimistic locking: the last save wins.

# Configuration

## Get the tenant's workflow configuration (tenant:settings:read)

`GET /api/workflow/v1/config`

Module: Workflow · operationId: `getWorkflowConfig` · Tag: Configuration · Auth: access token (`Authorization: Bearer <accessToken>`)

A tenant without a stored configuration gets (and stores) the default `{"active": false}`.

### Responses

- **200** Configuration (`application/json`)
- **400** Error (`application/json`)
- **401** Missing or invalid token (`unauthorized`) (`application/json`)
- **403** Error (`application/json`)
- **500** Error (`application/json`)

Fields of the 200 answer:

- `active` (boolean): Whether workflows run for the tenant
- `lastEditor` (string, read-only): E-mail of the last editor
- `lastUpdate` (string (date-time), nullable, read-only): Last change of the configuration
- `userEmailField` (string): No longer used

Example 200 answer:

```json
{
  "active": true,
  "lastEditor": "laura.kaestner@muster-it.example",
  "lastUpdate": "2026-10-14T13:20:11Z"
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/workflow/v1/config' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Switch workflows on or off for the tenant (tenant:settings:write)

`PUT /api/workflow/v1/config`

Module: Workflow · operationId: `updateWorkflowConfig` · Tag: Configuration · Auth: access token (`Authorization: Bearer <accessToken>`)

`active` is the only writable field (`userEmailField` is accepted and ignored). `lastUpdate` and
`lastEditor` are set by the server; sending them or any other field answers `400 invalid` with every
field in `details.fields`. While workflows are off, nothing starts and step completions are ignored;
pending trade write-backs are still delivered.

### Request body

`application/json` (required)

- `active` (boolean, required): Whether workflows run for the tenant

Example:

```json
{
  "active": true
}
```

### Responses

- **200** Saved (`application/json`)
- **400** Error (`application/json`)
- **401** Missing or invalid token (`unauthorized`) (`application/json`)
- **403** Error (`application/json`)
- **500** Error (`application/json`)

Fields of the 200 answer:

- `active` (boolean): Whether workflows run for the tenant
- `lastEditor` (string, read-only): E-mail of the last editor
- `lastUpdate` (string (date-time), nullable, read-only): Last change of the configuration
- `userEmailField` (string): No longer used

Example 200 answer:

```json
{
  "active": true,
  "lastEditor": "laura.kaestner@muster-it.example",
  "lastUpdate": "2026-10-14T13:20:11Z"
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/workflow/v1/config' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"active":true}'
```

## Check the workflow setup of the tenant (tenant:settings:write)

`POST /api/workflow/v1/config/validate`

Module: Workflow · operationId: `validateWorkflowConfig` · Tag: Configuration · Auth: access token (`Authorization: Bearer <accessToken>`)

Runs live checks (database, stored configuration, trade connection, HR connection, blueprints,
comms) and reports each one. Changes nothing; `ok` is false when a check has status `error`.
Sends no request body.

### Responses

- **200** Check results (`application/json`)
- **401** Missing or invalid token (`unauthorized`) (`application/json`)
- **403** Error (`application/json`)

Fields of the 200 answer:

- `checks` (array of object): One entry per check
  - `detail` (string): Details of the outcome
  - `label` (string): Name of the check
  - `status` (string): Outcome of the check (one of `success`, `warning`, `error`, `neutral`)
- `message` (string): Summary of the check
- `ok` (boolean): False when any check has status `error`

Example 200 answer:

```json
{
  "checks": [
    {
      "detail": "Verbindung zu trade erfolgreich.",
      "label": "trade-Verbindung",
      "status": "success"
    },
    {
      "detail": "Alle Gruppen der Blueprints gibt es.",
      "label": "HR-Gruppen",
      "status": "success"
    },
    {
      "detail": "Kein Blueprint nutzt einen Teams-Kanal.",
      "label": "Benachrichtigungen",
      "status": "neutral"
    }
  ],
  "message": "Konfiguration ist gültig.",
  "ok": true
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/workflow/v1/config/validate' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Whether workflows are active for the tenant (tenant:settings:read)

`GET /api/workflow/v1/config/status`

Module: Workflow · operationId: `getWorkflowStatus` · Tag: Configuration · Auth: access token (`Authorization: Bearer <accessToken>`)

### Responses

- **200** Status (`application/json`)
- **400** Error (`application/json`)
- **401** Missing or invalid token (`unauthorized`) (`application/json`)
- **403** Error (`application/json`)
- **500** Error (`application/json`)

Fields of the 200 answer:

- `active` (boolean): Whether workflows run for the tenant

Example 200 answer:

```json
{
  "active": true
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/workflow/v1/config/status' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

# Blueprints

## List the tenant's blueprints (tenant:settings:read)

`GET /api/workflow/v1/blueprints`

Module: Workflow · operationId: `listBlueprints` · Tag: Blueprints · Auth: access token (`Authorization: Bearer <accessToken>`)

Blueprints stored for the tenant (platform templates are not listed). A tenant without blueprints gets `null`.

### Responses

- **200** Blueprints, webhook URLs redacted (`application/json`)
- **401** Missing or invalid token (`unauthorized`) (`application/json`)
- **403** Error (`application/json`)
- **500** Error (`application/json`)

Fields of the 200 answer:

Array of Blueprint:

- `id` (string, required): Free identifier, unique per tenant
- `steps` (array of Step, required): Steps of the workflow; the first one runs unless trigger.nextStep names another
  - `name` (string, required): Unique within the blueprint; referenced by `nextSteps[].step`
  - `stepType` (string, required): `UserStep` (a person decides) or `SystemStep` (the engine decides) (one of `UserStep`, `SystemStep`)
  - `action` (string): Outcome when the workflow ends after this step: `approve` → APPROVED, `reject` → REJECTED (German synonyms accepted), else COMPLETED
  - `allowInquiry` (boolean): The assignee may ask another person (inquiry)
  - `fields` (array of Field): Fields shown in a user step
    - `name` (string, required): Trade field (`GET /blueprints/fields`), `typeData.<key>`, `lines.<field>`, or a workflow-local input field
    - `editable` (boolean): The user may change it; trade fields only if listed as editable
    - `label` (string): Label shown in the step
    - `required` (boolean): The user must fill it in to complete the step
    - `visible` (boolean, nullable): Whether the field is shown; null means visible
  - `group` (string): HR group UUID the user step is assigned to (required for user steps)
  - `lines` (LineActions): Line actions of a user step besides editing line fields
    - `allowDelete` (boolean): The user may delete lines
    - `allowDuplicate` (boolean): The user may duplicate lines
  - `nextSteps` (array of NextStep): Transitions: buttons of a user step, conditions of a system step
    - `color` (string): Button color of a user step transition
    - `condition` (string): System steps: expr condition, or `default`
    - `icon` (string): Button icon of a user step transition
    - `label` (string): Button label of a user step transition
    - `step` (string): Name of the target step
  - `notificationEmail` (string): E-mail address notified about this step
  - `notifyAssigneesByEmail` (boolean): E-mail the assignees (the step's user, else its group's members) when the task waits; user steps only
  - `notifyAssigneesByTeams` (boolean): Notify the assignees in their personal Teams chat; user steps only
  - `teamsChannel` (string): Comms webhook channel id notified about this step (see `GET /channels`)
  - `teamsWebhookUrl` (string): Legacy: a Teams webhook URL; saving moves it into a comms channel (`teamsChannel`)
  - `user` (string): E-mail of a person the user step is additionally assigned to
- `trigger` (Trigger, required)
  - `objectType` (string, required): The only supported object type (one of `transaction`)
  - `condition` (string): Optional expr condition over the transaction data; false ends the start as `TRIGGER_NOT_MATCHED`
  - `nextStep` (NextStep)
    - `color` (string): Button color of a user step transition
    - `condition` (string): System steps: expr condition, or `default`
    - `icon` (string): Button icon of a user step transition
    - `label` (string): Button label of a user step transition
    - `step` (string): Name of the target step
  - `statuses` (array of string): Trade statuses that start the workflow
  - `transactionTypes` (array of string): Trade transaction type codes (active in trade)
- `active` (boolean): Only active blueprints start workflows; missing means active
- `inquiryWebhookUrl` (string): Webhook (JSON) notified about inquiries and their answers; `********` keeps the stored URL
- `overviewField1` (OverviewField)
  - `label` (string): Column label
  - `name` (string): Transaction field shown in task lists
- `overviewField2` (OverviewField)
  - `label` (string): Column label
  - `name` (string): Transaction field shown in task lists
- `updatedAt` (string (date-time), read-only): Last modification of the stored blueprint
- `version` (integer (int64)): Informational; set to 1 when 0 on save

Example 200 answer:

```json
[
  {
    "active": true,
    "id": "er-freigabe",
    "overviewField1": {
      "label": "Lieferant",
      "name": "partnerCompany"
    },
    "overviewField2": {
      "label": "Brutto",
      "name": "grossTotal"
    },
    "steps": [
      {
        "allowInquiry": true,
        "fields": [
          {
            "label": "Eingangsnr.",
            "name": "transactionNumber"
          },
          {
            "label": "Rechnungsnummer",
            "name": "externalTransactionNumber"
          },
          {
            "label": "Lieferant",
            "name": "partnerCompany"
          },
          {
            "editable": true,
            "label": "Fällig am",
            "name": "dueDate"
          },
          {
            "label": "Brutto",
            "name": "grossTotal"
          },
          {
            "label": "Bezeichnung",
            "name": "lines.name"
          },
          {
            "editable": true,
            "label": "Kostenstelle",
            "name": "lines.lineData.costCenter",
            "required": true
          },
          {
            "label": "Menge",
            "name": "lines.quantity"
          }
        ],
        "group": "4e7a1c2b-9f3d-4b8a-a6e1-5c0d2f8b3a71",
        "lines": {
          "allowDelete": true,
          "allowDuplicate": true
        },
        "name": "kontierung",
        "nextSteps": [
          {
            "color": "primary",
            "icon": "i-lucide-arrow-right",
            "label": "Weiter zur Freigabe",
            "step": "freigabe"
          },
          {
            "color": "error",
            "icon": "i-lucide-x-circle",
            "label": "Ablehnen",
            "step": "abgelehnt"
          }
        ],
        "notifyAssigneesByEmail": true,
        "stepType": "UserStep"
      },
      {
        "allowInquiry": true,
        "fields": [
          {
            "label": "Eingangsnr.",
            "name": "transactionNumber"
          },
          {
            "label": "Lieferant",
            "name": "partnerCompany"
          },
          {
            "label": "Brutto",
            "name": "grossTotal"
          }
        ],
        "group": "4e7a1c2b-9f3d-4b8a-a6e1-5c0d2f8b3a71",
        "name": "freigabe",
        "nextSteps": [
          {
            "color": "success",
            "icon": "i-lucide-check-circle",
            "label": "Freigeben",
            "step": "freigegeben"
          },
          {
            "color": "warning",
            "icon": "i-lucide-undo-2",
            "label": "Zurück zur Kontierung",
            "step": "kontierung"
          },
          {
            "color": "error",
            "icon": "i-lucide-x-circle",
            "label": "Ablehnen",
            "step": "abgelehnt"
          }
        ],
        "stepType": "UserStep"
      },
      {
        "action": "approve",
        "name": "freigegeben",
        "stepType": "SystemStep"
      },
      {
        "action": "reject",
        "name": "abgelehnt",
        "stepType": "SystemStep"
      }
    ],
    "trigger": {
      "nextStep": {
        "step": "kontierung"
      },
      "objectType": "transaction",
      "statuses": [
        "MATCHED"
      ],
      "transactionTypes": [
        "INBOUND_INVOICE"
      ]
    },
    "updatedAt": "2026-10-14T13:22:05Z",
    "version": 3
  }
]
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/workflow/v1/blueprints' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Field names blueprints can use (tenant:settings:read)

`GET /api/workflow/v1/blueprints/fields`

Module: Workflow · operationId: `listBlueprintFields` · Tag: Blueprints · Auth: access token (`Authorization: Bearer <accessToken>`)

The trade transaction fields steps, overview fields and conditions can refer to, and which of
them a user step may mark `editable`. `typeData.` and `lineData.` are prefixes for the
transaction type's and the line's free-form data (e.g. `typeData.validUntil`). Line fields are
used in steps as `lines.<field>`.

### Responses

- **200** Field names, sorted (`application/json`)
- **401** Missing or invalid token (`unauthorized`) (`application/json`)
- **403** Error (`application/json`)

Fields of the 200 answer:

- `editableLines` (array of string, required): Line fields a user step may change
- `editableTransaction` (array of string, required): Transaction fields a user step may change
- `lines` (array of string, required): Fields of one transaction line
- `transaction` (array of string, required): Transaction fields

Example 200 answer:

```json
{
  "editableLines": [
    "lineData.",
    "articleNumber",
    "discountPercent",
    "quantity",
    "unitPriceNet"
  ],
  "editableTransaction": [
    "typeData.",
    "deliveryDate",
    "documentDate",
    "dueDate",
    "footerText",
    "headerText"
  ],
  "lines": [
    "articleNumber",
    "name",
    "quantity",
    "taxRate",
    "totalPriceNet",
    "unitPriceNet"
  ],
  "transaction": [
    "typeData.",
    "currency",
    "deliveryDate",
    "documentDate",
    "dueDate",
    "grossTotal",
    "partnerCompany",
    "status",
    "transactionNumber",
    "transactionType"
  ]
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/workflow/v1/blueprints/fields' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Check a blueprint without saving it (tenant:settings:write)

`POST /api/workflow/v1/blueprints/validate`

Module: Workflow · operationId: `validateBlueprint` · Tag: Blueprints · Auth: access token (`Authorization: Bearer <accessToken>`)

Runs the same checks as a save – field names, conditions, HR groups, trade transaction types,
comms channels – and returns the problems found (empty when the blueprint is valid). A check that
cannot reach trade or HR is reported as a problem.

### Request body

`application/json` (required)

- `id` (string, required): Free identifier, unique per tenant
- `steps` (array of Step, required): Steps of the workflow; the first one runs unless trigger.nextStep names another
  - `name` (string, required): Unique within the blueprint; referenced by `nextSteps[].step`
  - `stepType` (string, required): `UserStep` (a person decides) or `SystemStep` (the engine decides) (one of `UserStep`, `SystemStep`)
  - `action` (string): Outcome when the workflow ends after this step: `approve` → APPROVED, `reject` → REJECTED (German synonyms accepted), else COMPLETED
  - `allowInquiry` (boolean): The assignee may ask another person (inquiry)
  - `fields` (array of Field): Fields shown in a user step
    - `name` (string, required): Trade field (`GET /blueprints/fields`), `typeData.<key>`, `lines.<field>`, or a workflow-local input field
    - `editable` (boolean): The user may change it; trade fields only if listed as editable
    - `label` (string): Label shown in the step
    - `required` (boolean): The user must fill it in to complete the step
    - `visible` (boolean, nullable): Whether the field is shown; null means visible
  - `group` (string): HR group UUID the user step is assigned to (required for user steps)
  - `lines` (LineActions): Line actions of a user step besides editing line fields
    - `allowDelete` (boolean): The user may delete lines
    - `allowDuplicate` (boolean): The user may duplicate lines
  - `nextSteps` (array of NextStep): Transitions: buttons of a user step, conditions of a system step
    - `color` (string): Button color of a user step transition
    - `condition` (string): System steps: expr condition, or `default`
    - `icon` (string): Button icon of a user step transition
    - `label` (string): Button label of a user step transition
    - `step` (string): Name of the target step
  - `notificationEmail` (string): E-mail address notified about this step
  - `notifyAssigneesByEmail` (boolean): E-mail the assignees (the step's user, else its group's members) when the task waits; user steps only
  - `notifyAssigneesByTeams` (boolean): Notify the assignees in their personal Teams chat; user steps only
  - `teamsChannel` (string): Comms webhook channel id notified about this step (see `GET /channels`)
  - `teamsWebhookUrl` (string): Legacy: a Teams webhook URL; saving moves it into a comms channel (`teamsChannel`)
  - `user` (string): E-mail of a person the user step is additionally assigned to
- `trigger` (Trigger, required)
  - `objectType` (string, required): The only supported object type (one of `transaction`)
  - `condition` (string): Optional expr condition over the transaction data; false ends the start as `TRIGGER_NOT_MATCHED`
  - `nextStep` (NextStep)
    - `color` (string): Button color of a user step transition
    - `condition` (string): System steps: expr condition, or `default`
    - `icon` (string): Button icon of a user step transition
    - `label` (string): Button label of a user step transition
    - `step` (string): Name of the target step
  - `statuses` (array of string): Trade statuses that start the workflow
  - `transactionTypes` (array of string): Trade transaction type codes (active in trade)
- `active` (boolean): Only active blueprints start workflows; missing means active
- `inquiryWebhookUrl` (string): Webhook (JSON) notified about inquiries and their answers; `********` keeps the stored URL
- `overviewField1` (OverviewField)
  - `label` (string): Column label
  - `name` (string): Transaction field shown in task lists
- `overviewField2` (OverviewField)
  - `label` (string): Column label
  - `name` (string): Transaction field shown in task lists
- `updatedAt` (string (date-time), read-only): Last modification of the stored blueprint
- `version` (integer (int64)): Informational; set to 1 when 0 on save

Example:

```json
{
  "active": true,
  "id": "er-freigabe",
  "overviewField1": {
    "label": "Lieferant",
    "name": "partnerCompany"
  },
  "overviewField2": {
    "label": "Brutto",
    "name": "grossTotal"
  },
  "steps": [
    {
      "allowInquiry": true,
      "fields": [
        {
          "label": "Eingangsnr.",
          "name": "transactionNumber"
        },
        {
          "label": "Rechnungsnummer",
          "name": "externalTransactionNumber"
        },
        {
          "label": "Lieferant",
          "name": "partnerCompany"
        },
        {
          "editable": true,
          "label": "Fällig am",
          "name": "dueDate"
        },
        {
          "label": "Brutto",
          "name": "grossTotal"
        },
        {
          "label": "Bezeichnung",
          "name": "lines.name"
        },
        {
          "editable": true,
          "label": "Kostenstelle",
          "name": "lines.lineData.costCenter",
          "required": true
        },
        {
          "label": "Menge",
          "name": "lines.quantity"
        }
      ],
      "group": "4e7a1c2b-9f3d-4b8a-a6e1-5c0d2f8b3a71",
      "lines": {
        "allowDelete": true,
        "allowDuplicate": true
      },
      "name": "kontierung",
      "nextSteps": [
        {
          "color": "primary",
          "icon": "i-lucide-arrow-right",
          "label": "Weiter zur Freigabe",
          "step": "freigabe"
        },
        {
          "color": "error",
          "icon": "i-lucide-x-circle",
          "label": "Ablehnen",
          "step": "abgelehnt"
        }
      ],
      "notifyAssigneesByEmail": true,
      "stepType": "UserStep"
    },
    {
      "allowInquiry": true,
      "fields": [
        {
          "label": "Eingangsnr.",
          "name": "transactionNumber"
        },
        {
          "label": "Lieferant",
          "name": "partnerCompany"
        },
        {
          "label": "Brutto",
          "name": "grossTotal"
        }
      ],
      "group": "4e7a1c2b-9f3d-4b8a-a6e1-5c0d2f8b3a71",
      "name": "freigabe",
      "nextSteps": [
        {
          "color": "success",
          "icon": "i-lucide-check-circle",
          "label": "Freigeben",
          "step": "freigegeben"
        },
        {
          "color": "warning",
          "icon": "i-lucide-undo-2",
          "label": "Zurück zur Kontierung",
          "step": "kontierung"
        },
        {
          "color": "error",
          "icon": "i-lucide-x-circle",
          "label": "Ablehnen",
          "step": "abgelehnt"
        }
      ],
      "stepType": "UserStep"
    },
    {
      "action": "approve",
      "name": "freigegeben",
      "stepType": "SystemStep"
    },
    {
      "action": "reject",
      "name": "abgelehnt",
      "stepType": "SystemStep"
    }
  ],
  "trigger": {
    "nextStep": {
      "step": "kontierung"
    },
    "objectType": "transaction",
    "statuses": [
      "MATCHED"
    ],
    "transactionTypes": [
      "INBOUND_INVOICE"
    ]
  },
  "updatedAt": "2026-10-14T13:22:05Z",
  "version": 3
}
```

### Responses

- **200** Problems found (`application/json`)
- **400** Error (`application/json`)
- **401** Missing or invalid token (`unauthorized`) (`application/json`)
- **403** Error (`application/json`)
- **500** Error (`application/json`)

Fields of the 200 answer:

- `problems` (array of BlueprintProblem): Problems found; empty or null when the blueprint is valid
  - `message` (string): What is wrong, human-readable
  - `path` (string): Where in the blueprint (empty for the whole blueprint)

Example 200 answer:

```json
{
  "problems": [
    {
      "message": "HR-Gruppe '4e7a1c2b-9f3d-4b8a-a6e1-5c0d2f8b3a71' gibt es nicht",
      "path": "steps[1].group"
    }
  ]
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/workflow/v1/blueprints/validate' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"active":true,"id":"er-freigabe","overviewField1":{"label":"Lieferant","name":"partnerCompany"},"overviewField2":{"label":"Brutto","name":"grossTotal"},"steps":[{"allowInquiry":true,"fields":[{"label":"Eingangsnr.","name":"transactionNumber"},{"label":"Rechnungsnummer","name":"externalTransactionNumber"},{"label":"Lieferant","name":"partnerCompany"},{"editable":true,"label":"Fällig am","name":"dueDate"},{"label":"Brutto","name":"grossTotal"},{"label":"Bezeichnung","name":"lines.name"},{"editable":true,"label":"Kostenstelle","name":"lines.lineData.costCenter","required":true},{"label":"Menge","name":"lines.quantity"}],"group":"4e7a1c2b-9f3d-4b8a-a6e1-5c0d2f8b3a71","lines":{"allowDelete":true,"allowDuplicate":true},"name":"kontierung","nextSteps":[{"color":"primary","icon":"i-lucide-arrow-right","label":"Weiter zur Freigabe","step":"freigabe"},{"color":"error","icon":"i-lucide-x-circle","label":"Ablehnen","step":"abgelehnt"}],"notifyAssigneesByEmail":true,"stepType":"UserStep"},{"allowInquiry":true,"fields":[{"label":"Eingangsnr.","name":"transactionNumber"},{"label":"Lieferant","name":"partnerCompany"},{"label":"Brutto","name":"grossTotal"}],"group":"4e7a1c2b-9f3d-4b8a-a6e1-5c0d2f8b3a71","name":"freigabe","nextSteps":[{"color":"success","icon":"i-lucide-check-circle","label":"Freigeben","step":"freigegeben"},{"color":"warning","icon":"i-lucide-undo-2","label":"Zurück zur Kontierung","step":"kontierung"},{"color":"error","icon":"i-lucide-x-circle","label":"Ablehnen","step":"abgelehnt"}],"stepType":"UserStep"},{"action":"approve","name":"freigegeben","stepType":"SystemStep"},{"action":"reject","name":"abgelehnt","stepType":"SystemStep"}],"trigger":{"nextStep":{"step":"kontierung"},"objectType":"transaction","statuses":["MATCHED"],"transactionTypes":["INBOUND_INVOICE"]},"updatedAt":"2026-10-14T13:22:05Z","version":3}'
```

## Get a blueprint (tenant:settings:read)

`GET /api/workflow/v1/blueprints/{blueprintId}`

Module: Workflow · operationId: `getBlueprint` · Tag: Blueprints · Auth: access token (`Authorization: Bearer <accessToken>`)

The tenant's blueprint, or the platform template of that id if the tenant has none.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `blueprintId` | path | string | yes | Blueprint id |

### Responses

- **200** Blueprint, webhook URLs redacted (`application/json`)
- **401** Missing or invalid token (`unauthorized`) (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `id` (string, required): Free identifier, unique per tenant
- `steps` (array of Step, required): Steps of the workflow; the first one runs unless trigger.nextStep names another
  - `name` (string, required): Unique within the blueprint; referenced by `nextSteps[].step`
  - `stepType` (string, required): `UserStep` (a person decides) or `SystemStep` (the engine decides) (one of `UserStep`, `SystemStep`)
  - `action` (string): Outcome when the workflow ends after this step: `approve` → APPROVED, `reject` → REJECTED (German synonyms accepted), else COMPLETED
  - `allowInquiry` (boolean): The assignee may ask another person (inquiry)
  - `fields` (array of Field): Fields shown in a user step
    - `name` (string, required): Trade field (`GET /blueprints/fields`), `typeData.<key>`, `lines.<field>`, or a workflow-local input field
    - `editable` (boolean): The user may change it; trade fields only if listed as editable
    - `label` (string): Label shown in the step
    - `required` (boolean): The user must fill it in to complete the step
    - `visible` (boolean, nullable): Whether the field is shown; null means visible
  - `group` (string): HR group UUID the user step is assigned to (required for user steps)
  - `lines` (LineActions): Line actions of a user step besides editing line fields
    - `allowDelete` (boolean): The user may delete lines
    - `allowDuplicate` (boolean): The user may duplicate lines
  - `nextSteps` (array of NextStep): Transitions: buttons of a user step, conditions of a system step
    - `color` (string): Button color of a user step transition
    - `condition` (string): System steps: expr condition, or `default`
    - `icon` (string): Button icon of a user step transition
    - `label` (string): Button label of a user step transition
    - `step` (string): Name of the target step
  - `notificationEmail` (string): E-mail address notified about this step
  - `notifyAssigneesByEmail` (boolean): E-mail the assignees (the step's user, else its group's members) when the task waits; user steps only
  - `notifyAssigneesByTeams` (boolean): Notify the assignees in their personal Teams chat; user steps only
  - `teamsChannel` (string): Comms webhook channel id notified about this step (see `GET /channels`)
  - `teamsWebhookUrl` (string): Legacy: a Teams webhook URL; saving moves it into a comms channel (`teamsChannel`)
  - `user` (string): E-mail of a person the user step is additionally assigned to
- `trigger` (Trigger, required)
  - `objectType` (string, required): The only supported object type (one of `transaction`)
  - `condition` (string): Optional expr condition over the transaction data; false ends the start as `TRIGGER_NOT_MATCHED`
  - `nextStep` (NextStep)
    - `color` (string): Button color of a user step transition
    - `condition` (string): System steps: expr condition, or `default`
    - `icon` (string): Button icon of a user step transition
    - `label` (string): Button label of a user step transition
    - `step` (string): Name of the target step
  - `statuses` (array of string): Trade statuses that start the workflow
  - `transactionTypes` (array of string): Trade transaction type codes (active in trade)
- `active` (boolean): Only active blueprints start workflows; missing means active
- `inquiryWebhookUrl` (string): Webhook (JSON) notified about inquiries and their answers; `********` keeps the stored URL
- `overviewField1` (OverviewField)
  - `label` (string): Column label
  - `name` (string): Transaction field shown in task lists
- `overviewField2` (OverviewField)
  - `label` (string): Column label
  - `name` (string): Transaction field shown in task lists
- `updatedAt` (string (date-time), read-only): Last modification of the stored blueprint
- `version` (integer (int64)): Informational; set to 1 when 0 on save

Example 200 answer:

```json
{
  "active": true,
  "id": "er-freigabe",
  "overviewField1": {
    "label": "Lieferant",
    "name": "partnerCompany"
  },
  "overviewField2": {
    "label": "Brutto",
    "name": "grossTotal"
  },
  "steps": [
    {
      "allowInquiry": true,
      "fields": [
        {
          "label": "Eingangsnr.",
          "name": "transactionNumber"
        },
        {
          "label": "Rechnungsnummer",
          "name": "externalTransactionNumber"
        },
        {
          "label": "Lieferant",
          "name": "partnerCompany"
        },
        {
          "editable": true,
          "label": "Fällig am",
          "name": "dueDate"
        },
        {
          "label": "Brutto",
          "name": "grossTotal"
        },
        {
          "label": "Bezeichnung",
          "name": "lines.name"
        },
        {
          "editable": true,
          "label": "Kostenstelle",
          "name": "lines.lineData.costCenter",
          "required": true
        },
        {
          "label": "Menge",
          "name": "lines.quantity"
        }
      ],
      "group": "4e7a1c2b-9f3d-4b8a-a6e1-5c0d2f8b3a71",
      "lines": {
        "allowDelete": true,
        "allowDuplicate": true
      },
      "name": "kontierung",
      "nextSteps": [
        {
          "color": "primary",
          "icon": "i-lucide-arrow-right",
          "label": "Weiter zur Freigabe",
          "step": "freigabe"
        },
        {
          "color": "error",
          "icon": "i-lucide-x-circle",
          "label": "Ablehnen",
          "step": "abgelehnt"
        }
      ],
      "notifyAssigneesByEmail": true,
      "stepType": "UserStep"
    },
    {
      "allowInquiry": true,
      "fields": [
        {
          "label": "Eingangsnr.",
          "name": "transactionNumber"
        },
        {
          "label": "Lieferant",
          "name": "partnerCompany"
        },
        {
          "label": "Brutto",
          "name": "grossTotal"
        }
      ],
      "group": "4e7a1c2b-9f3d-4b8a-a6e1-5c0d2f8b3a71",
      "name": "freigabe",
      "nextSteps": [
        {
          "color": "success",
          "icon": "i-lucide-check-circle",
          "label": "Freigeben",
          "step": "freigegeben"
        },
        {
          "color": "warning",
          "icon": "i-lucide-undo-2",
          "label": "Zurück zur Kontierung",
          "step": "kontierung"
        },
        {
          "color": "error",
          "icon": "i-lucide-x-circle",
          "label": "Ablehnen",
          "step": "abgelehnt"
        }
      ],
      "stepType": "UserStep"
    },
    {
      "action": "approve",
      "name": "freigegeben",
      "stepType": "SystemStep"
    },
    {
      "action": "reject",
      "name": "abgelehnt",
      "stepType": "SystemStep"
    }
  ],
  "trigger": {
    "nextStep": {
      "step": "kontierung"
    },
    "objectType": "transaction",
    "statuses": [
      "MATCHED"
    ],
    "transactionTypes": [
      "INBOUND_INVOICE"
    ]
  },
  "updatedAt": "2026-10-14T13:22:05Z",
  "version": 3
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/workflow/v1/blueprints/angebot-pruefung' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Create or replace a blueprint (tenant:settings:write)

`PUT /api/workflow/v1/blueprints/{blueprintId}`

Module: Workflow · operationId: `saveBlueprint` · Tag: Blueprints · Auth: access token (`Authorization: Bearer <accessToken>`)

Stores the blueprint under the `id` **of the body** (the path segment is not used). The blueprint
needs an `id`, at least one step, a name for every step and, for `transaction` triggers, at
least one transaction type and status (`400`); the full check of `POST /blueprints/validate` must
find no problems (`422`). `version` defaults to 1 and is not incremented by the server.
A step's legacy `teamsWebhookUrl` is moved into a comms webhook channel (`teamsChannel`); if comms
fails the save answers `502`. Running instances keep the blueprint they started with.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `blueprintId` | path | string | yes | Blueprint id |

### Request body

`application/json` (required)

- `id` (string, required): Free identifier, unique per tenant
- `steps` (array of Step, required): Steps of the workflow; the first one runs unless trigger.nextStep names another
  - `name` (string, required): Unique within the blueprint; referenced by `nextSteps[].step`
  - `stepType` (string, required): `UserStep` (a person decides) or `SystemStep` (the engine decides) (one of `UserStep`, `SystemStep`)
  - `action` (string): Outcome when the workflow ends after this step: `approve` → APPROVED, `reject` → REJECTED (German synonyms accepted), else COMPLETED
  - `allowInquiry` (boolean): The assignee may ask another person (inquiry)
  - `fields` (array of Field): Fields shown in a user step
    - `name` (string, required): Trade field (`GET /blueprints/fields`), `typeData.<key>`, `lines.<field>`, or a workflow-local input field
    - `editable` (boolean): The user may change it; trade fields only if listed as editable
    - `label` (string): Label shown in the step
    - `required` (boolean): The user must fill it in to complete the step
    - `visible` (boolean, nullable): Whether the field is shown; null means visible
  - `group` (string): HR group UUID the user step is assigned to (required for user steps)
  - `lines` (LineActions): Line actions of a user step besides editing line fields
    - `allowDelete` (boolean): The user may delete lines
    - `allowDuplicate` (boolean): The user may duplicate lines
  - `nextSteps` (array of NextStep): Transitions: buttons of a user step, conditions of a system step
    - `color` (string): Button color of a user step transition
    - `condition` (string): System steps: expr condition, or `default`
    - `icon` (string): Button icon of a user step transition
    - `label` (string): Button label of a user step transition
    - `step` (string): Name of the target step
  - `notificationEmail` (string): E-mail address notified about this step
  - `notifyAssigneesByEmail` (boolean): E-mail the assignees (the step's user, else its group's members) when the task waits; user steps only
  - `notifyAssigneesByTeams` (boolean): Notify the assignees in their personal Teams chat; user steps only
  - `teamsChannel` (string): Comms webhook channel id notified about this step (see `GET /channels`)
  - `teamsWebhookUrl` (string): Legacy: a Teams webhook URL; saving moves it into a comms channel (`teamsChannel`)
  - `user` (string): E-mail of a person the user step is additionally assigned to
- `trigger` (Trigger, required)
  - `objectType` (string, required): The only supported object type (one of `transaction`)
  - `condition` (string): Optional expr condition over the transaction data; false ends the start as `TRIGGER_NOT_MATCHED`
  - `nextStep` (NextStep)
    - `color` (string): Button color of a user step transition
    - `condition` (string): System steps: expr condition, or `default`
    - `icon` (string): Button icon of a user step transition
    - `label` (string): Button label of a user step transition
    - `step` (string): Name of the target step
  - `statuses` (array of string): Trade statuses that start the workflow
  - `transactionTypes` (array of string): Trade transaction type codes (active in trade)
- `active` (boolean): Only active blueprints start workflows; missing means active
- `inquiryWebhookUrl` (string): Webhook (JSON) notified about inquiries and their answers; `********` keeps the stored URL
- `overviewField1` (OverviewField)
  - `label` (string): Column label
  - `name` (string): Transaction field shown in task lists
- `overviewField2` (OverviewField)
  - `label` (string): Column label
  - `name` (string): Transaction field shown in task lists
- `updatedAt` (string (date-time), read-only): Last modification of the stored blueprint
- `version` (integer (int64)): Informational; set to 1 when 0 on save

Example:

```json
{
  "active": true,
  "id": "angebot-pruefung",
  "overviewField1": {
    "label": "Kunde",
    "name": "partnerCompany"
  },
  "overviewField2": {
    "label": "Brutto",
    "name": "grossTotal"
  },
  "steps": [
    {
      "allowInquiry": true,
      "fields": [
        {
          "label": "Angebotsnummer",
          "name": "transactionNumber"
        },
        {
          "editable": true,
          "label": "Gültig bis",
          "name": "typeData.validUntil"
        },
        {
          "editable": true,
          "label": "Menge",
          "name": "lines.quantity"
        }
      ],
      "group": "4e7a1c2b-9f3d-4b8a-a6e1-5c0d2f8b3a71",
      "lines": {
        "allowDelete": false,
        "allowDuplicate": true
      },
      "name": "pruefung",
      "nextSteps": [
        {
          "color": "primary",
          "icon": "i-lucide-arrow-right",
          "label": "Weiter",
          "step": "betrag_pruefen"
        },
        {
          "color": "error",
          "icon": "i-lucide-x-circle",
          "label": "Ablehnen",
          "step": "abgelehnt"
        }
      ],
      "notifyAssigneesByEmail": true,
      "stepType": "UserStep"
    },
    {
      "action": "route",
      "name": "betrag_pruefen",
      "nextSteps": [
        {
          "condition": "grossTotal \u003e 1000",
          "step": "freigabe_gf"
        },
        {
          "condition": "default",
          "step": "freigegeben"
        }
      ],
      "stepType": "SystemStep"
    },
    {
      "fields": [
        {
          "label": "Brutto",
          "name": "grossTotal"
        }
      ],
      "group": "4e7a1c2b-9f3d-4b8a-a6e1-5c0d2f8b3a71",
      "name": "freigabe_gf",
      "nextSteps": [
        {
          "color": "success",
          "label": "Freigeben",
          "step": "freigegeben"
        },
        {
          "color": "error",
          "label": "Ablehnen",
          "step": "abgelehnt"
        }
      ],
      "stepType": "UserStep"
    },
    {
      "action": "approve",
      "name": "freigegeben",
      "stepType": "SystemStep"
    },
    {
      "action": "reject",
      "name": "abgelehnt",
      "stepType": "SystemStep"
    }
  ],
  "trigger": {
    "nextStep": {
      "step": "pruefung"
    },
    "objectType": "transaction",
    "statuses": [
      "DRAFT"
    ],
    "transactionTypes": [
      "OFFER"
    ]
  }
}
```

### Responses

- **200** Saved (no body)
- **400** Error (`application/json`)
- **401** Missing or invalid token (`unauthorized`) (`application/json`)
- **403** Error (`application/json`)
- **422** The blueprint has problems and was not saved or switched on (`invalid_blueprint`, the problems in `details.problems`) (`application/json`)
- **500** Error (`application/json`)
- **503** Error (`application/json`)

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/workflow/v1/blueprints/angebot-pruefung' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"active":true,"id":"angebot-pruefung","overviewField1":{"label":"Kunde","name":"partnerCompany"},"overviewField2":{"label":"Brutto","name":"grossTotal"},"steps":[{"allowInquiry":true,"fields":[{"label":"Angebotsnummer","name":"transactionNumber"},{"editable":true,"label":"Gültig bis","name":"typeData.validUntil"},{"editable":true,"label":"Menge","name":"lines.quantity"}],"group":"4e7a1c2b-9f3d-4b8a-a6e1-5c0d2f8b3a71","lines":{"allowDelete":false,"allowDuplicate":true},"name":"pruefung","nextSteps":[{"color":"primary","icon":"i-lucide-arrow-right","label":"Weiter","step":"betrag_pruefen"},{"color":"error","icon":"i-lucide-x-circle","label":"Ablehnen","step":"abgelehnt"}],"notifyAssigneesByEmail":true,"stepType":"UserStep"},{"action":"route","name":"betrag_pruefen","nextSteps":[{"condition":"grossTotal \u003e 1000","step":"freigabe_gf"},{"condition":"default","step":"freigegeben"}],"stepType":"SystemStep"},{"fields":[{"label":"Brutto","name":"grossTotal"}],"group":"4e7a1c2b-9f3d-4b8a-a6e1-5c0d2f8b3a71","name":"freigabe_gf","nextSteps":[{"color":"success","label":"Freigeben","step":"freigegeben"},{"color":"error","label":"Ablehnen","step":"abgelehnt"}],"stepType":"UserStep"},{"action":"approve","name":"freigegeben","stepType":"SystemStep"},{"action":"reject","name":"abgelehnt","stepType":"SystemStep"}],"trigger":{"nextStep":{"step":"pruefung"},"objectType":"transaction","statuses":["DRAFT"],"transactionTypes":["OFFER"]}}'
```

## Delete a blueprint (tenant:settings:write)

`DELETE /api/workflow/v1/blueprints/{blueprintId}`

Module: Workflow · operationId: `deleteBlueprint` · Tag: Blueprints · Auth: access token (`Authorization: Bearer <accessToken>`)

No new workflows start from it; running instances go on with their snapshot.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `blueprintId` | path | string | yes | Blueprint id |

### Responses

- **200** Deleted (no body)
- **401** Missing or invalid token (`unauthorized`) (`application/json`)
- **403** Error (`application/json`)
- **500** Error (`application/json`)

### Example request

```bash
curl -X DELETE 'https://api.mbcom.cloud/api/workflow/v1/blueprints/angebot-pruefung' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Switch a blueprint on or off (tenant:settings:write)

`PUT /api/workflow/v1/blueprints/{blueprintId}/active`

Module: Workflow · operationId: `setBlueprintActive` · Tag: Blueprints · Auth: access token (`Authorization: Bearer <accessToken>`)

Switching on runs the blueprint check like a save (`422` with the problems); switching off always
works. Running instances are not affected either way.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `blueprintId` | path | string | yes | Blueprint id |

### Request body

`application/json` (required)

- `active` (boolean, required): Whether the blueprint starts workflows

Example:

```json
{
  "active": false
}
```

### Responses

- **200** The switched blueprint, webhook URLs redacted (`application/json`)
- **400** Error (`application/json`)
- **401** Missing or invalid token (`unauthorized`) (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **422** The blueprint has problems and was not saved or switched on (`invalid_blueprint`, the problems in `details.problems`) (`application/json`)
- **500** Error (`application/json`)

Fields of the 200 answer:

- `id` (string, required): Free identifier, unique per tenant
- `steps` (array of Step, required): Steps of the workflow; the first one runs unless trigger.nextStep names another
  - `name` (string, required): Unique within the blueprint; referenced by `nextSteps[].step`
  - `stepType` (string, required): `UserStep` (a person decides) or `SystemStep` (the engine decides) (one of `UserStep`, `SystemStep`)
  - `action` (string): Outcome when the workflow ends after this step: `approve` → APPROVED, `reject` → REJECTED (German synonyms accepted), else COMPLETED
  - `allowInquiry` (boolean): The assignee may ask another person (inquiry)
  - `fields` (array of Field): Fields shown in a user step
    - `name` (string, required): Trade field (`GET /blueprints/fields`), `typeData.<key>`, `lines.<field>`, or a workflow-local input field
    - `editable` (boolean): The user may change it; trade fields only if listed as editable
    - `label` (string): Label shown in the step
    - `required` (boolean): The user must fill it in to complete the step
    - `visible` (boolean, nullable): Whether the field is shown; null means visible
  - `group` (string): HR group UUID the user step is assigned to (required for user steps)
  - `lines` (LineActions): Line actions of a user step besides editing line fields
    - `allowDelete` (boolean): The user may delete lines
    - `allowDuplicate` (boolean): The user may duplicate lines
  - `nextSteps` (array of NextStep): Transitions: buttons of a user step, conditions of a system step
    - `color` (string): Button color of a user step transition
    - `condition` (string): System steps: expr condition, or `default`
    - `icon` (string): Button icon of a user step transition
    - `label` (string): Button label of a user step transition
    - `step` (string): Name of the target step
  - `notificationEmail` (string): E-mail address notified about this step
  - `notifyAssigneesByEmail` (boolean): E-mail the assignees (the step's user, else its group's members) when the task waits; user steps only
  - `notifyAssigneesByTeams` (boolean): Notify the assignees in their personal Teams chat; user steps only
  - `teamsChannel` (string): Comms webhook channel id notified about this step (see `GET /channels`)
  - `teamsWebhookUrl` (string): Legacy: a Teams webhook URL; saving moves it into a comms channel (`teamsChannel`)
  - `user` (string): E-mail of a person the user step is additionally assigned to
- `trigger` (Trigger, required)
  - `objectType` (string, required): The only supported object type (one of `transaction`)
  - `condition` (string): Optional expr condition over the transaction data; false ends the start as `TRIGGER_NOT_MATCHED`
  - `nextStep` (NextStep)
    - `color` (string): Button color of a user step transition
    - `condition` (string): System steps: expr condition, or `default`
    - `icon` (string): Button icon of a user step transition
    - `label` (string): Button label of a user step transition
    - `step` (string): Name of the target step
  - `statuses` (array of string): Trade statuses that start the workflow
  - `transactionTypes` (array of string): Trade transaction type codes (active in trade)
- `active` (boolean): Only active blueprints start workflows; missing means active
- `inquiryWebhookUrl` (string): Webhook (JSON) notified about inquiries and their answers; `********` keeps the stored URL
- `overviewField1` (OverviewField)
  - `label` (string): Column label
  - `name` (string): Transaction field shown in task lists
- `overviewField2` (OverviewField)
  - `label` (string): Column label
  - `name` (string): Transaction field shown in task lists
- `updatedAt` (string (date-time), read-only): Last modification of the stored blueprint
- `version` (integer (int64)): Informational; set to 1 when 0 on save

Example 200 answer:

```json
{
  "active": true,
  "id": "er-freigabe",
  "overviewField1": {
    "label": "Lieferant",
    "name": "partnerCompany"
  },
  "overviewField2": {
    "label": "Brutto",
    "name": "grossTotal"
  },
  "steps": [
    {
      "allowInquiry": true,
      "fields": [
        {
          "label": "Eingangsnr.",
          "name": "transactionNumber"
        },
        {
          "label": "Rechnungsnummer",
          "name": "externalTransactionNumber"
        },
        {
          "label": "Lieferant",
          "name": "partnerCompany"
        },
        {
          "editable": true,
          "label": "Fällig am",
          "name": "dueDate"
        },
        {
          "label": "Brutto",
          "name": "grossTotal"
        },
        {
          "label": "Bezeichnung",
          "name": "lines.name"
        },
        {
          "editable": true,
          "label": "Kostenstelle",
          "name": "lines.lineData.costCenter",
          "required": true
        },
        {
          "label": "Menge",
          "name": "lines.quantity"
        }
      ],
      "group": "4e7a1c2b-9f3d-4b8a-a6e1-5c0d2f8b3a71",
      "lines": {
        "allowDelete": true,
        "allowDuplicate": true
      },
      "name": "kontierung",
      "nextSteps": [
        {
          "color": "primary",
          "icon": "i-lucide-arrow-right",
          "label": "Weiter zur Freigabe",
          "step": "freigabe"
        },
        {
          "color": "error",
          "icon": "i-lucide-x-circle",
          "label": "Ablehnen",
          "step": "abgelehnt"
        }
      ],
      "notifyAssigneesByEmail": true,
      "stepType": "UserStep"
    },
    {
      "allowInquiry": true,
      "fields": [
        {
          "label": "Eingangsnr.",
          "name": "transactionNumber"
        },
        {
          "label": "Lieferant",
          "name": "partnerCompany"
        },
        {
          "label": "Brutto",
          "name": "grossTotal"
        }
      ],
      "group": "4e7a1c2b-9f3d-4b8a-a6e1-5c0d2f8b3a71",
      "name": "freigabe",
      "nextSteps": [
        {
          "color": "success",
          "icon": "i-lucide-check-circle",
          "label": "Freigeben",
          "step": "freigegeben"
        },
        {
          "color": "warning",
          "icon": "i-lucide-undo-2",
          "label": "Zurück zur Kontierung",
          "step": "kontierung"
        },
        {
          "color": "error",
          "icon": "i-lucide-x-circle",
          "label": "Ablehnen",
          "step": "abgelehnt"
        }
      ],
      "stepType": "UserStep"
    },
    {
      "action": "approve",
      "name": "freigegeben",
      "stepType": "SystemStep"
    },
    {
      "action": "reject",
      "name": "abgelehnt",
      "stepType": "SystemStep"
    }
  ],
  "trigger": {
    "nextStep": {
      "step": "kontierung"
    },
    "objectType": "transaction",
    "statuses": [
      "MATCHED"
    ],
    "transactionTypes": [
      "INBOUND_INVOICE"
    ]
  },
  "updatedAt": "2026-10-14T13:22:05Z",
  "version": 3
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/workflow/v1/blueprints/angebot-pruefung/active' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"active":false}'
```

## List the tenant's comms webhook channels for step notifications (tenant:settings:read)

`GET /api/workflow/v1/channels`

Module: Workflow · operationId: `listWebhookChannels` · Tag: Blueprints · Auth: access token (`Authorization: Bearer <accessToken>`)

The channels a step can name as `teamsChannel`. URLs are never returned. Empty when comms is not configured.

### Responses

- **200** Channels (`application/json`)
- **401** Missing or invalid token (`unauthorized`) (`application/json`)
- **403** Error (`application/json`)
- **503** Error (`application/json`)

Fields of the 200 answer:

- `items` (array of WebhookChannel, required): Items of the list
  - `format` (string): Payload format of the channel (one of `json_event`, `teams_card`)
  - `id` (string): Channel id, used as a step's `teamsChannel`
  - `name` (string): Channel name
  - `status` (string): Status of the channel in comms
- `total` (integer): Number of items

Example 200 answer:

```json
{
  "items": [
    {
      "format": "teams_card",
      "id": "9c4e2b7a-1d3f-4a6b-8c5d-2e7f9a1b3c4d",
      "name": "Teams-Kanal Buchhaltung",
      "status": "active"
    }
  ],
  "total": 1
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/workflow/v1/channels' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

# Tasks

## List the people an inquiry can go to (tenant:access)

`GET /api/workflow/v1/users`

Module: Workflow · operationId: `listInquiryRecipients` · Tag: Tasks · Auth: access token (`Authorization: Bearer <accessToken>`)

The tenant's active employees from HR, one entry per e-mail address, sorted by name.

### Responses

- **200** People (`application/json`)
- **401** Missing or invalid token (`unauthorized`) (`application/json`)
- **403** Error (`application/json`)
- **503** Error (`application/json`)

Fields of the 200 answer:

- `items` (array of InquiryRecipient, required): Items of the list
  - `email` (string (email)): E-mail address
  - `id` (string): The e-mail address
  - `name` (string): Display name
- `total` (integer): Number of items

Example 200 answer:

```json
{
  "items": [
    {
      "email": "laura.kaestner@muster-it.example",
      "id": "laura.kaestner@muster-it.example",
      "name": "Laura Kästner"
    },
    {
      "email": "lukas.wimmer@muster-it.example",
      "id": "lukas.wimmer@muster-it.example",
      "name": "Lukas Wimmer"
    }
  ],
  "total": 2
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/workflow/v1/users' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## List the open tasks assigned to the caller (tenant:access)

`GET /api/workflow/v1/tasks`

Module: Workflow · operationId: `listTasks` · Tag: Tasks · Auth: access token (`Authorization: Bearer <accessToken>`)

Instances in state `OPEN` or `RETRYING_SYNC` whose current step is assigned to the caller (the
step's user, a member of its group, or the recipient or sender of an open inquiry). Each item
carries the blueprint's overview fields with their values. Pages with `limit` and `offset`; `total` counts
all open tasks of the caller.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `limit` | query | integer |  | Page size; another value than 1–500 is a `400 invalid` (default `100`; max 500) |
| `offset` | query | integer |  | Number of items to skip; a negative value is a `400 invalid` (default `0`) |
| `slim` | query | string |  | `true` or `1`: return `SlimTaskListItem`s without data and history (one of `true`, `1`) |
| `format` | query | string |  | `slim`: same as `slim=true` (one of `slim`) |
| `slim_history` | query | string |  | `true` or `1`: blank the comments of notes and of history entries longer than 100 characters (one of `true`, `1`) |

### Responses

- **200** Tasks (slim items when `slim` is set) (`application/json`)
- **400** Error (`application/json`)
- **401** Missing or invalid token (`unauthorized`) (`application/json`)
- **403** Error (`application/json`)
- **500** Error (`application/json`)

Fields of the 200 answer:

- `items` (array of TaskListItem | SlimTaskListItem, required): Tasks of the page
- `total` (integer, required): Number of open tasks of the caller

Example 200 answer:

```json
{
  "items": [
    {
      "blueprint": {
        "id": "er-freigabe",
        "version": 3
      },
      "blueprintId": "er-freigabe",
      "blueprintVersion": 3,
      "claimedAt": "2026-11-17T09:05:40Z",
      "claimedBy": "christina.adler@muster-it.example",
      "currentStep": {
        "allowInquiry": true,
        "fields": [
          {
            "label": "Eingangsnr.",
            "name": "transactionNumber"
          },
          {
            "label": "Rechnungsnummer",
            "name": "externalTransactionNumber"
          },
          {
            "label": "Lieferant",
            "name": "partnerCompany"
          },
          {
            "editable": true,
            "label": "Fällig am",
            "name": "dueDate"
          },
          {
            "label": "Brutto",
            "name": "grossTotal"
          },
          {
            "label": "Bezeichnung",
            "name": "lines.name"
          },
          {
            "editable": true,
            "label": "Kostenstelle",
            "name": "lines.lineData.costCenter",
            "required": true
          },
          {
            "label": "Menge",
            "name": "lines.quantity"
          }
        ],
        "group": "4e7a1c2b-9f3d-4b8a-a6e1-5c0d2f8b3a71",
        "lines": {
          "allowDelete": true,
          "allowDuplicate": true
        },
        "name": "kontierung",
        "nextSteps": [
          {
            "color": "primary",
            "icon": "i-lucide-arrow-right",
            "label": "Weiter zur Freigabe",
            "step": "freigabe"
          },
          {
            "color": "error",
            "icon": "i-lucide-x-circle",
            "label": "Ablehnen",
            "step": "abgelehnt"
          }
        ],
        "notifyAssigneesByEmail": true,
        "stepType": "UserStep"
      },
      "customerId": {
        "customerId": "99999",
        "tenantName": "DEMO"
      },
      "guid": "3f9c2a1e-8b7d-4c6e-a5f4-1d2b3c4e5f60",
      "objectNumber": "ER-2026-00042",
      "objectType": "transaction",
      "overviewField1": {
        "label": "Lieferant",
        "name": "partnerCompany",
        "value": "Nordlicht IT-Distribution GmbH"
      },
      "overviewField2": {
        "label": "Brutto",
        "name": "grossTotal",
        "value": "6911.52"
      },
      "startTime": "2026-11-17T08:41:12Z",
      "workflowState": "OPEN"
    }
  ],
  "total": 1
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/workflow/v1/tasks' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Get a task with its current trade transaction (tenant:access)

`GET /api/workflow/v1/tasks/{instanceId}`

Module: Workflow · operationId: `getTask` · Tag: Tasks · Auth: access token (`Authorization: Bearer <accessToken>`)

Every holder of `tenant:access` in the tenant can read any instance's details; `readOnly` tells
whether the caller can work on it (assigned and not `RETRYING_SYNC`). `document` is the trade
transaction as trade has it now (omitted if trade cannot be reached); `pdfUrl` is set when the
transaction has a document and the caller holds `tenant:dms:read`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `instanceId` | path | string (uuid) | yes | Instance id (`guid`) |

### Responses

- **200** Task details (`application/json`)
- **401** Missing or invalid token (`unauthorized`) (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `blueprintId` (string): Id of the instance's blueprint
- `currentStepConfig` (Step)
  - `name` (string, required): Unique within the blueprint; referenced by `nextSteps[].step`
  - `stepType` (string, required): `UserStep` (a person decides) or `SystemStep` (the engine decides) (one of `UserStep`, `SystemStep`)
  - `action` (string): Outcome when the workflow ends after this step: `approve` → APPROVED, `reject` → REJECTED (German synonyms accepted), else COMPLETED
  - `allowInquiry` (boolean): The assignee may ask another person (inquiry)
  - `fields` (array of Field): Fields shown in a user step
    - `name` (string, required): Trade field (`GET /blueprints/fields`), `typeData.<key>`, `lines.<field>`, or a workflow-local input field
    - `editable` (boolean): The user may change it; trade fields only if listed as editable
    - `label` (string): Label shown in the step
    - `required` (boolean): The user must fill it in to complete the step
    - `visible` (boolean, nullable): Whether the field is shown; null means visible
  - `group` (string): HR group UUID the user step is assigned to (required for user steps)
  - `lines` (LineActions): Line actions of a user step besides editing line fields
    - `allowDelete` (boolean): The user may delete lines
    - `allowDuplicate` (boolean): The user may duplicate lines
  - `nextSteps` (array of NextStep): Transitions: buttons of a user step, conditions of a system step
    - `color` (string): Button color of a user step transition
    - `condition` (string): System steps: expr condition, or `default`
    - `icon` (string): Button icon of a user step transition
    - `label` (string): Button label of a user step transition
    - `step` (string): Name of the target step
  - `notificationEmail` (string): E-mail address notified about this step
  - `notifyAssigneesByEmail` (boolean): E-mail the assignees (the step's user, else its group's members) when the task waits; user steps only
  - `notifyAssigneesByTeams` (boolean): Notify the assignees in their personal Teams chat; user steps only
  - `teamsChannel` (string): Comms webhook channel id notified about this step (see `GET /channels`)
  - `teamsWebhookUrl` (string): Legacy: a Teams webhook URL; saving moves it into a comms channel (`teamsChannel`)
  - `user` (string): E-mail of a person the user step is additionally assigned to
- `document` (object): The trade transaction now, with `lines` and `typeData` (field names as in `GET /blueprints/fields`)
- `instance` (WorkflowInstance)
  - `blueprint` (Blueprint): A workflow definition. In responses, set webhook URLs are replaced by `********`.
    - `id` (string, required): Free identifier, unique per tenant
    - `steps` (array of Step, required): Steps of the workflow; the first one runs unless trigger.nextStep names another
    - `trigger` (Trigger, required)
      - `objectType` (string, required): The only supported object type (one of `transaction`)
      - `condition` (string): Optional expr condition over the transaction data; false ends the start as `TRIGGER_NOT_MATCHED`
      - `nextStep` (NextStep)
      - `statuses` (array of string): Trade statuses that start the workflow
      - `transactionTypes` (array of string): Trade transaction type codes (active in trade)
    - `active` (boolean): Only active blueprints start workflows; missing means active
    - `inquiryWebhookUrl` (string): Webhook (JSON) notified about inquiries and their answers; `********` keeps the stored URL
    - `overviewField1` (OverviewField)
      - `label` (string): Column label
      - `name` (string): Transaction field shown in task lists
    - `overviewField2` (OverviewField)
      - `label` (string): Column label
      - `name` (string): Transaction field shown in task lists
    - `updatedAt` (string (date-time), read-only): Last modification of the stored blueprint
    - `version` (integer (int64)): Informational; set to 1 when 0 on save
  - `claimedAt` (string (date-time)): When the task was claimed; omitted if unclaimed
  - `claimedBy` (string): E-mail of the person working on the task, empty if unclaimed
  - `currentStep` (Step | null): Null once the workflow has ended
  - `customerId` (TenantRef)
    - `customerId` (string): Customer number
    - `tenantName` (string): Tenant name
  - `data` (object): Transaction data at start, start metadata (`blueprintId`, `objectNumber`, `initialNote`, …), workflow-local input and open inquiry keys (`inquiry_to`, `inquiry_text`, …)
  - `endTime` (string (date-time)): When the instance ended; omitted while running
  - `guid` (string (uuid)): Instance id
  - `history` (array of HistoryEntry): Append-only history, oldest first
    - `action` (string): Free text, e.g. `Step completed`, `CLAIMED`, `UNCLAIMED`, `FORCE_PULLED`, `NOTE`, `CANCELLED`, `Rückfrage gestellt`
    - `actor` (string): E-mail of the person, or `SYSTEM`
    - `branch` (string): `regular` or `inquiry`
    - `changes` (ChangeSetDiff)
    - `color` (string): Color of the chosen transition button
    - `comment` (string): Comment, note text or inquiry answer
    - `group` (string): HR group UUID of the step
    - `icon` (string): Icon of the chosen transition button
    - `nextStep` (string): Name of the step the transition led to
    - `stepName` (string): Step the entry belongs to (`START`/`END` for the start and end of the workflow)
    - `timestamp` (string (date-time)): When it happened
    - `user` (string): E-mail of the person the step was assigned to
  - `lastRetryAt` (string (date-time)): Last automatic retry; omitted if none
  - `objectNumber` (string): Transaction number
  - `objectType` (string): Object type of the trigger
  - `retryCount` (integer): Attempts of a pending trade start or write-back
  - `revision` (integer (int64)): Optimistic-lock counter
  - `startTime` (string (date-time)): When the instance started
  - `transactionId` (string (uuid)): Trade transaction id
  - `workflowState` (WorkflowState): (one of `OPEN`, `RETRYING_SYNC`, `APPROVED`, `REJECTED`, `COMPLETED`, `CANCELLED`, `TRIGGER_NOT_MATCHED`, `TECHNICALLY_FAILED`)
- `pdfUrl` (string): Path of the task document
- `readOnly` (boolean): True when the caller cannot work on the task

Example 200 answer:

```json
{
  "blueprintId": "er-freigabe",
  "currentStepConfig": {
    "allowInquiry": true,
    "fields": [
      {
        "label": "Eingangsnr.",
        "name": "transactionNumber"
      },
      {
        "label": "Rechnungsnummer",
        "name": "externalTransactionNumber"
      },
      {
        "label": "Lieferant",
        "name": "partnerCompany"
      },
      {
        "editable": true,
        "label": "Fällig am",
        "name": "dueDate"
      },
      {
        "label": "Brutto",
        "name": "grossTotal"
      },
      {
        "label": "Bezeichnung",
        "name": "lines.name"
      },
      {
        "editable": true,
        "label": "Kostenstelle",
        "name": "lines.lineData.costCenter",
        "required": true
      },
      {
        "label": "Menge",
        "name": "lines.quantity"
      }
    ],
    "group": "4e7a1c2b-9f3d-4b8a-a6e1-5c0d2f8b3a71",
    "lines": {
      "allowDelete": true,
      "allowDuplicate": true
    },
    "name": "kontierung",
    "nextSteps": [
      {
        "color": "primary",
        "icon": "i-lucide-arrow-right",
        "label": "Weiter zur Freigabe",
        "step": "freigabe"
      },
      {
        "color": "error",
        "icon": "i-lucide-x-circle",
        "label": "Ablehnen",
        "step": "abgelehnt"
      }
    ],
    "notifyAssigneesByEmail": true,
    "stepType": "UserStep"
  },
  "document": {
    "documentDate": "2026-09-30",
    "dueDate": "2026-10-30",
    "externalTransactionNumber": "RE-482117",
    "grossTotal": 6911.52,
    "id": "8c2f4a6e-0b1d-4e3f-9a5c-7e9b1d3f5a7c",
    "lines": [
      {
        "articleNumber": "HW-1001",
        "id": "7d2e9a41-3b6c-4f0e-8a15-c9b2d4e6f801",
        "lineData": {
          "costCenter": "4100"
        },
        "name": "Notebook ProBook 14 G10, i5, 16 GB, 512 GB SSD",
        "position": 1,
        "quantity": 6,
        "taxRate": 19,
        "totalPriceNet": 4974,
        "unitPriceNet": 829
      },
      {
        "articleNumber": "HW-1004",
        "id": "1a3c5e7b-9d2f-4b4a-8c6e-0f2a4c6e8b0d",
        "lineData": {
          "costCenter": "4100"
        },
        "name": "USB-C Dockingstation 100 W",
        "position": 2,
        "quantity": 6,
        "taxRate": 19,
        "totalPriceNet": 834,
        "unitPriceNet": 139
      }
    ],
    "netTotal": 5808,
    "partnerCompany": "Nordlicht IT-Distribution GmbH",
    "transactionNumber": "ER-2026-00042",
    "transactionType": "INBOUND_INVOICE",
    "typeData": {}
  },
  "instance": {
    "blueprint": {
      "active": true,
      "id": "er-freigabe",
      "overviewField1": {
        "label": "Lieferant",
        "name": "partnerCompany"
      },
      "overviewField2": {
        "label": "Brutto",
        "name": "grossTotal"
      },
      "steps": [
        {
          "allowInquiry": true,
          "fields": [
            {
              "label": "Eingangsnr.",
              "name": "transactionNumber"
            },
            {
              "label": "Rechnungsnummer",
              "name": "externalTransactionNumber"
            },
            {
              "label": "Lieferant",
              "name": "partnerCompany"
            },
            {
              "editable": true,
              "label": "Fällig am",
              "name": "dueDate"
            },
            {
              "label": "Brutto",
              "name": "grossTotal"
            },
            {
              "label": "Bezeichnung",
              "name": "lines.name"
            },
            {
              "editable": true,
              "label": "Kostenstelle",
              "name": "lines.lineData.costCenter",
              "required": true
            },
            {
              "label": "Menge",
              "name": "lines.quantity"
            }
          ],
          "group": "4e7a1c2b-9f3d-4b8a-a6e1-5c0d2f8b3a71",
          "lines": {
            "allowDelete": true,
            "allowDuplicate": true
          },
          "name": "kontierung",
          "nextSteps": [
            {
              "color": "primary",
              "icon": "i-lucide-arrow-right",
              "label": "Weiter zur Freigabe",
              "step": "freigabe"
            },
            {
              "color": "error",
              "icon": "i-lucide-x-circle",
              "label": "Ablehnen",
              "step": "abgelehnt"
            }
          ],
          "notifyAssigneesByEmail": true,
          "stepType": "UserStep"
        },
        {
          "allowInquiry": true,
          "fields": [
            {
              "label": "Eingangsnr.",
              "name": "transactionNumber"
            },
            {
              "label": "Lieferant",
              "name": "partnerCompany"
            },
            {
              "label": "Brutto",
              "name": "grossTotal"
            }
          ],
          "group": "4e7a1c2b-9f3d-4b8a-a6e1-5c0d2f8b3a71",
          "name": "freigabe",
          "nextSteps": [
            {
              "color": "success",
              "icon": "i-lucide-check-circle",
              "label": "Freigeben",
              "step": "freigegeben"
            },
            {
              "color": "warning",
              "icon": "i-lucide-undo-2",
              "label": "Zurück zur Kontierung",
              "step": "kontierung"
            },
            {
              "color": "error",
              "icon": "i-lucide-x-circle",
              "label": "Ablehnen",
              "step": "abgelehnt"
            }
          ],
          "stepType": "UserStep"
        },
        {
          "action": "approve",
          "name": "freigegeben",
          "stepType": "SystemStep"
        },
        {
          "action": "reject",
          "name": "abgelehnt",
          "stepType": "SystemStep"
        }
      ],
      "trigger": {
        "nextStep": {
          "step": "kontierung"
        },
        "objectType": "transaction",
        "statuses": [
          "MATCHED"
        ],
        "transactionTypes": [
          "INBOUND_INVOICE"
        ]
      },
      "updatedAt": "2026-10-14T13:22:05Z",
      "version": 3
    },
    "claimedAt": "2026-11-17T09:05:40Z",
    "claimedBy": "christina.adler@muster-it.example",
    "currentStep": {
      "allowInquiry": true,
      "fields": [
        {
          "label": "Eingangsnr.",
          "name": "transactionNumber"
        },
        {
          "label": "Rechnungsnummer",
          "name": "externalTransactionNumber"
        },
        {
          "label": "Lieferant",
          "name": "partnerCompany"
        },
        {
          "editable": true,
          "label": "Fällig am",
          "name": "dueDate"
        },
        {
          "label": "Brutto",
          "name": "grossTotal"
        },
        {
          "label": "Bezeichnung",
          "name": "lines.name"
        },
        {
          "editable": true,
          "label": "Kostenstelle",
          "name": "lines.lineData.costCenter",
          "required": true
        },
        {
          "label": "Menge",
          "name": "lines.quantity"
        }
      ],
      "group": "4e7a1c2b-9f3d-4b8a-a6e1-5c0d2f8b3a71",
      "lines": {
        "allowDelete": true,
        "allowDuplicate": true
      },
      "name": "kontierung",
      "nextSteps": [
        {
          "color": "primary",
          "icon": "i-lucide-arrow-right",
          "label": "Weiter zur Freigabe",
          "step": "freigabe"
        },
        {
          "color": "error",
          "icon": "i-lucide-x-circle",
          "label": "Ablehnen",
          "step": "abgelehnt"
        }
      ],
      "notifyAssigneesByEmail": true,
      "stepType": "UserStep"
    },
    "customerId": {
      "customerId": "99999",
      "tenantName": "DEMO"
    },
    "data": {
      "blueprintId": "er-freigabe",
      "externalTransactionNumber": "RE-482117",
      "grossTotal": 6911.52,
      "netTotal": 5808,
      "objectNumber": "ER-2026-00042",
      "partnerCompany": "Nordlicht IT-Distribution GmbH",
      "transactionNumber": "ER-2026-00042"
    },
    "guid": "3f9c2a1e-8b7d-4c6e-a5f4-1d2b3c4e5f60",
    "history": [
      {
        "action": "Workflow started",
        "actor": "SYSTEM",
        "nextStep": "kontierung",
        "stepName": "START",
        "timestamp": "2026-11-17T08:41:12Z"
      },
      {
        "action": "CLAIMED",
        "actor": "christina.adler@muster-it.example",
        "group": "4e7a1c2b-9f3d-4b8a-a6e1-5c0d2f8b3a71",
        "stepName": "kontierung",
        "timestamp": "2026-11-17T09:05:40Z"
      }
    ],
    "objectNumber": "ER-2026-00042",
    "objectType": "transaction",
    "retryCount": 0,
    "revision": 2,
    "startTime": "2026-11-17T08:41:12Z",
    "transactionId": "8c2f4a6e-0b1d-4e3f-9a5c-7e9b1d3f5a7c",
    "workflowState": "OPEN"
  },
  "pdfUrl": "/api/workflow/v1/tasks/3f9c2a1e-8b7d-4c6e-a5f4-1d2b3c4e5f60/document",
  "readOnly": false
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/workflow/v1/tasks/3f9c2a1e-8b7d-4c6e-a5f4-1d2b3c4e5f60' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Get the object an instance belongs to (tenant:access)

`GET /api/workflow/v1/tasks/{instanceId}/metadata`

Module: Workflow · operationId: `getTaskMetadata` · Tag: Tasks · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `instanceId` | path | string (uuid) | yes | Instance id (`guid`) |

### Responses

- **200** Metadata (`application/json`)
- **401** Missing or invalid token (`unauthorized`) (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `guid` (string (uuid)): Instance id
- `objectNumber` (string): Transaction number
- `objectType` (string): Object type of the trigger

Example 200 answer:

```json
{
  "guid": "3f9c2a1e-8b7d-4c6e-a5f4-1d2b3c4e5f60",
  "objectNumber": "ER-2026-00042",
  "objectType": "transaction"
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/workflow/v1/tasks/3f9c2a1e-8b7d-4c6e-a5f4-1d2b3c4e5f60/metadata' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Complete the current step of a task, or ask, answer or pull back an inquiry (tenant:access)

`POST /api/workflow/v1/tasks/{instanceId}/complete`

Module: Workflow · operationId: `completeTask` · Tag: Tasks · Auth: access token (`Authorization: Bearer <accessToken>`)

The body is the step's input. `action` selects what happens:
- the `step` or `label` of one of the current step's `nextSteps`: the step is completed and the
  workflow moves on (an empty action ends the workflow);
- `INQUIRY`: ask `inquiry_to` (an e-mail from `GET /users`) the question `inquiry_text`; only in
  steps with `allowInquiry`;
- `FORCE_PULL_INQUIRY`: the sender pulls an open inquiry back;
- the inquiry recipient answers with `comment` (and an empty `action` or `ANSWER_INQUIRY`).

`changes` carries the trade changes the step allows (its `editable` fields and line actions); they
are written to trade before the step is saved (`422 trade_rejected` if trade refuses them, `502
trade_unavailable` if trade fails; changes beyond what the step allows are `422 invalid_changes`) and recorded
in the history entry. Other keys are stored in the instance data (trade field names are dropped).
The caller must be assigned (`403 not_assigned`); a task claimed by someone else needs to be claimed first
(`409 claimed_by_other`).
Completing an unclaimed task claims it. While workflows are switched off for the tenant, the call
answers `200` without changing anything.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `instanceId` | path | string (uuid) | yes | Instance id (`guid`) |

### Request body

`application/json` (required)

- `action` (string): Target `step` or `label` of a transition, or `INQUIRY`, `FORCE_PULL_INQUIRY`, `ANSWER_INQUIRY`
- `changes` (ChangeSet): Trade changes of a user step. Field names as in the step's fields; line fields without the `lines.` prefix.
  - `delete` (array of string): Line ids to delete (needs `lines.allowDelete`)
  - `duplicate` (array of object): Copies of existing lines (needs `lines.allowDuplicate`)
    - `sourceLineId` (string, required): Id of the line to copy
    - `tempId` (string, required): Client id of the copy
    - `values` (object): Values overriding the copy's
  - `header` (object): Transaction fields to set
  - `lines` (array of object): Changed field values of existing lines
    - `id` (string, required): Line id
    - `values` (object, required): Line fields to set
- `comment` (string): Comment of the history entry, or the answer to an inquiry
- `inquiry_text` (string): With `INQUIRY`: the question
- `inquiry_to` (string (email)): With `INQUIRY`: the recipient

Example:

```json
{
  "comment": "Ja, mit dem Kunden vereinbart."
}
```

### Responses

- **200** Done (no body)
- **400** Error (`application/json`)
- **401** Missing or invalid token (`unauthorized`) (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)
- **422** Error (`application/json`)
- **500** Error (`application/json`)
- **502** Error (`application/json`)

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/workflow/v1/tasks/3f9c2a1e-8b7d-4c6e-a5f4-1d2b3c4e5f60/complete' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"comment":"Ja, mit dem Kunden vereinbart."}'
```

## Preview what a step's trade changes would do, without saving (tenant:access)

`POST /api/workflow/v1/tasks/{instanceId}/preview`

Module: Workflow · operationId: `previewTaskChanges` · Tag: Tasks · Auth: access token (`Authorization: Bearer <accessToken>`)

Trade recalculates the transaction (totals, lines) with `changes`; nothing is stored. Only the
caller who may complete the open task (assigned, not claimed by someone else) gets a preview,
with the changes the current step allows (`400` otherwise).

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `instanceId` | path | string (uuid) | yes | Instance id (`guid`) |

### Request body

`application/json` (required)

- `changes` (ChangeSet): Trade changes of a user step. Field names as in the step's fields; line fields without the `lines.` prefix.
  - `delete` (array of string): Line ids to delete (needs `lines.allowDelete`)
  - `duplicate` (array of object): Copies of existing lines (needs `lines.allowDuplicate`)
    - `sourceLineId` (string, required): Id of the line to copy
    - `tempId` (string, required): Client id of the copy
    - `values` (object): Values overriding the copy's
  - `header` (object): Transaction fields to set
  - `lines` (array of object): Changed field values of existing lines
    - `id` (string, required): Line id
    - `values` (object, required): Line fields to set

Example:

```json
{
  "changes": {
    "duplicate": [
      {
        "sourceLineId": "7d2e9a41-3b6c-4f0e-8a15-c9b2d4e6f801",
        "tempId": "new-1"
      }
    ],
    "lines": [
      {
        "id": "7d2e9a41-3b6c-4f0e-8a15-c9b2d4e6f801",
        "values": {
          "quantity": 12
        }
      }
    ]
  }
}
```

### Responses

- **200** Preview (`application/json`)
- **400** Error (`application/json`)
- **401** Missing or invalid token (`unauthorized`) (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)
- **422** Error (`application/json`)
- **502** Error (`application/json`)

Fields of the 200 answer:

- `diff` (ChangeSetDiff): What trade changed, with old values
  - `added` (array of LineSnapshot): Lines added by duplicating
    - `lineId` (string): Trade line id
    - `position` (integer): Position of the line in the transaction
    - `sourceLineId` (string): Line a duplicate was copied from
    - `tempId` (string): Client id of a duplicated line (`ChangeSet.duplicate[].tempId`)
    - `values` (object): Line field values
  - `changeSetId` (string): Id of the applied change set (instance:revision:content hash)
  - `deleted` (array of LineSnapshot): Lines deleted, with their old values
    - `lineId` (string): Trade line id
    - `position` (integer): Position of the line in the transaction
    - `sourceLineId` (string): Line a duplicate was copied from
    - `tempId` (string): Client id of a duplicated line (`ChangeSet.duplicate[].tempId`)
    - `values` (object): Line field values
  - `header` (array of FieldChange): Changed transaction fields
    - `field` (string): Field name
    - `label` (string): Label of the field in the step
    - `new` (any): New value
    - `old` (any): Previous value
  - `lines` (array of object): Changed fields of existing lines
    - `changes` (array of FieldChange): Changed fields of the line
    - `lineId` (string): Trade line id
    - `position` (integer): Position of the line in the transaction
  - `totals` (object): Transaction totals before and after the changes
    - `new` (Totals)
      - `gross` (number): Gross total
      - `net` (number): Net total
      - `tax` (number): Tax total
    - `old` (Totals)
      - `gross` (number): Gross total
      - `net` (number): Net total
      - `tax` (number): Tax total
- `document` (object): The recalculated transaction, shaped like `TaskDetails.document`

Example 200 answer:

```json
{
  "diff": {
    "added": [
      {
        "position": 3,
        "sourceLineId": "7d2e9a41-3b6c-4f0e-8a15-c9b2d4e6f801",
        "tempId": "new-1",
        "values": {
          "articleNumber": "HW-1001",
          "quantity": 0
        }
      }
    ],
    "changeSetId": "3f9c2a1e-8b7d-4c6e-a5f4-1d2b3c4e5f60:2:9b1e4c",
    "deleted": [],
    "header": [],
    "lines": [
      {
        "changes": [
          {
            "field": "quantity",
            "label": "Menge",
            "new": 7,
            "old": 6
          }
        ],
        "lineId": "7d2e9a41-3b6c-4f0e-8a15-c9b2d4e6f801",
        "position": 1
      }
    ],
    "totals": {
      "new": {
        "gross": 7898.03,
        "net": 6637,
        "tax": 1261.03
      },
      "old": {
        "gross": 6911.52,
        "net": 5808,
        "tax": 1103.52
      }
    }
  },
  "document": {
    "grossTotal": 7898.03,
    "id": "8c2f4a6e-0b1d-4e3f-9a5c-7e9b1d3f5a7c",
    "netTotal": 6637,
    "transactionNumber": "ER-2026-00042"
  }
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/workflow/v1/tasks/3f9c2a1e-8b7d-4c6e-a5f4-1d2b3c4e5f60/preview' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"changes":{"duplicate":[{"sourceLineId":"7d2e9a41-3b6c-4f0e-8a15-c9b2d4e6f801","tempId":"new-1"}],"lines":[{"id":"7d2e9a41-3b6c-4f0e-8a15-c9b2d4e6f801","values":{"quantity":12}}]}}'
```

## Add a note to a task's history (tenant:access)

`POST /api/workflow/v1/tasks/{instanceId}/note`

Module: Workflow · operationId: `addTaskNote` · Tag: Tasks · Auth: access token (`Authorization: Bearer <accessToken>`)

Records a note (history action `NOTE`) without changing the step. The task must be `OPEN` (`409
invalid_state`), assigned to the caller (`403 not_assigned`) and not claimed by someone else (`409
claimed_by_other`); a blank or too long note is `400 invalid` with `field: note`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `instanceId` | path | string (uuid) | yes | Instance id (`guid`) |

### Request body

`application/json` (required)

- `note` (string, required): Trimmed; must not be blank. The limit counts characters. (max length 4000)

Example:

```json
{
  "note": "Lieferant hat telefonisch bestätigt."
}
```

### Responses

- **200** Saved (`application/json`)
- **400** Error (`application/json`)
- **401** Missing or invalid token (`unauthorized`) (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)
- **500** Error (`application/json`)

Fields of the 200 answer:

- `message` (string): Confirmation text
- `status` (string): Always `ok`

Example 200 answer:

```json
{
  "message": "Hinweis erfolgreich hinzugefügt",
  "status": "ok"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/workflow/v1/tasks/3f9c2a1e-8b7d-4c6e-a5f4-1d2b3c4e5f60/note' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"note":"Lieferant hat telefonisch bestätigt."}'
```

## Claim a task (tenant:access)

`POST /api/workflow/v1/tasks/{instanceId}/claim`

Module: Workflow · operationId: `claimTask` · Tag: Tasks · Auth: access token (`Authorization: Bearer <accessToken>`)

The caller takes the open task assigned to them (history action `CLAIMED`). A task claimed by
someone else is `409 claimed_by_other`, a task that is not open `409 invalid_state`, a busy instance
`409 locked`, a task not assigned to the caller `403 not_assigned`, an unknown one `404`. If the
caller is the recipient of an open inquiry, the inquiry is closed.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `instanceId` | path | string (uuid) | yes | Instance id (`guid`) |

### Responses

- **200** Claimed (no body)
- **401** Missing or invalid token (`unauthorized`) (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/workflow/v1/tasks/3f9c2a1e-8b7d-4c6e-a5f4-1d2b3c4e5f60/claim' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Release the caller's claim on a task (tenant:access)

`POST /api/workflow/v1/tasks/{instanceId}/unclaim`

Module: Workflow · operationId: `unclaimTask` · Tag: Tasks · Auth: access token (`Authorization: Bearer <accessToken>`)

Returns the task to its group (history action `UNCLAIMED`); an unclaimed task stays as it is. A claim of someone else answers `409 claimed_by_other`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `instanceId` | path | string (uuid) | yes | Instance id (`guid`) |

### Responses

- **200** Released (no body)
- **401** Missing or invalid token (`unauthorized`) (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/workflow/v1/tasks/3f9c2a1e-8b7d-4c6e-a5f4-1d2b3c4e5f60/unclaim' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Release anyone's claim on a task (tenant:settings:write)

`POST /api/workflow/v1/tasks/{instanceId}/force-unclaim`

Module: Workflow · operationId: `forceUnclaimTask` · Tag: Tasks · Auth: access token (`Authorization: Bearer <accessToken>`)

The caller must also be assigned to the task (`403 not_assigned` otherwise). History action `FORCE_PULLED`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `instanceId` | path | string (uuid) | yes | Instance id (`guid`) |

### Responses

- **200** Released (no body)
- **401** Missing or invalid token (`unauthorized`) (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/workflow/v1/tasks/3f9c2a1e-8b7d-4c6e-a5f4-1d2b3c4e5f60/force-unclaim' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Download the document of a task's transaction (tenant:access and tenant:dms:read)

`GET /api/workflow/v1/tasks/{instanceId}/document`

Module: Workflow · operationId: `getTaskDocument` · Tag: Tasks · Auth: access token (`Authorization: Bearer <accessToken>`)

Streams the DMS document of the instance's trade transaction (`Content-Disposition: inline`,
`Cache-Control: private, no-store`). Types other than PDF and raster images are served with a
sandboxing `Content-Security-Policy`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `instanceId` | path | string (uuid) | yes | Instance id (`guid`) |

### Responses

- **200** The document (`application/octet-stream`)
- **401** Missing or invalid token (`unauthorized`) (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **503** Error (`application/json`)

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/workflow/v1/tasks/3f9c2a1e-8b7d-4c6e-a5f4-1d2b3c4e5f60/document' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

# Instances

## Start a workflow for a transaction manually (tenant:settings:write)

`POST /api/workflow/v1/trigger`

Module: Workflow · operationId: `triggerWorkflow` · Tag: Instances · Auth: access token (`Authorization: Bearer <accessToken>`)

Starts the active blueprint `blueprintId` for one trade transaction, as polling would. The
transaction is given by `transactionId` (UUID) or, as a fallback, by its number (`objectNumber`),
which must match exactly one transaction of the blueprint's transaction types. A running workflow
locks the transaction in trade.

- `200`: the workflow runs (`OPEN`).
- `204`: the start was accepted but nothing runs: it ended at start (`TRIGGER_NOT_MATCHED`,
  `TECHNICALLY_FAILED`), it is waiting for trade (`RETRYING_SYNC`, retried automatically), or a
  workflow of the blueprint already runs for the transaction.
- `400`: nothing was started – workflows are off, the blueprint is unknown or switched off, the
  transaction was not found or does not match the trigger, or another start of it is in progress.

### Request body

`application/json` (required)

- `blueprintId` (string, required): Blueprint id
- `initialNote` (string): Note stored in the instance data as `initialNote`
- `objectNumber` (string): Transaction number, used when transactionId is empty
- `transactionId` (string (uuid)): Trade transaction id

Example:

```json
{
  "blueprintId": "angebot-pruefung",
  "initialNote": "Bitte bis Freitag prüfen",
  "transactionId": "0b6f3c2e-5d4a-4e1b-9a7c-2f8d1e6b4c90"
}
```

### Responses

- **200** Started and running (no body)
- **204** Accepted, but no running workflow resulted
- **400** Error (`application/json`)
- **401** Missing or invalid token (`unauthorized`) (`application/json`)
- **403** Error (`application/json`)
- **422** Nothing started (`nothing_to_start`): workflows are off, the blueprint or transaction is unknown, or a start is in progress (`application/json`)
- **500** Error (`application/json`)

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/workflow/v1/trigger' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"blueprintId":"angebot-pruefung","initialNote":"Bitte bis Freitag prüfen","transactionId":"0b6f3c2e-5d4a-4e1b-9a7c-2f8d1e6b4c90"}'
```

## List the instances of a transaction number (tenant:access)

`GET /api/workflow/v1/tasks/object/{objectNumber}`

Module: Workflow · operationId: `listInstancesByObject` · Tag: Instances · Auth: access token (`Authorization: Bearer <accessToken>`)

All instances of the tenant for the object (transaction) number, in any state and regardless of assignment.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `objectNumber` | path | string | yes | Transaction number |

### Responses

- **200** Instances (`application/json`)
- **401** Missing or invalid token (`unauthorized`) (`application/json`)
- **403** Error (`application/json`)
- **500** Error (`application/json`)

Fields of the 200 answer:

- `items` (array of TaskListItem, required): Items of the list
- `total` (integer): Number of items

Example 200 answer:

```json
{
  "items": [
    {
      "blueprint": {
        "active": true,
        "id": "er-freigabe",
        "overviewField1": {
          "label": "Lieferant",
          "name": "partnerCompany"
        },
        "overviewField2": {
          "label": "Brutto",
          "name": "grossTotal"
        },
        "steps": [
          {
            "allowInquiry": true,
            "fields": [
              {
                "label": "Eingangsnr.",
                "name": "transactionNumber"
              },
              {
                "label": "Rechnungsnummer",
                "name": "externalTransactionNumber"
              },
              {
                "label": "Lieferant",
                "name": "partnerCompany"
              },
              {
                "editable": true,
                "label": "Fällig am",
                "name": "dueDate"
              },
              {
                "label": "Brutto",
                "name": "grossTotal"
              },
              {
                "label": "Bezeichnung",
                "name": "lines.name"
              },
              {
                "editable": true,
                "label": "Kostenstelle",
                "name": "lines.lineData.costCenter",
                "required": true
              },
              {
                "label": "Menge",
                "name": "lines.quantity"
              }
            ],
            "group": "4e7a1c2b-9f3d-4b8a-a6e1-5c0d2f8b3a71",
            "lines": {
              "allowDelete": true,
              "allowDuplicate": true
            },
            "name": "kontierung",
            "nextSteps": [
              {
                "color": "primary",
                "icon": "i-lucide-arrow-right",
                "label": "Weiter zur Freigabe",
                "step": "freigabe"
              },
              {
                "color": "error",
                "icon": "i-lucide-x-circle",
                "label": "Ablehnen",
                "step": "abgelehnt"
              }
            ],
            "notifyAssigneesByEmail": true,
            "stepType": "UserStep"
          },
          {
            "allowInquiry": true,
            "fields": [
              {
                "label": "Eingangsnr.",
                "name": "transactionNumber"
              },
              {
                "label": "Lieferant",
                "name": "partnerCompany"
              },
              {
                "label": "Brutto",
                "name": "grossTotal"
              }
            ],
            "group": "4e7a1c2b-9f3d-4b8a-a6e1-5c0d2f8b3a71",
            "name": "freigabe",
            "nextSteps": [
              {
                "color": "success",
                "icon": "i-lucide-check-circle",
                "label": "Freigeben",
                "step": "freigegeben"
              },
              {
                "color": "warning",
                "icon": "i-lucide-undo-2",
                "label": "Zurück zur Kontierung",
                "step": "kontierung"
              },
              {
                "color": "error",
                "icon": "i-lucide-x-circle",
                "label": "Ablehnen",
                "step": "abgelehnt"
              }
            ],
            "stepType": "UserStep"
          },
          {
            "action": "approve",
            "name": "freigegeben",
            "stepType": "SystemStep"
          },
          {
            "action": "reject",
            "name": "abgelehnt",
            "stepType": "SystemStep"
          }
        ],
        "trigger": {
          "nextStep": {
            "step": "kontierung"
          },
          "objectType": "transaction",
          "statuses": [
            "MATCHED"
          ],
          "transactionTypes": [
            "INBOUND_INVOICE"
          ]
        },
        "updatedAt": "2026-10-14T13:22:05Z",
        "version": 3
      },
      "claimedAt": "2026-11-17T09:05:40Z",
      "claimedBy": "christina.adler@muster-it.example",
      "currentStep": {
        "allowInquiry": true,
        "fields": [
          {
            "label": "Eingangsnr.",
            "name": "transactionNumber"
          },
          {
            "label": "Rechnungsnummer",
            "name": "externalTransactionNumber"
          },
          {
            "label": "Lieferant",
            "name": "partnerCompany"
          },
          {
            "editable": true,
            "label": "Fällig am",
            "name": "dueDate"
          },
          {
            "label": "Brutto",
            "name": "grossTotal"
          },
          {
            "label": "Bezeichnung",
            "name": "lines.name"
          },
          {
            "editable": true,
            "label": "Kostenstelle",
            "name": "lines.lineData.costCenter",
            "required": true
          },
          {
            "label": "Menge",
            "name": "lines.quantity"
          }
        ],
        "group": "4e7a1c2b-9f3d-4b8a-a6e1-5c0d2f8b3a71",
        "lines": {
          "allowDelete": true,
          "allowDuplicate": true
        },
        "name": "kontierung",
        "nextSteps": [
          {
            "color": "primary",
            "icon": "i-lucide-arrow-right",
            "label": "Weiter zur Freigabe",
            "step": "freigabe"
          },
          {
            "color": "error",
            "icon": "i-lucide-x-circle",
            "label": "Ablehnen",
            "step": "abgelehnt"
          }
        ],
        "notifyAssigneesByEmail": true,
        "stepType": "UserStep"
      },
      "customerId": {
        "customerId": "99999",
        "tenantName": "DEMO"
      },
      "data": {
        "blueprintId": "er-freigabe",
        "externalTransactionNumber": "RE-482117",
        "grossTotal": 6911.52,
        "netTotal": 5808,
        "objectNumber": "ER-2026-00042",
        "partnerCompany": "Nordlicht IT-Distribution GmbH",
        "transactionNumber": "ER-2026-00042"
      },
      "guid": "3f9c2a1e-8b7d-4c6e-a5f4-1d2b3c4e5f60",
      "history": [
        {
          "action": "Workflow started",
          "actor": "SYSTEM",
          "nextStep": "kontierung",
          "stepName": "START",
          "timestamp": "2026-11-17T08:41:12Z"
        },
        {
          "action": "CLAIMED",
          "actor": "christina.adler@muster-it.example",
          "group": "4e7a1c2b-9f3d-4b8a-a6e1-5c0d2f8b3a71",
          "stepName": "kontierung",
          "timestamp": "2026-11-17T09:05:40Z"
        }
      ],
      "objectNumber": "ER-2026-00042",
      "objectType": "transaction",
      "overviewField1": {
        "label": "Lieferant",
        "name": "partnerCompany",
        "value": "Nordlicht IT-Distribution GmbH"
      },
      "overviewField2": {
        "label": "Brutto",
        "name": "grossTotal",
        "value": "6911.52"
      },
      "revision": 2,
      "startTime": "2026-11-17T08:41:12Z",
      "transactionId": "8c2f4a6e-0b1d-4e3f-9a5c-7e9b1d3f5a7c",
      "workflowState": "OPEN"
    }
  ],
  "total": 1
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/workflow/v1/tasks/object/AN-2026-00042' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Get the blueprint snapshot an instance runs on (tenant:access)

`GET /api/workflow/v1/tasks/{instanceId}/blueprint`

Module: Workflow · operationId: `getInstanceBlueprint` · Tag: Instances · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `instanceId` | path | string (uuid) | yes | Instance id (`guid`) |

### Responses

- **200** Blueprint snapshot, webhook URLs redacted (`application/json`)
- **401** Missing or invalid token (`unauthorized`) (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `id` (string, required): Free identifier, unique per tenant
- `steps` (array of Step, required): Steps of the workflow; the first one runs unless trigger.nextStep names another
  - `name` (string, required): Unique within the blueprint; referenced by `nextSteps[].step`
  - `stepType` (string, required): `UserStep` (a person decides) or `SystemStep` (the engine decides) (one of `UserStep`, `SystemStep`)
  - `action` (string): Outcome when the workflow ends after this step: `approve` → APPROVED, `reject` → REJECTED (German synonyms accepted), else COMPLETED
  - `allowInquiry` (boolean): The assignee may ask another person (inquiry)
  - `fields` (array of Field): Fields shown in a user step
    - `name` (string, required): Trade field (`GET /blueprints/fields`), `typeData.<key>`, `lines.<field>`, or a workflow-local input field
    - `editable` (boolean): The user may change it; trade fields only if listed as editable
    - `label` (string): Label shown in the step
    - `required` (boolean): The user must fill it in to complete the step
    - `visible` (boolean, nullable): Whether the field is shown; null means visible
  - `group` (string): HR group UUID the user step is assigned to (required for user steps)
  - `lines` (LineActions): Line actions of a user step besides editing line fields
    - `allowDelete` (boolean): The user may delete lines
    - `allowDuplicate` (boolean): The user may duplicate lines
  - `nextSteps` (array of NextStep): Transitions: buttons of a user step, conditions of a system step
    - `color` (string): Button color of a user step transition
    - `condition` (string): System steps: expr condition, or `default`
    - `icon` (string): Button icon of a user step transition
    - `label` (string): Button label of a user step transition
    - `step` (string): Name of the target step
  - `notificationEmail` (string): E-mail address notified about this step
  - `notifyAssigneesByEmail` (boolean): E-mail the assignees (the step's user, else its group's members) when the task waits; user steps only
  - `notifyAssigneesByTeams` (boolean): Notify the assignees in their personal Teams chat; user steps only
  - `teamsChannel` (string): Comms webhook channel id notified about this step (see `GET /channels`)
  - `teamsWebhookUrl` (string): Legacy: a Teams webhook URL; saving moves it into a comms channel (`teamsChannel`)
  - `user` (string): E-mail of a person the user step is additionally assigned to
- `trigger` (Trigger, required)
  - `objectType` (string, required): The only supported object type (one of `transaction`)
  - `condition` (string): Optional expr condition over the transaction data; false ends the start as `TRIGGER_NOT_MATCHED`
  - `nextStep` (NextStep)
    - `color` (string): Button color of a user step transition
    - `condition` (string): System steps: expr condition, or `default`
    - `icon` (string): Button icon of a user step transition
    - `label` (string): Button label of a user step transition
    - `step` (string): Name of the target step
  - `statuses` (array of string): Trade statuses that start the workflow
  - `transactionTypes` (array of string): Trade transaction type codes (active in trade)
- `active` (boolean): Only active blueprints start workflows; missing means active
- `inquiryWebhookUrl` (string): Webhook (JSON) notified about inquiries and their answers; `********` keeps the stored URL
- `overviewField1` (OverviewField)
  - `label` (string): Column label
  - `name` (string): Transaction field shown in task lists
- `overviewField2` (OverviewField)
  - `label` (string): Column label
  - `name` (string): Transaction field shown in task lists
- `updatedAt` (string (date-time), read-only): Last modification of the stored blueprint
- `version` (integer (int64)): Informational; set to 1 when 0 on save

Example 200 answer:

```json
{
  "active": true,
  "id": "er-freigabe",
  "overviewField1": {
    "label": "Lieferant",
    "name": "partnerCompany"
  },
  "overviewField2": {
    "label": "Brutto",
    "name": "grossTotal"
  },
  "steps": [
    {
      "allowInquiry": true,
      "fields": [
        {
          "label": "Eingangsnr.",
          "name": "transactionNumber"
        },
        {
          "label": "Rechnungsnummer",
          "name": "externalTransactionNumber"
        },
        {
          "label": "Lieferant",
          "name": "partnerCompany"
        },
        {
          "editable": true,
          "label": "Fällig am",
          "name": "dueDate"
        },
        {
          "label": "Brutto",
          "name": "grossTotal"
        },
        {
          "label": "Bezeichnung",
          "name": "lines.name"
        },
        {
          "editable": true,
          "label": "Kostenstelle",
          "name": "lines.lineData.costCenter",
          "required": true
        },
        {
          "label": "Menge",
          "name": "lines.quantity"
        }
      ],
      "group": "4e7a1c2b-9f3d-4b8a-a6e1-5c0d2f8b3a71",
      "lines": {
        "allowDelete": true,
        "allowDuplicate": true
      },
      "name": "kontierung",
      "nextSteps": [
        {
          "color": "primary",
          "icon": "i-lucide-arrow-right",
          "label": "Weiter zur Freigabe",
          "step": "freigabe"
        },
        {
          "color": "error",
          "icon": "i-lucide-x-circle",
          "label": "Ablehnen",
          "step": "abgelehnt"
        }
      ],
      "notifyAssigneesByEmail": true,
      "stepType": "UserStep"
    },
    {
      "allowInquiry": true,
      "fields": [
        {
          "label": "Eingangsnr.",
          "name": "transactionNumber"
        },
        {
          "label": "Lieferant",
          "name": "partnerCompany"
        },
        {
          "label": "Brutto",
          "name": "grossTotal"
        }
      ],
      "group": "4e7a1c2b-9f3d-4b8a-a6e1-5c0d2f8b3a71",
      "name": "freigabe",
      "nextSteps": [
        {
          "color": "success",
          "icon": "i-lucide-check-circle",
          "label": "Freigeben",
          "step": "freigegeben"
        },
        {
          "color": "warning",
          "icon": "i-lucide-undo-2",
          "label": "Zurück zur Kontierung",
          "step": "kontierung"
        },
        {
          "color": "error",
          "icon": "i-lucide-x-circle",
          "label": "Ablehnen",
          "step": "abgelehnt"
        }
      ],
      "stepType": "UserStep"
    },
    {
      "action": "approve",
      "name": "freigegeben",
      "stepType": "SystemStep"
    },
    {
      "action": "reject",
      "name": "abgelehnt",
      "stepType": "SystemStep"
    }
  ],
  "trigger": {
    "nextStep": {
      "step": "kontierung"
    },
    "objectType": "transaction",
    "statuses": [
      "MATCHED"
    ],
    "transactionTypes": [
      "INBOUND_INVOICE"
    ]
  },
  "updatedAt": "2026-10-14T13:22:05Z",
  "version": 3
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/workflow/v1/tasks/3f9c2a1e-8b7d-4c6e-a5f4-1d2b3c4e5f60/blueprint' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Cancel a running workflow instance (workflow:admin)

`POST /api/workflow/v1/tasks/{instanceId}/cancel`

Module: Workflow · operationId: `cancelInstance` · Tag: Instances · Auth: access token (`Authorization: Bearer <accessToken>`)

Ends the instance as `CANCELLED` (also a pending start) and writes the state to trade, which
releases the transaction. An instance that has already ended answers `409 invalid_state`. The body is optional.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `instanceId` | path | string (uuid) | yes | Instance id (`guid`) |

### Request body

`application/json`

- `reason` (string): Stored as the comment of the history entry (max length 1000)

Example:

```json
{
  "reason": "Vorgang wurde storniert"
}
```

### Responses

- **200** Cancelled (`application/json`)
- **400** Error (`application/json`)
- **401** Missing or invalid token (`unauthorized`) (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)
- **500** Error (`application/json`)

Fields of the 200 answer:

- `status` (string): Always `ok`

Example 200 answer:

```json
{
  "status": "ok"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/workflow/v1/tasks/3f9c2a1e-8b7d-4c6e-a5f4-1d2b3c4e5f60/cancel' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"reason":"Vorgang wurde storniert"}'
```

## Resend an instance's state to trade (workflow:admin)

`POST /api/workflow/v1/tasks/{instanceId}/resync`

Module: Workflow · operationId: `resyncInstance` · Tag: Instances · Auth: access token (`Authorization: Bearer <accessToken>`)

The escape hatch for a transaction that stays locked although its workflow is over: sends the
instance's effective state to trade again and returns the state afterwards (`RETRYING_SYNC` if
trade is still unreachable; it is retried automatically). `409` when there is nothing to resend:
no trade transaction, a start that never ran, or an ended instance while another workflow runs
for the same transaction.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `instanceId` | path | string (uuid) | yes | Instance id (`guid`) |

### Responses

- **200** State after the resend (`application/json`)
- **401** Missing or invalid token (`unauthorized`) (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)
- **500** Error (`application/json`)

Fields of the 200 answer:

- `state` (WorkflowState): (one of `OPEN`, `RETRYING_SYNC`, `APPROVED`, `REJECTED`, `COMPLETED`, `CANCELLED`, `TRIGGER_NOT_MATCHED`, `TECHNICALLY_FAILED`)

Example 200 answer:

```json
{
  "state": "APPROVED"
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/workflow/v1/tasks/3f9c2a1e-8b7d-4c6e-a5f4-1d2b3c4e5f60/resync' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## List the saved state versions of an instance (tenant:settings:read)

`GET /api/workflow/v1/tasks/{instanceId}/versions`

Module: Workflow · operationId: `listInstanceVersions` · Tag: Instances · Auth: access token (`Authorization: Bearer <accessToken>`)

Every save of an instance is kept as a revision; newest first.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `instanceId` | path | string (uuid) | yes | Instance id (`guid`) |

### Responses

- **200** Versions (`application/json`)
- **401** Missing or invalid token (`unauthorized`) (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **500** Error (`application/json`)

Fields of the 200 answer:

- `items` (array of StateVersion, required): Items of the list
  - `name` (string): Always `State Version`
  - `timestamp` (string (date-time)): When the revision was saved
  - `versionId` (string): The revision number
- `total` (integer): Number of items

Example 200 answer:

```json
{
  "items": [
    {
      "name": "State Version",
      "timestamp": "2026-11-17T09:05:40Z",
      "versionId": "2"
    },
    {
      "name": "State Version",
      "timestamp": "2026-11-17T08:41:12Z",
      "versionId": "1"
    }
  ],
  "total": 2
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/workflow/v1/tasks/3f9c2a1e-8b7d-4c6e-a5f4-1d2b3c4e5f60/versions' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Restore an instance to an earlier state version (tenant:settings:write)

`POST /api/workflow/v1/tasks/{instanceId}/recover`

Module: Workflow · operationId: `restoreInstanceVersion` · Tag: Instances · Auth: access token (`Authorization: Bearer <accessToken>`)

Saves the state of revision `versionId` as a new revision and writes it to trade, which locks or
releases the transaction accordingly. `409` when another instance is already active for the
transaction, when the version belongs to a start that never ran, or on a concurrent change.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `versionId` | query | integer (int64) | yes | Revision to restore (`versionId` from the version list) |
| `instanceId` | path | string (uuid) | yes | Instance id (`guid`) |

### Responses

- **200** Restored (no body)
- **400** Error (`application/json`)
- **401** Missing or invalid token (`unauthorized`) (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)
- **500** Error (`application/json`)

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/workflow/v1/tasks/3f9c2a1e-8b7d-4c6e-a5f4-1d2b3c4e5f60/recover?versionId=3' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## List all workflow instances of the tenant (workflow:admin)

`GET /api/workflow/v1/instances`

Module: Workflow · operationId: `listInstances` · Tag: Instances · Auth: access token (`Authorization: Bearer <accessToken>`)

Every instance in every state, with overview field values, newest start first. Pages by cursor: pass
`nextCursor` as `cursor` until it is missing; no `total`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `limit` | query | integer |  | Page size; another value than 1–500 is a `400 invalid` (default `100`; max 500) |
| `cursor` | query | string |  | `nextCursor` of the previous page (opaque); a foreign or altered cursor is a `400 invalid` |
| `slim` | query | string |  | `true` or `1`: return `SlimTaskListItem`s without data and history (one of `true`, `1`) |
| `format` | query | string |  | `slim`: same as `slim=true` (one of `slim`) |

### Responses

- **200** Instances (slim items when `slim` is set) (`application/json`)
- **400** Error (`application/json`)
- **401** Missing or invalid token (`unauthorized`) (`application/json`)
- **403** Error (`application/json`)
- **500** Error (`application/json`)

Fields of the 200 answer:

- `items` (array of TaskListItem | SlimTaskListItem, required): Instances of the page
- `nextCursor` (string): Cursor of the next page; missing on the last page

Example 200 answer:

```json
{
  "items": [
    {
      "blueprint": {
        "id": "er-freigabe",
        "version": 3
      },
      "blueprintId": "er-freigabe",
      "blueprintVersion": 3,
      "claimedAt": "2026-11-17T09:05:40Z",
      "claimedBy": "christina.adler@muster-it.example",
      "currentStep": {
        "allowInquiry": true,
        "fields": [
          {
            "label": "Eingangsnr.",
            "name": "transactionNumber"
          },
          {
            "label": "Rechnungsnummer",
            "name": "externalTransactionNumber"
          },
          {
            "label": "Lieferant",
            "name": "partnerCompany"
          },
          {
            "editable": true,
            "label": "Fällig am",
            "name": "dueDate"
          },
          {
            "label": "Brutto",
            "name": "grossTotal"
          },
          {
            "label": "Bezeichnung",
            "name": "lines.name"
          },
          {
            "editable": true,
            "label": "Kostenstelle",
            "name": "lines.lineData.costCenter",
            "required": true
          },
          {
            "label": "Menge",
            "name": "lines.quantity"
          }
        ],
        "group": "4e7a1c2b-9f3d-4b8a-a6e1-5c0d2f8b3a71",
        "lines": {
          "allowDelete": true,
          "allowDuplicate": true
        },
        "name": "kontierung",
        "nextSteps": [
          {
            "color": "primary",
            "icon": "i-lucide-arrow-right",
            "label": "Weiter zur Freigabe",
            "step": "freigabe"
          },
          {
            "color": "error",
            "icon": "i-lucide-x-circle",
            "label": "Ablehnen",
            "step": "abgelehnt"
          }
        ],
        "notifyAssigneesByEmail": true,
        "stepType": "UserStep"
      },
      "customerId": {
        "customerId": "99999",
        "tenantName": "DEMO"
      },
      "guid": "3f9c2a1e-8b7d-4c6e-a5f4-1d2b3c4e5f60",
      "objectNumber": "ER-2026-00042",
      "objectType": "transaction",
      "overviewField1": {
        "label": "Lieferant",
        "name": "partnerCompany",
        "value": "Nordlicht IT-Distribution GmbH"
      },
      "overviewField2": {
        "label": "Brutto",
        "name": "grossTotal",
        "value": "6911.52"
      },
      "startTime": "2026-11-17T08:41:12Z",
      "workflowState": "OPEN"
    }
  ],
  "nextCursor": "eyJzIjoiMjAyNi0xMS0xN1QwODo0MToxMloiLCJpZCI6IjNmOWMyYTFlIn0"
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/workflow/v1/instances' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Get a workflow instance (tenant:access)

`GET /api/workflow/v1/instances/{instanceId}`

Module: Workflow · operationId: `getInstance` · Tag: Instances · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `instanceId` | path | string (uuid) | yes | Instance id (`guid`) |

### Responses

- **200** Instance, webhook URLs redacted (`application/json`)
- **401** Missing or invalid token (`unauthorized`) (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **500** Error (`application/json`)

Fields of the 200 answer:

- `blueprint` (Blueprint): A workflow definition. In responses, set webhook URLs are replaced by `********`.
  - `id` (string, required): Free identifier, unique per tenant
  - `steps` (array of Step, required): Steps of the workflow; the first one runs unless trigger.nextStep names another
    - `name` (string, required): Unique within the blueprint; referenced by `nextSteps[].step`
    - `stepType` (string, required): `UserStep` (a person decides) or `SystemStep` (the engine decides) (one of `UserStep`, `SystemStep`)
    - `action` (string): Outcome when the workflow ends after this step: `approve` → APPROVED, `reject` → REJECTED (German synonyms accepted), else COMPLETED
    - `allowInquiry` (boolean): The assignee may ask another person (inquiry)
    - `fields` (array of Field): Fields shown in a user step
    - `group` (string): HR group UUID the user step is assigned to (required for user steps)
    - `lines` (LineActions)
    - `nextSteps` (array of NextStep): Transitions: buttons of a user step, conditions of a system step
    - `notificationEmail` (string): E-mail address notified about this step
    - `notifyAssigneesByEmail` (boolean): E-mail the assignees (the step's user, else its group's members) when the task waits; user steps only
    - `notifyAssigneesByTeams` (boolean): Notify the assignees in their personal Teams chat; user steps only
    - `teamsChannel` (string): Comms webhook channel id notified about this step (see `GET /channels`)
    - `teamsWebhookUrl` (string): Legacy: a Teams webhook URL; saving moves it into a comms channel (`teamsChannel`)
    - `user` (string): E-mail of a person the user step is additionally assigned to
  - `trigger` (Trigger, required)
    - `objectType` (string, required): The only supported object type (one of `transaction`)
    - `condition` (string): Optional expr condition over the transaction data; false ends the start as `TRIGGER_NOT_MATCHED`
    - `nextStep` (NextStep)
      - `color` (string): Button color of a user step transition
      - `condition` (string): System steps: expr condition, or `default`
      - `icon` (string): Button icon of a user step transition
      - `label` (string): Button label of a user step transition
      - `step` (string): Name of the target step
    - `statuses` (array of string): Trade statuses that start the workflow
    - `transactionTypes` (array of string): Trade transaction type codes (active in trade)
  - `active` (boolean): Only active blueprints start workflows; missing means active
  - `inquiryWebhookUrl` (string): Webhook (JSON) notified about inquiries and their answers; `********` keeps the stored URL
  - `overviewField1` (OverviewField)
    - `label` (string): Column label
    - `name` (string): Transaction field shown in task lists
  - `overviewField2` (OverviewField)
    - `label` (string): Column label
    - `name` (string): Transaction field shown in task lists
  - `updatedAt` (string (date-time), read-only): Last modification of the stored blueprint
  - `version` (integer (int64)): Informational; set to 1 when 0 on save
- `claimedAt` (string (date-time)): When the task was claimed; omitted if unclaimed
- `claimedBy` (string): E-mail of the person working on the task, empty if unclaimed
- `currentStep` (Step | null): Null once the workflow has ended
- `customerId` (TenantRef)
  - `customerId` (string): Customer number
  - `tenantName` (string): Tenant name
- `data` (object): Transaction data at start, start metadata (`blueprintId`, `objectNumber`, `initialNote`, …), workflow-local input and open inquiry keys (`inquiry_to`, `inquiry_text`, …)
- `endTime` (string (date-time)): When the instance ended; omitted while running
- `guid` (string (uuid)): Instance id
- `history` (array of HistoryEntry): Append-only history, oldest first
  - `action` (string): Free text, e.g. `Step completed`, `CLAIMED`, `UNCLAIMED`, `FORCE_PULLED`, `NOTE`, `CANCELLED`, `Rückfrage gestellt`
  - `actor` (string): E-mail of the person, or `SYSTEM`
  - `branch` (string): `regular` or `inquiry`
  - `changes` (ChangeSetDiff): What trade changed, with old values
    - `added` (array of LineSnapshot): Lines added by duplicating
    - `changeSetId` (string): Id of the applied change set (instance:revision:content hash)
    - `deleted` (array of LineSnapshot): Lines deleted, with their old values
    - `header` (array of FieldChange): Changed transaction fields
    - `lines` (array of object): Changed fields of existing lines
      - `changes` (array of FieldChange): Changed fields of the line
      - `lineId` (string): Trade line id
      - `position` (integer): Position of the line in the transaction
    - `totals` (object): Transaction totals before and after the changes
      - `new` (Totals)
      - `old` (Totals)
  - `color` (string): Color of the chosen transition button
  - `comment` (string): Comment, note text or inquiry answer
  - `group` (string): HR group UUID of the step
  - `icon` (string): Icon of the chosen transition button
  - `nextStep` (string): Name of the step the transition led to
  - `stepName` (string): Step the entry belongs to (`START`/`END` for the start and end of the workflow)
  - `timestamp` (string (date-time)): When it happened
  - `user` (string): E-mail of the person the step was assigned to
- `lastRetryAt` (string (date-time)): Last automatic retry; omitted if none
- `objectNumber` (string): Transaction number
- `objectType` (string): Object type of the trigger
- `retryCount` (integer): Attempts of a pending trade start or write-back
- `revision` (integer (int64)): Optimistic-lock counter
- `startTime` (string (date-time)): When the instance started
- `transactionId` (string (uuid)): Trade transaction id
- `workflowState` (WorkflowState): (one of `OPEN`, `RETRYING_SYNC`, `APPROVED`, `REJECTED`, `COMPLETED`, `CANCELLED`, `TRIGGER_NOT_MATCHED`, `TECHNICALLY_FAILED`)

Example 200 answer:

```json
{
  "blueprint": {
    "active": true,
    "id": "er-freigabe",
    "overviewField1": {
      "label": "Lieferant",
      "name": "partnerCompany"
    },
    "overviewField2": {
      "label": "Brutto",
      "name": "grossTotal"
    },
    "steps": [
      {
        "allowInquiry": true,
        "fields": [
          {
            "label": "Eingangsnr.",
            "name": "transactionNumber"
          },
          {
            "label": "Rechnungsnummer",
            "name": "externalTransactionNumber"
          },
          {
            "label": "Lieferant",
            "name": "partnerCompany"
          },
          {
            "editable": true,
            "label": "Fällig am",
            "name": "dueDate"
          },
          {
            "label": "Brutto",
            "name": "grossTotal"
          },
          {
            "label": "Bezeichnung",
            "name": "lines.name"
          },
          {
            "editable": true,
            "label": "Kostenstelle",
            "name": "lines.lineData.costCenter",
            "required": true
          },
          {
            "label": "Menge",
            "name": "lines.quantity"
          }
        ],
        "group": "4e7a1c2b-9f3d-4b8a-a6e1-5c0d2f8b3a71",
        "lines": {
          "allowDelete": true,
          "allowDuplicate": true
        },
        "name": "kontierung",
        "nextSteps": [
          {
            "color": "primary",
            "icon": "i-lucide-arrow-right",
            "label": "Weiter zur Freigabe",
            "step": "freigabe"
          },
          {
            "color": "error",
            "icon": "i-lucide-x-circle",
            "label": "Ablehnen",
            "step": "abgelehnt"
          }
        ],
        "notifyAssigneesByEmail": true,
        "stepType": "UserStep"
      },
      {
        "allowInquiry": true,
        "fields": [
          {
            "label": "Eingangsnr.",
            "name": "transactionNumber"
          },
          {
            "label": "Lieferant",
            "name": "partnerCompany"
          },
          {
            "label": "Brutto",
            "name": "grossTotal"
          }
        ],
        "group": "4e7a1c2b-9f3d-4b8a-a6e1-5c0d2f8b3a71",
        "name": "freigabe",
        "nextSteps": [
          {
            "color": "success",
            "icon": "i-lucide-check-circle",
            "label": "Freigeben",
            "step": "freigegeben"
          },
          {
            "color": "warning",
            "icon": "i-lucide-undo-2",
            "label": "Zurück zur Kontierung",
            "step": "kontierung"
          },
          {
            "color": "error",
            "icon": "i-lucide-x-circle",
            "label": "Ablehnen",
            "step": "abgelehnt"
          }
        ],
        "stepType": "UserStep"
      },
      {
        "action": "approve",
        "name": "freigegeben",
        "stepType": "SystemStep"
      },
      {
        "action": "reject",
        "name": "abgelehnt",
        "stepType": "SystemStep"
      }
    ],
    "trigger": {
      "nextStep": {
        "step": "kontierung"
      },
      "objectType": "transaction",
      "statuses": [
        "MATCHED"
      ],
      "transactionTypes": [
        "INBOUND_INVOICE"
      ]
    },
    "updatedAt": "2026-10-14T13:22:05Z",
    "version": 3
  },
  "claimedAt": "2026-11-17T09:05:40Z",
  "claimedBy": "christina.adler@muster-it.example",
  "currentStep": {
    "allowInquiry": true,
    "fields": [
      {
        "label": "Eingangsnr.",
        "name": "transactionNumber"
      },
      {
        "label": "Rechnungsnummer",
        "name": "externalTransactionNumber"
      },
      {
        "label": "Lieferant",
        "name": "partnerCompany"
      },
      {
        "editable": true,
        "label": "Fällig am",
        "name": "dueDate"
      },
      {
        "label": "Brutto",
        "name": "grossTotal"
      },
      {
        "label": "Bezeichnung",
        "name": "lines.name"
      },
      {
        "editable": true,
        "label": "Kostenstelle",
        "name": "lines.lineData.costCenter",
        "required": true
      },
      {
        "label": "Menge",
        "name": "lines.quantity"
      }
    ],
    "group": "4e7a1c2b-9f3d-4b8a-a6e1-5c0d2f8b3a71",
    "lines": {
      "allowDelete": true,
      "allowDuplicate": true
    },
    "name": "kontierung",
    "nextSteps": [
      {
        "color": "primary",
        "icon": "i-lucide-arrow-right",
        "label": "Weiter zur Freigabe",
        "step": "freigabe"
      },
      {
        "color": "error",
        "icon": "i-lucide-x-circle",
        "label": "Ablehnen",
        "step": "abgelehnt"
      }
    ],
    "notifyAssigneesByEmail": true,
    "stepType": "UserStep"
  },
  "customerId": {
    "customerId": "99999",
    "tenantName": "DEMO"
  },
  "data": {
    "blueprintId": "er-freigabe",
    "externalTransactionNumber": "RE-482117",
    "grossTotal": 6911.52,
    "netTotal": 5808,
    "objectNumber": "ER-2026-00042",
    "partnerCompany": "Nordlicht IT-Distribution GmbH",
    "transactionNumber": "ER-2026-00042"
  },
  "guid": "3f9c2a1e-8b7d-4c6e-a5f4-1d2b3c4e5f60",
  "history": [
    {
      "action": "Workflow started",
      "actor": "SYSTEM",
      "nextStep": "kontierung",
      "stepName": "START",
      "timestamp": "2026-11-17T08:41:12Z"
    },
    {
      "action": "CLAIMED",
      "actor": "christina.adler@muster-it.example",
      "group": "4e7a1c2b-9f3d-4b8a-a6e1-5c0d2f8b3a71",
      "stepName": "kontierung",
      "timestamp": "2026-11-17T09:05:40Z"
    }
  ],
  "objectNumber": "ER-2026-00042",
  "objectType": "transaction",
  "retryCount": 0,
  "revision": 2,
  "startTime": "2026-11-17T08:41:12Z",
  "transactionId": "8c2f4a6e-0b1d-4e3f-9a5c-7e9b1d3f5a7c",
  "workflowState": "OPEN"
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/workflow/v1/instances/3f9c2a1e-8b7d-4c6e-a5f4-1d2b3c4e5f60' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Get the history of a workflow instance (tenant:access)

`GET /api/workflow/v1/instances/{instanceId}/log`

Module: Workflow · operationId: `getInstanceHistory` · Tag: Instances · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `instanceId` | path | string (uuid) | yes | Instance id (`guid`) |

### Responses

- **200** History entries, oldest first (`application/json`)
- **401** Missing or invalid token (`unauthorized`) (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)

Fields of the 200 answer:

- `items` (array of HistoryEntry, required): Items of the list
  - `action` (string): Free text, e.g. `Step completed`, `CLAIMED`, `UNCLAIMED`, `FORCE_PULLED`, `NOTE`, `CANCELLED`, `Rückfrage gestellt`
  - `actor` (string): E-mail of the person, or `SYSTEM`
  - `branch` (string): `regular` or `inquiry`
  - `changes` (ChangeSetDiff): What trade changed, with old values
    - `added` (array of LineSnapshot): Lines added by duplicating
    - `changeSetId` (string): Id of the applied change set (instance:revision:content hash)
    - `deleted` (array of LineSnapshot): Lines deleted, with their old values
    - `header` (array of FieldChange): Changed transaction fields
    - `lines` (array of object): Changed fields of existing lines
      - `changes` (array of FieldChange): Changed fields of the line
      - `lineId` (string): Trade line id
      - `position` (integer): Position of the line in the transaction
    - `totals` (object): Transaction totals before and after the changes
      - `new` (Totals)
      - `old` (Totals)
  - `color` (string): Color of the chosen transition button
  - `comment` (string): Comment, note text or inquiry answer
  - `group` (string): HR group UUID of the step
  - `icon` (string): Icon of the chosen transition button
  - `nextStep` (string): Name of the step the transition led to
  - `stepName` (string): Step the entry belongs to (`START`/`END` for the start and end of the workflow)
  - `timestamp` (string (date-time)): When it happened
  - `user` (string): E-mail of the person the step was assigned to
- `total` (integer): Number of items

Example 200 answer:

```json
{
  "items": [
    {
      "action": "Workflow started",
      "actor": "SYSTEM",
      "nextStep": "kontierung",
      "stepName": "START",
      "timestamp": "2026-11-17T08:41:12Z"
    },
    {
      "action": "CLAIMED",
      "actor": "christina.adler@muster-it.example",
      "group": "4e7a1c2b-9f3d-4b8a-a6e1-5c0d2f8b3a71",
      "stepName": "kontierung",
      "timestamp": "2026-11-17T09:05:40Z"
    },
    {
      "action": "Step completed",
      "actor": "christina.adler@muster-it.example",
      "branch": "regular",
      "changes": {
        "added": [],
        "changeSetId": "3f9c2a1e-8b7d-4c6e-a5f4-1d2b3c4e5f60:2:4d7a0c",
        "deleted": [],
        "header": [],
        "lines": [
          {
            "changes": [
              {
                "field": "lineData.costCenter",
                "label": "Kostenstelle",
                "new": "4100",
                "old": ""
              }
            ],
            "lineId": "7d2e9a41-3b6c-4f0e-8a15-c9b2d4e6f801",
            "position": 1
          }
        ],
        "totals": {
          "new": {
            "gross": 6911.52,
            "net": 5808,
            "tax": 1103.52
          },
          "old": {
            "gross": 6911.52,
            "net": 5808,
            "tax": 1103.52
          }
        }
      },
      "color": "primary",
      "comment": "Kostenstelle Vertrieb.",
      "group": "4e7a1c2b-9f3d-4b8a-a6e1-5c0d2f8b3a71",
      "icon": "i-lucide-arrow-right",
      "nextStep": "freigabe",
      "stepName": "kontierung",
      "timestamp": "2026-11-17T09:12:03Z"
    }
  ],
  "total": 3
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/workflow/v1/instances/3f9c2a1e-8b7d-4c6e-a5f4-1d2b3c4e5f60/log' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

