## Submit, recall, approve, reject, release or transfer a report

`POST /api/hr/v1/travel-reports/{id}/{action}`

Module: HR · operationId: `runTravelReportAction` · Tag: Travel expenses · Auth: access token (`Authorization: Bearer <accessToken>`)

- `submit` (owner, `draft`/`rejected` → `submitted`): recomputes the totals and freezes them – approval,
  `totals` and the transfer use them, whatever the rates say later; `422 infected` while a
  receipt the malware scan flagged is attached, `422 scan_failed` while one could not be checked. `recall` (owner, `submitted` → `draft`).
- `approve` / `reject` (`submitted`): the responsible managers and `hr:travel:approve`; a reason
  (`note`) is required to reject. Accounting (`hr:travel:manage`) may also reject `approved` reports.
- `release` (`approved` → `released`) and `transfer` (`released` → `transferred`): `hr:travel:manage`.
  The transfer creates a trade document (`transactionType`, default `TRAVEL_EXPENSE`) for the
  employee's masterdata address (`400` on field `addressId` while it does not exist yet), one line per
  allowance and expense (the frozen totals; net unit price with 4 decimals, so net × VAT rate is the
  reimbursed amount). Trade derives the document from the reference `hr-travel:<id>`, so a repeated
  transfer never creates a second one. A failure answers `502 transfer_failed`, is kept in
  `transferError` and can be retried.

Nobody approves, releases or transfers their own report (`403`); not allowed in the current
status: `409 invalid_state`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |
| `action` | path | string | yes | (one of `submit`, `recall`, `approve`, `reject`, `release`, `transfer`) |

### Request body

`application/json` (required)

- `version` (integer, required): Version of the report the action is based on
- `note` (string): Reason of a rejection (max length 2000)

Example:

```json
{
  "note": "Bitte den Parkbeleg nachreichen, dann gebe ich die Abrechnung frei.",
  "version": 2
}
```

### Responses

- **200** Done (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)
- **422** Error (`application/json`)
- **502** Error (`application/json`)
- **503** Error (`application/json`)

Fields of the 200 answer:

- `approvedAt` (string (date-time)): When it was approved
- `approvedBy` (string): Who approved (e-mail; the platform team acting in the tenant: „Plattformbetrieb (MBCOM) · <Name>“)
- `country` (string): ISO 3166-1 alpha-2 code of the destination; selects the allowance rates
- `createdAt` (string (date-time)): When the report was created
- `createdBy` (string): Who created the report (e-mail)
- `days` (array of TravelDay): What was provided per day (meals, lodging lump sum)
  - `breakfast` (boolean): Breakfast provided (cuts the allowance by breakfastPercent of the full-day rate)
  - `date` (string (date)): Day of the trip (YYYY-MM-DD)
  - `dinner` (boolean): Dinner was provided (reduces the meal allowance)
  - `lodgingLumpSum` (boolean): The night after this day without a hotel receipt (lodging lump sum)
  - `lunch` (boolean): Lunch was provided (reduces the meal allowance)
- `decisionNote` (string): Reason of the last rejection
- `destination` (string): Destination of the trip
- `employeeId` (string): Id of the employee
- `employeeName` (string): Display name of the employee (in lists)
- `endAt` (string): Local return time (YYYY-MM-DDTHH:MM)
- `id` (string): Id of the report
- `items` (array of TravelItem): Expenses (single reads)
  - `date` (string (date), required): Date of the expense (YYYY-MM-DD)
  - `kind` (string, required): Kind of expense; mileage items carry km and are priced with the tenant rate (one of `mileage`, `transport`, `lodging`, `other`)
  - `amountCents` (integer): Gross amount in cents; computed for mileage (km × rate)
  - `description` (string): What was paid for (max length 200)
  - `id` (string, read-only): Id of the expense
  - `km` (number): Kilometres of a mileage item
  - `merchant` (string): Issuer of the receipt (max length 200)
  - `receiptId` (string): A receipt of the same report
  - `vatCents` (integer): VAT contained in the amount, always computed from amountCents and vatRate (a sent value is ignored; record a receipt with several rates as one item per rate)
  - `vatRate` (number): VAT rate in percent
- `note` (string): Note of the employee
- `overnight` (boolean): The trip includes overnight stays
- `purpose` (string): Purpose of the trip
- `receipts` (array of TravelReceipt): Receipt files (single reads)
  - `contentType` (string): Media type of the file
  - `createdAt` (string (date-time)): When the receipt was uploaded
  - `createdBy` (string): Who uploaded the receipt (e-mail)
  - `documentId` (string): DMS document (owner module hr)
  - `fileName` (string): File name
  - `id` (string): Id of the receipt
  - `scanStatus` (string): Malware scan of the DMS (one of `PENDING`, `CLEAN`, `INFECTED`, `SKIPPED`, `FAILED`)
  - `sizeBytes` (integer): Size in bytes
