ConnectCloud Developers

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:

{
  "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) · “)
      • 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:

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

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

View as Markdown · Interactive reference · OpenAPI