# Projects, plans and billing

Desk projects bundle the tickets and tasks of a customer project: a schedule with milestones and
dependencies, a time budget and a payment plan with interim and final invoices. The hours worked on a
project are work entries in HR (Leistungserfassung), which also bills them. Everything below is under `https://api.mbcom.cloud/api/desk/v1`. Project types,
workflows and fields are tenant configuration – read them from [`GET /bootstrap`](/reference/desk/getBootstrap),
never hard-code keys.

| Step | Operations | Permission |
|---|---|---|
| Create and plan | [`createProjectFromTemplate`](/reference/desk/createProjectFromTemplate), [`getProjectPlan`](/reference/desk/getProjectPlan), milestones, dependencies | `desk:write` (read: `desk:read`) |
| Approve hours (HR) | [`approveWorkEntries`](/reference/hr/approveWorkEntries), [`unapproveWorkEntries`](/reference/hr/unapproveWorkEntries), [`correctWorkEntry`](/reference/hr/correctWorkEntry) | `hr:work:manage` (or the chain of command) |
| Bill | payment plan; hours: [`createWorkBatch`](/reference/hr/createWorkBatch), [`listWorkRates`](/reference/hr/listWorkRates) (HR) | `hr:work:billing` |

## Create a project from a template

A template of a project type creates the project with its tasks (ordinary desk items), milestones
and dependencies in one transaction. Dates count from `startOn`. Every project has a home space (`spaceId`, a space id or key, required; `422` when it is
missing, unknown or archived). List a space's projects with `GET /projects?spaceId=`. Send `dryRun=true` first to see
the plan without storing anything:

```bash
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/projects/from-template?dryRun=true' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"templateId": "erp-einfuehrung", "startOn": "2026-11-02",
           "project": {"title": "ERP Müller GmbH", "spaceId": "SUPPORT", "customer": {"id": "10042", "name": "Müller GmbH"}}}'
```

## Plan: milestones, dependencies, findings

[`GET /projects/{id}/plan`](/reference/desk/getProjectPlan) returns the project's items with start
and end dates, its milestones, the dependencies and **findings** as of today: `late` (end passed,
not done), `at_risk` (a predecessor is late), `blocked`, `conflict` (a successor starts too early),
`milestone_late` and `undated`. Dates are never moved for you – reschedule items with
[`PATCH /items/{ref}`](/reference/desk/updateItem) (`startOn`, `dueAt`).

Dependencies are finish-to-start between two items of the same project, with a lag in days
(negative = overlap); a cycle is refused with `409 dependency_cycle`:

```bash
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/projects/P-12/dependencies' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"predecessorId": "<item id>", "successorId": "<item id>", "lagDays": 1}'
```

A milestone ([`createProjectMilestone`](/reference/desk/createProjectMilestone)) is reached by hand ([`achieveProjectMilestone`](/reference/desk/achieveProjectMilestone))
or, with `completion: "items"`, when all its items are done.

### React to delays

Every 10 minutes desk looks for project items that are late or at risk and writes the events
`desk.plan.late` and `desk.plan.at_risk` – once per item and finding, again only after the
finding went away. The payload field `planDays` holds the delay. React to them with an automation
([`POST /automations`](/reference/desk/createDeskAutomation), `desk:admin` or a maintainer of the
space) or a flow, to comment, send a message, set a priority or a label; without one nothing
happens. Automations are definitions in the flow language that desk runs inside the change – see
"Immediate automations in desk and forge" in the [Flows](/guides/flows) guide; forge projects have the
same under `/api/forge/v1/projects/{key}/automations`
([`listForgeAutomations`](/reference/forge/listForgeAutomations)).

## Payment plan

A project's payments ([`createProjectPayment`](/reference/desk/createProjectPayment)) are interim
payments and one final invoice, each a fixed net amount or a percentage of `budgetAmount`, due with
a milestone (`milestoneId`) or on a date (`dueOn`). [`requestProjectPayment`](/reference/desk/requestProjectPayment)
builds the invoice and hands it to trade as a **draft** under the reference
`desk:project-payment:<id>:<attempt>`; a person releases it in trade, which assigns the invoice
number. The final invoice bills the whole contract value and deducts the interim invoices per tax
rate. States: `planned → due → requested → drafted → invoiced` (or `skipped`); a deleted draft or a
revoked invoice makes the payment due again.

## Hours

Work is booked, approved and billed in HR ([`createWorkEntry`](/reference/hr/createWorkEntry)): on a ticket
with the subject `desk:item:<id>`, on a project with the project reference `desk:project:<id>` (an entry on a
ticket of a project gets the project from desk). A project's `spentMinutes` and the summary
([`getProjectSummary`](/reference/desk/getProjectSummary)) are HR's totals of that reference; when HR does not
answer they are `null` (unknown), never an error. Crossing the warning share or the budget writes
`desk.project.budget`, once per threshold.

Approval ([`approveWorkEntries`](/reference/hr/approveWorkEntries)), corrections and hourly billing per project,
contract or customer ([`createWorkBatch`](/reference/hr/createWorkBatch) with `dryRun=true` as preview; rates:
[`listWorkRates`](/reference/hr/listWorkRates)) are HR's; the batch goes to trade as a draft under
`hr:work-batch:<id>`.

## Show and filter project tickets

`ticketDisplay` on a project ([`createProject`](/reference/desk/createProject),
[`updateProject`](/reference/desk/updateProject)) decides where its tickets show in the portal's ticket
list: `tickets` (default, as ordinary tickets), `projects` (only on the projects page) or `hidden`
(not in the lists; tickets assigned to the viewer still show). A `PUT` without `ticketDisplay` keeps the
stored value. In project lists, `itemsByPhase` counts the project's tickets per phase (`new`, `active`,
`waiting`, `done`); it is read-only. [`listProjects`](/reference/desk/listProjects) also filters by
`type` and by `responsible=me`. Every item carries the read-only `projectTicketDisplay` of its project
(empty without project).

[`listItems`](/reference/desk/listItems) takes `projectTickets`: `view` applies the portal's ticket-list
rule (no project, a project with `ticketDisplay=tickets`, or assigned to the caller), `none` returns
items without project, `only` items with a project. Without it all items are returned, as before.
`projects` limits the list to comma-separated project ids:

```bash
curl 'https://api.mbcom.cloud/api/desk/v1/items?projectTickets=view&limit=25' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

A child ticket always has the project of its parent: a different `projectId` on a child is refused
with `422`, and changing the project of a parent moves all its descendants along (their milestones
are cleared).
