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 thelines.prefix.delete(array of string): Line ids to delete (needslines.allowDelete)duplicate(array of object): Copies of existing lines (needslines.allowDuplicate)sourceLineId(string, required): Id of the line to copytempId(string, required): Client id of the copyvalues(object): Values overriding the copy's
header(object): Transaction fields to setlines(array of object): Changed field values of existing linesid(string, required): Line idvalues(object, required): Line fields to set
Example:
{
"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 valuesadded(array of LineSnapshot): Lines added by duplicatinglineId(string): Trade line idposition(integer): Position of the line in the transactionsourceLineId(string): Line a duplicate was copied fromtempId(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 valueslineId(string): Trade line idposition(integer): Position of the line in the transactionsourceLineId(string): Line a duplicate was copied fromtempId(string): Client id of a duplicated line (ChangeSet.duplicate[].tempId)values(object): Line field values
header(array of FieldChange): Changed transaction fieldsfield(string): Field namelabel(string): Label of the field in the stepnew(any): New valueold(any): Previous value
lines(array of object): Changed fields of existing lineschanges(array of FieldChange): Changed fields of the linelineId(string): Trade line idposition(integer): Position of the line in the transaction
totals(object): Transaction totals before and after the changesnew(Totals)gross(number): Gross totalnet(number): Net totaltax(number): Tax total
old(Totals)gross(number): Gross totalnet(number): Net totaltax(number): Tax total
document(object): The recalculated transaction, shaped likeTaskDetails.document
Example 200 answer:
{
"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
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}}]}}'