Docs

VERTRAG

Documentation

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

  1. Open Contract → Contracts (/dokumente/vertraege).
  2. Click "New" (/dokumente/vertraege/new).
  3. Fill in the required fields:
    • Tenant (select or create new)
    • Landlord
    • Period
  4. Save.

2) Edit a contract

  1. Click the contract in the list (/dokumente/vertraege/{id}).
  2. Change fields and save.
  3. 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

  1. On the detail page, open the Inventory section.
  2. Select an item (or search by name, "Quick add").
  3. Set the quantity.
  4. 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/move is called.
  • See the KANBAN plugin for column configuration.

5) Generate the contract PDF

  1. On the detail page (if TEMPLATING is enabled), select a VERTRAG template in the template dropdown. "Default" uses the default VERTRAG template.
  2. 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). With template={uuid} the selected template is rendered on the fly.
  3. 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

  1. Use the "Generate as invoice" and "Invoice as PDF" buttons on the detail page (only visible when TEMPLATING is enabled).
  2. "Generate as invoice" opens the HTML view: GET /dokumente/vertraege/{id}/generate?type=RECHNUNG.
  3. "Invoice as PDF" produces the PDF: GET /dokumente/vertraege/{id}/pdf?type=RECHNUNG.
  4. Without a template parameter the default RECHNUNG template is used. With template={uuid} an explicitly selected RECHNUNG template is rendered; the type must match the template, otherwise you get an error (HTTP 400).
  5. 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)

  1. On the detail page, click "Sign as landlord" (POST /dokumente/vertraege/{id}/sign-vermieter).
  2. Sign with mouse / touchpad / pen → save.

b) Tenant signature (via external link)

  1. On the detail page, click "Generate signature link" (POST /dokumente/vertraege/{id}/sign/generate-token).
  2. A token link is generated: /dokumente/vertraege/sign/{token}.
  3. Send this link to the tenant (e.g., via email).
  4. The tenant opens the link, sees the contract overview, and signs directly in the browser. No login is required.
  5. 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 — list
  • GET /dokumente/vertraege/new — new contract
  • POST /dokumente/vertraege — create
  • GET /dokumente/vertraege/{id} — detail
  • POST /dokumente/vertraege/{id} — save
  • GET /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 — comment
  • POST /dokumente/vertraege/{id}/documents — upload document
  • GET /dokumente/vertraege/{id}/documents/{docId} — fetch document
  • POST /dokumente/vertraege/{id}/documents/{docId}/delete — delete document
  • POST /dokumente/vertraege/{id}/inventar — assign inventory
  • POST /dokumente/vertraege/{id}/inventar/by-name — quick-search inventory
  • POST /dokumente/vertraege/{id}/inventar/{itemId}/remove — remove item
  • POST /dokumente/vertraege/{id}/techniker — set technician
  • POST /dokumente/vertraege/{id}/sign-vermieter — landlord signature
  • POST /dokumente/vertraege/{id}/sign/generate-token — generate tenant signature link
  • POST /dokumente/vertraege/kanban/move — move card between columns
  • POST /dokumente/vertraege/{id}/delete — soft delete
  • POST /dokumente/vertraege/{id}/restore — restore
  • POST /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: /pdf serves the
    stored protected contract PDF (or regenerates it when the contract is not
    locked), /generate renders the default VERTRAG template.
  • With type or template, the document is rendered on the fly and not
    stored as a contract document (no change-log entry).
  • Unknown type, unknown template UUID, or a type/template mismatch →
    HTTP 400 with an i18n error message.

Public (token only):

  • GET /dokumente/vertraege/sign/{token} — signature page
  • POST /dokumente/vertraege/sign/{token} — submit signature

Admin (/settings/admin/dokumente/vertrag):

  • GET /settings/admin/dokumente/vertrag/options
  • POST /settings/admin/dokumente/vertrag/options
  • GET /settings/admin/dokumente/vertrag/uploads
  • POST /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.