- `rejectedAt` (string (date-time)): When it was rejected last
- `rejectedBy` (string): Who rejected it last (e-mail; the platform team acting in the tenant: „Plattformbetrieb (MBCOM) · <Name>“)
- `releasedAt` (string (date-time)): When it was released
- `releasedBy` (string): Who released it for payment (e-mail; the platform team acting in the tenant: „Plattformbetrieb (MBCOM) · <Name>“)
- `startAt` (string): Local departure time (YYYY-MM-DDTHH:MM)
- `status` (string): State of the report (one of `draft`, `submitted`, `approved`, `rejected`, `released`, `transferred`)
- `submittedAt` (string (date-time)): When the report was submitted
- `totalCents` (integer): Reimbursement in cents
- `totals` (object): Drafts and rejected reports: computed with the current rates; from `submitted` on: frozen at submit.
- `tradeDocumentNo` (string): Number of the trade document
- `tradeTransactionId` (string): Id of the trade document created for the report
- `transferError` (string): The last failed transfer (empty after a success)
- `transferredAt` (string (date-time)): When it was transferred to trade
- `updatedAt` (string (date-time)): When the report was last changed
- `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)

Example 200 answer:

```json
{
  "approvedAt": "2026-11-07T08:15:00Z",
  "approvedBy": "tobias.hartl@muster-it.example",
  "country": "DE",
  "createdAt": "2026-11-06T07:40:00Z",
  "createdBy": "jonas.bauer@muster-it.example",
  "days": [
    {
      "breakfast": true,
      "date": "2026-11-05"
    }
  ],
  "destination": "Alpenhotel Seeblick, Schönau am Königssee",
  "employeeId": "f2a4c6e8-0b2d-4f4a-8c6e-8a0c2e4b6d1c",
  "employeeName": "Jonas Bauer",
  "endAt": "2026-11-05T18:30",
  "id": "0d2f4b6d-8f0b-4d2f-8b6d-8f0b2d4f6b46",
  "items": [
    {
      "amountCents": 11400,
      "date": "2026-11-04",
      "description": "Regensburg – Schönau am Königssee und zurück",
      "id": "2f4b6d8f-0b2d-4f4b-9d8f-0b2d4f6b8d47",
      "kind": "mileage",
      "km": 380,
      "vatCents": 0,
      "vatRate": 0
    },
    {
      "amountCents": 9800,
      "date": "2026-11-05",
      "description": "Übernachtung mit Frühstück",
      "id": "4b6d8f0b-2d4f-4b6d-8f0b-2d4f6b8d0f48",
      "kind": "lodging",
      "merchant": "Alpenhotel Seeblick",
      "receiptId": "6f8b0d2f-4b6d-4f8b-8d2f-4b6d8f0b2d44",
      "vatCents": 641,
      "vatRate": 7
    }
  ],
  "note": "Hotelrechnung als PDF angehängt.",
  "overnight": true,
  "purpose": "WLAN-Ausleuchtung und Access-Point-Montage",
  "receipts": [
    {
      "contentType": "application/pdf",
      "createdAt": "2026-11-06T07:48:00Z",
      "createdBy": "jonas.bauer@muster-it.example",
      "documentId": "8b0d2f4b-6d8f-4b0d-9f4b-6d8f0b2d4f45",
      "fileName": "rechnung-alpenhotel-seeblick.pdf",
      "id": "6f8b0d2f-4b6d-4f8b-8d2f-4b6d8f0b2d44",
      "scanStatus": "CLEAN",
      "sizeBytes": 184320
    }
  ],
  "startAt": "2026-11-04T06:45",
  "status": "approved",
  "submittedAt": "2026-11-06T07:52:00Z",
  "totalCents": 23440,
  "totals": {
    "days": [
      {
        "allowanceCents": 1400,
        "country": "DE",
        "date": "2026-11-04",
        "deductionCents": 0,
        "hours": 17.25,
        "kind": "partial",
        "lodgingCents": 0,
        "rateCents": 1400
      },
      {
        "allowanceCents": 840,
        "country": "DE",
        "date": "2026-11-05",
        "deductionCents": 560,
        "hours": 18.5,
        "kind": "partial",
        "lodgingCents": 0,
        "rateCents": 1400
      }
    ],
    "expensesCents": 9800,
    "lodgingLumpSumCents": 0,
    "mealAllowanceCents": 2240,
    "mileageCents": 11400,
    "totalCents": 23440,
    "warnings": []
  },
  "updatedAt": "2026-11-07T08:15:00Z",
  "version": 3
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/hr/v1/travel-reports/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/submit' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"note":"Bitte den Parkbeleg nachreichen, dann gebe ich die Abrechnung frei.","version":2}'
```
