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