## 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}}]}}'
```
