ConnectCloud Developers

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:

{
  "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:

{
  "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}}]}}'

View as Markdown · Interactive reference · OpenAPI