## Bill a unit's approved work in a period (hr:work:billing)

`POST /api/hr/v1/work-batches`

Module: HR · operationId: `createWorkBatch` · Tag: Work billing · Auth: access token (`Authorization: Bearer <accessToken>`)

Bills the approved entries of a project (`scope: project`, `projectRef`; the customer is that of the project's
work, `customerId` picks one when it bills several), a contract outside projects (`contract`, `customerId`,
`contractId`) or a customer outside projects and contracts (`customer`, `customerId`) whose work date lies in
`from`–`to`. Hourly entries are priced with the rate table (project, contract, customer, default; a rate for the
entry's kind before one for all kinds; the newest `validFrom` on or before the work date), flat-rate entries
with an article at the article's sales price in masterdata (one line, quantity 1). With `dryRun=true` the answer
is the preview and nothing is stored. Otherwise the entries are put into the batch with their rate
(`billedRate`) and the invoice draft goes to trade at once (reference `hr:work-batch:<id>`); when trade does not
take it the batch stays `requested` with `lastError` and is sent again automatically. Refused (`400`, field
`from`, `hourlyRate` or `article`): no approved billable work, entries without rate, flat-rate articles without
price or gone, a sum of 0 or less. Without trade `503 trade_unavailable`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `dryRun` | query | boolean |  | Answer the preview only (default `false`) |

### Request body

`application/json` (required)

- `from` (string (date), required): First work day of the period (YYYY-MM-DD), inclusive
- `scope` (string, required): Billing unit: contract (customerId, contractId), customer (customerId) or project (projectRef) (one of `project`, `contract`, `customer`)
- `to` (string (date), required): Inclusive; at most a year after `from`
- `contractId` (string): The contract of a contract batch
- `customerId` (string): The customer (masterdata address id); for a project only when its work bills several
- `projectRef` (string): The project of a project batch

Example:

```json
{
  "customerId": "1b3d5f7b-9d1f-4b3d-8f5b-9d1f3b5d7f50",
  "from": "2026-10-01",
  "scope": "customer",
  "to": "2026-10-31"
}
```

### Responses

- **200** The preview (dryRun) (`application/json`)
- **201** The batch with what it bills (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **409** Error (`application/json`)
- **503** Error (`application/json`)

Fields of the 201 answer:

- `batch` (WorkBatch): One hourly invoice of a billing unit – a draft in trade until a person releases it there.
  - `billableMinutes` (integer): Hourly minutes (flat-rate entries are not counted)
  - `contractId` (string): Trade contract of contract batches
  - `createdAt` (string (date-time)): When the batch was created
  - `customerId` (string): Customer (masterdata address id) of contract and customer batches
  - `entryCount` (integer): Number of entries in the batch
  - `grossTotal` (number, nullable): Gross total of trade's invoice
  - `id` (string (uuid)): Id of the batch
  - `invoiceNumber` (string): Given by trade on release
  - `invoicedOn` (string (date), nullable): Date of the invoice (YYYY-MM-DD) once released
  - `label` (string): Names the unit on the invoice and in lists
  - `lastError` (string): Why the last send failed (German)
  - `netAmount` (number): Net amount HR computed
  - `netTotal` (number, nullable): Net total of trade's invoice
  - `periodFrom` (string (date)): First work day of the period (YYYY-MM-DD)
  - `periodTo` (string (date)): Last work day of the period (YYYY-MM-DD)
  - `projectRef` (string): Reference of the project (project batches)
  - `requestedAt` (string (date-time)): When the batch was requested
  - `requestedBy` (string): Who requested it (e-mail)
  - `scope` (string): Billing unit of the batch (one of `project`, `contract`, `customer`)
  - `sendAttempts` (integer): Attempts to send the draft to trade
  - `state` (string): requested → drafted (trade holds the draft) → invoiced; discarded: the draft was deleted, the entries are free again (one of `requested`, `drafted`, `invoiced`, `discarded`)
  - `tradeTransactionId` (string): Id of trade's document
  - `updatedAt` (string (date-time)): When the batch was last changed
  - `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)
- `billableMinutes` (integer): Billable minutes of the batch
- `flatWithoutArticle` (integer): Approved flat-rate entries without article (never billed)
- `lines` (array of object): The entries with their rate and net amount
  - `entry` (WorkEntry): A booked piece of work of an employee.
    - `approvedAt` (string (date-time), nullable): When the entry was approved
    - `approvedBy` (string): Who approved the entry (e-mail; the platform team acting in the tenant: „Plattformbetrieb (MBCOM) · <Name>“)
    - `article` (WorkArticleRef | null): Masterdata article a flat-rate entry is billed as
    - `batchId` (string (uuid), nullable): Billing batch the entry is billed in
    - `billableMinutes` (integer): Minutes billed
    - `billedRate` (number, nullable): Hourly rate (or article price) the entry was billed at
    - `billing` (string): Key of a billing type
    - `contract` (WorkContractRef | null): Trade contract that decides billing
    - `correctionOf` (string (uuid), nullable): The approved or billed entry this one corrects; its minutes are the difference (may be negative)
    - `createdAt` (string (date-time)): When the work entry was created
    - `createdBy` (string): Who booked the entry (e-mail)
    - `customer` (WorkCustomerRef | null): Customer the work is billed to
    - `description` (string): What was done
    - `durationSeconds` (integer): The exact length in seconds (the stopwatch's seconds, else `minutes` × 60)
    - `employeeId` (string (uuid)): Id of the employee
    - `employeeName` (string): Display name of the employee – only in `listApprovableWorkEntries`
    - `endedAt` (string (date-time), nullable): `null` for the running stopwatch and for an entry without a span
    - `id` (string (uuid)): Id of the work entry
    - `kind` (string): Key of a work kind (`getWorkEntrySettings`)
    - `km` (number): Kilometres travelled (kinds that allow travel)
    - `minutes` (integer): The length in minutes that sums and billing use (a correction's difference, may be negative; 0 for a stopwatch run that rounded to nothing)
    - `origin` (string): The call or appointment the time comes from: `comms:interaction:<id>` or `comms:calendar:<id>`; omitted for other work. Booked at most once per tenant (`409 already_booked`)
    - `project` (WorkProjectRef | null): Project the work counts for
    - `running` (boolean): The running stopwatch entry (start, no end)
    - `source` (string): How the entry was booked (one of `manual`, `stopwatch`, `interaction`, `calendar`, `correction`)
    - `startedAt` (string (date-time), nullable): `null` for an entry booked as a length only
    - `state` (string): suggested → confirmed → approved → billed (one of `suggested`, `confirmed`, `approved`, `billed`)
    - `subject` (string): What was worked on: `desk:item:<id>`, `forge:item:<id>`, `crm:activity:<id>`, a project `desk:project:<id>` / `forge:project:<id>`; empty for work on the customer only or internal work
    - `subjectLabel` (string): The subject's name at booking time (the origin's without a subject)
    - `travelMinutes` (integer): Travel time in minutes (kinds that allow travel)
    - `updatedAt` (string (date-time)): When the work entry was last changed
    - `version` (integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)
    - `workDate` (string (date)): The day the work counts for (the person's choice; with a start its day in the tenant's time zone)
  - `flat` (boolean): Billed as the entry's article (quantity 1)
  - `net` (number): Net amount of the line
  - `rate` (number, nullable): Hourly rate or article price; `null` none
- `missingPrice` (integer): Flat-rate entries whose article is gone
- `missingRate` (integer): Entries without hourly rate
- `netAmount` (number): Net amount of the batch
- `noPrice` (integer): Flat-rate entries whose article has no sales price

Example 201 answer:

```json
{
  "billableMinutes": 270,
  "flatWithoutArticle": 0,
  "lines": [
    {
      "entry": {
        "billableMinutes": 90,
        "billing": "hourly",
        "customer": {
          "id": "1b3d5f7b-9d1f-4b3d-8f5b-9d1f3b5d7f50",
          "name": "Kanzlei Hofmann \u0026 Partner"
        },
        "description": "Neuer Arbeitsplatz Büroleitung eingerichtet",
        "employeeId": "e5a1c3d7-2b4f-4c6e-8a0b-1d3f5b7c9e02",
        "id": "3d5f7b9d-1f3b-4d5f-8b9d-1f3b5d7f9b65",
        "kind": "onsite",
        "minutes": 90,
        "source": "manual",
        "state": "approved",
        "subject": "desk:item:9f1b3d5f-7b9d-4f1b-8d5f-7b9d1f3b5d66",
        "subjectLabel": "#198 Arbeitsplatz Herr Pichler",
        "version": 2,
        "workDate": "2026-10-14"
      },
      "flat": false,
      "net": 142.5,
      "rate": 95
    },
    {
      "entry": {
        "billableMinutes": 180,
        "billing": "hourly",
        "customer": {
          "id": "1b3d5f7b-9d1f-4b3d-8f5b-9d1f3b5d7f50",
          "name": "Kanzlei Hofmann \u0026 Partner"
        },
        "description": "Datensicherung umgestellt und Rücksicherung getestet",
        "employeeId": "c7e9a1b3-5d7f-4b2c-8e4a-6f8b0d2c4e06",
        "id": "1b3d5f7b-9d1f-4b3d-9f5b-9d1f3b5d7f67",
        "kind": "remote",
        "minutes": 180,
        "source": "manual",
        "state": "approved",
        "subject": "desk:item:3f5b7d9f-1b3d-4f5b-9d9f-1b3d5f7b9d68",
        "subjectLabel": "#205 Backup-Umstellung",
        "version": 2,
        "workDate": "2026-10-22"
      },
      "flat": false,
      "net": 285,
      "rate": 95
    }
  ],
  "missingPrice": 0,
  "missingRate": 0,
  "netAmount": 427.5,
  "noPrice": 0
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/hr/v1/work-batches' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"customerId":"1b3d5f7b-9d1f-4b3d-8f5b-9d1f3b5d7f50","from":"2026-10-01","scope":"customer","to":"2026-10-31"}'
```
