VERTRAG
VERTRAG
With VERTRAG you manage rental agreements / cases between landlord and tenant.
For each contract you can record:
- Landlord and tenant (see VERMIETER, MIETER)
- Period (start, end)
- Assigned inventory (quantities, optional prices)
- Technicians / helpers
- Comments and documents (uploads)
- Status / Kanban column (see KANBAN)
- Digital signatures (landlord & tenant)
- Generated PDF of the contract
- Generated invoice (HTML/PDF) based on the contract data (M27)
- Create a contract and maintain its data
- Assign inventory
- Generate a PDF
- Generate an invoice from the contract (HTML/PDF)
- Get the contract signed by landlord and/or tenant
- Move via Kanban drag & drop into another column
- Upload attachments (e.g., ID, terms and conditions, order confirmation)
- Filter contracts (e.g., only open, only completed)
- Delete contracts (soft) and possibly restore or delete permanently
1) Create a contract
- Open Contract → Contracts (
/dokumente/vertraege). - Click "New" (
/dokumente/vertraege/new). - Fill in the required fields:
- Tenant (select or create new)
- Landlord
- Period
- Save.
2) Edit a contract
- Click the contract in the list (
/dokumente/vertraege/{id}). - Change fields and save.
- The detail page additionally allows you to:
- Add comments
- Upload / download / delete documents
- Assign inventory (selection list or quick search by name)
- Assign technicians
- Generate a PDF
- Capture signatures / generate a signature link
3) Add inventory to a contract
- On the detail page, open the Inventory section.
- Select an item (or search by name, "Quick add").
- Set the quantity.
- Save. The item is added with its daily rate, if one is configured.
To remove items: click the X / "Remove" next to the entry.
4) Move a contract in the Kanban view
- In the Kanban overview, drag & drop the card into another column.
- In the background,
/dokumente/vertraege/kanban/moveis called. - See the KANBAN plugin for column configuration.
5) Generate the contract PDF
- On the detail page (if TEMPLATING is enabled), select a VERTRAG template in the template dropdown. "Default" uses the default
VERTRAGtemplate. - Click "Generate PDF":
GET /dokumente/vertraege/{id}/pdf. Without parameters the app serves the stored, protected contract PDF (or regenerates it when the contract is not locked). Withtemplate={uuid}the selected template is rendered on the fly. - Optionally, a different document type can be rendered via
type— see section 6 for details.
> The layout / content of the generated documents is controlled by the TEMPLATING plugin. There you create VERTRAG and RECHNUNG templates and choose the default per type.
6) Generate as invoice
- Use the "Generate as invoice" and "Invoice as PDF" buttons on the detail page (only visible when TEMPLATING is enabled).
- "Generate as invoice" opens the HTML view:
GET /dokumente/vertraege/{id}/generate?type=RECHNUNG. - "Invoice as PDF" produces the PDF:
GET /dokumente/vertraege/{id}/pdf?type=RECHNUNG. - Without a
templateparameter the defaultRECHNUNGtemplate is used. Withtemplate={uuid}an explicitly selectedRECHNUNGtemplate is rendered; the type must match the template, otherwise you get an error (HTTP 400). - On-the-fly generated invoices are not stored as contract documents and are not recorded in the change log.
7) Get the contract signed
a) Landlord signature (internal)
- On the detail page, click "Sign as landlord" (
POST /dokumente/vertraege/{id}/sign-vermieter). - Sign with mouse / touchpad / pen → save.
b) Tenant signature (via external link)
- On the detail page, click "Generate signature link" (
POST /dokumente/vertraege/{id}/sign/generate-token). - A token link is generated:
/dokumente/vertraege/sign/{token}. - Send this link to the tenant (e.g., via email).
- The tenant opens the link, sees the contract overview, and signs directly in the browser. No login is required.
- After saving, the signature appears on the contract.
> The link is only valid as long as the token is active and the contract has not yet been fully signed.
8) Delete / restore a contract
- Delete (soft):
POST /dokumente/vertraege/{id}/delete— the contract is hidden but remains in the database. - Restore:
POST /dokumente/vertraege/{id}/restore - Permanently delete:
POST /dokumente/vertraege/{id}/permanent-delete— not recoverable.
9) Filter & search
In the list you can filter by status / Kanban column / tenant / landlord / period. The filters are passed in the URL as query parameters, so you can save the view as a bookmark.
Options (/settings/admin/dokumente/vertrag/options)
Global settings around the contract, e.g.:
- Default tax rate / default values
- Visible fields in the form
- Defaults when creating from a homepage inquiry
Uploads (/settings/admin/dokumente/vertrag/uploads)
Defaults for document uploads (e.g., allowed file types, max size). The uploaded files are physically stored under <tenant-root>/contract-uploads.
"PDF is empty / looks wrong"
- Check the contract template in the TEMPLATING plugin (default template set?).
- Images/logos: is the path correct in the template?
"Tenant cannot open the signature link"
- Was the token really copied and sent unchanged?
- Has the contract already been fully signed? Then the link is "used up".
- A new token may have been generated (the old link becomes invalid).
"Inventory item is missing in the PDF"
- Was the item really saved?
- The inventory block must be active in the template (TEMPLATING).
"Contract is not in the Kanban"
- Is KANBAN active? Is a category assigned? Is the contract not soft-deleted?
User area (/dokumente/vertraege):
GET /dokumente/vertraege— listGET /dokumente/vertraege/new— new contractPOST /dokumente/vertraege— createGET /dokumente/vertraege/{id}— detailPOST /dokumente/vertraege/{id}— saveGET /dokumente/vertraege/{id}/pdf— show PDF (optional:lang,type=VERTRAG|RECHNUNG,template={uuid})GET /dokumente/vertraege/{id}/generate— generate document HTML (optional:lang,type=VERTRAG|RECHNUNG,template={uuid})POST /dokumente/vertraege/{id}/comments— commentPOST /dokumente/vertraege/{id}/documents— upload documentGET /dokumente/vertraege/{id}/documents/{docId}— fetch documentPOST /dokumente/vertraege/{id}/documents/{docId}/delete— delete documentPOST /dokumente/vertraege/{id}/inventar— assign inventoryPOST /dokumente/vertraege/{id}/inventar/by-name— quick-search inventoryPOST /dokumente/vertraege/{id}/inventar/{itemId}/remove— remove itemPOST /dokumente/vertraege/{id}/techniker— set technicianPOST /dokumente/vertraege/{id}/sign-vermieter— landlord signaturePOST /dokumente/vertraege/{id}/sign/generate-token— generate tenant signature linkPOST /dokumente/vertraege/kanban/move— move card between columnsPOST /dokumente/vertraege/{id}/delete— soft deletePOST /dokumente/vertraege/{id}/restore— restorePOST /dokumente/vertraege/{id}/permanent-delete— permanently delete
Since M27 (Issue #522), GET .../pdf and GET .../generate support the
optional query parameters lang (default de), type
(VERTRAG/RECHNUNG; default when omitted: VERTRAG), and template
(UUID of an existing template):
- Without
type/template, the legacy behavior is kept:/pdfserves the
stored protected contract PDF (or regenerates it when the contract is not
locked),/generaterenders the defaultVERTRAGtemplate. - With
typeortemplate, the document is rendered on the fly and not
stored as a contract document (no change-log entry). - Unknown
type, unknowntemplateUUID, or atype/templatemismatch →
HTTP 400 with an i18n error message.
Public (token only):
GET /dokumente/vertraege/sign/{token}— signature pagePOST /dokumente/vertraege/sign/{token}— submit signature
Admin (/settings/admin/dokumente/vertrag):
GET /settings/admin/dokumente/vertrag/optionsPOST /settings/admin/dokumente/vertrag/optionsGET /settings/admin/dokumente/vertrag/uploadsPOST /settings/admin/dokumente/vertrag/uploads
- VERTRAG is a core plugin: it relies on MIETER, VERMIETER, INVENTAR, TEMPLATING, KANBAN, and MAIL. Only enable what you actually need.
- Soft-deleted contracts continue to count in the statistics until they are permanently deleted.
- Short IDs: UUIDs are shown in lists and detail views in short form (e.g. #123e4567). The full UUID is available in the tooltip (on mobile devices by tapping) and can be copied with the copy button next to the short form. Links and URLs continue to use the full UUID.
Contract functionality belongs to the DOKUMENTE plugin; activation and gating deliberately remain on the plugin key VERTRAG (no plugin rename). The seven permission keys were migrated from vertrag.* to dokumente.* (data migration V69, including all role assignments) and appear in the Documents section of the permission matrix:
| Old key (alias) | New key | Effect |
|---|---|---|
vertrag.vertrag.view |
dokumente.vertrag.view |
Show contract list and details |
vertrag.vertrag.create |
dokumente.vertrag.create |
Create new contracts |
vertrag.vertrag.edit |
dokumente.vertrag.edit |
Edit contracts |
vertrag.vertrag.delete |
dokumente.vertrag.delete |
Delete, restore, permanently delete contracts |
vertrag.changelog.view |
dokumente.changelog.view |
Show a contract's changelog |
vertrag.options.view |
dokumente.options.view |
Show contract options and upload settings |
vertrag.options.edit |
dokumente.options.edit |
Edit contract options and upload settings |
The old keys check and write against the new (canonical) key unchanged - PermissionService resolves them via PermissionAliases; a grant for dokumente.vertrag.view therefore also applies to the old key and vice versa. The aliases are a transition phase and will be removed with the M37 follow-up.
Permanent URL redirects: The old contract URLs under /vertrag/** (overview /vertrag/vertraege/**, details, the public signature page /vertrag/sign/{token} including the ?lang= parameter, and the admin paths /settings/admin/vertrag/**) redirect permanently to the new paths under /dokumente/** via HTTP 301 (GET) resp. 307 (POST, preserving method and body) - including path segments and query string. This redirect is permanent and not planned as a temporary transitional component: signature links from e-mails and QR codes with long lifetimes, bookmarks, and backlinks permanently reach their target and cannot be removed.