justpilot · Oct 26, 2026 · Oct 26, 2026
diff --git a/.gitattributes b/.gitattributes
@@ -16,6 +16,7 @@
 /phpunit.xml.dist       export-ignore
 /rector.php             export-ignore
 /infection.json5        export-ignore
+/lychee.toml            export-ignore
 /.roave-backward-compatibility-check.xml export-ignore
 /.env.test              export-ignore
 

diff --git a/.github/workflows/links.yml b/.github/workflows/links.yml
@@ -0,0 +1,39 @@
+name: Links
+
+on:
+  pull_request:
+    paths: ['**.md', 'docs/**', 'src/**', 'tools/codegen/definitions/**', 'lychee.toml', '.github/workflows/links.yml']
+  push:
+    branches: [4.x]
+    paths: ['**.md', 'docs/**', 'src/**', 'tools/codegen/definitions/**', 'lychee.toml', '.github/workflows/links.yml']
+  # Wöchentlich, damit auch Links auffallen, die ohne Änderung bei uns kaputtgehen.
+  schedule:
+    - cron: '0 6 * * 1'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  lychee:
+    name: Check links
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      - name: Restore lychee cache
+        uses: actions/cache@v6
+        with:
+          path: .lycheecache
+          key: lychee-${{ github.sha }}
+          restore-keys: lychee-
+
+      # Konfiguration in lychee.toml; das Token verhindert das GitHub-Rate-Limit für github.com-Links.
+      - name: Check links
+        uses: lycheeverse/lychee-action@v2
+        with:
+          args: --no-progress --config lychee.toml 'docs/**/*.md' '*.md' 'src/**/*.php' 'tools/codegen/definitions/*.php'
+          fail: true
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
diff --git a/.gitignore b/.gitignore
@@ -53,3 +53,4 @@ Thumbs.db
 /docs/node_modules/
 /docs/.vitepress/cache/
 /docs/.vitepress/dist/
+.lycheecache
diff --git a/AGENTS.md b/AGENTS.md
@@ -46,7 +46,7 @@ CI runs via `.github/workflows/ci.yml` on PHP 8.5 (required) and 8.6 (experiment
 
 ### Documentation website
 
-`docs/` is also a VitePress site (`docs/.vitepress/config.mts`, `docs/package.json`, `cd docs && npm ci && npm run build`), deployed by `.github/workflows/docs.yml` to https://billomat-php.justpilot.io (`docs/public/CNAME`). The sidebar is built from the first `# ` heading of each page; `docs/spec/`, `docs/audit.md` and `docs/roadmap-v4.md` are excluded. Relative links to files outside `docs/` are rewritten to GitHub. Dead links fail the build. The "JSON on the wire" sections between the `json-examples` markers are generated by `tools/generate-json-examples.php` (request bodies captured from the SDK into `docs/snippets/json/`, responses imported from the contract fixtures); never edit them by hand, add a request or page in the tool and run `composer docs:json`.
+`docs/` is also a VitePress site (`docs/.vitepress/config.mts`, `docs/package.json`, `cd docs && npm ci && npm run build`), deployed by `.github/workflows/docs.yml` to https://billomat-php.justpilot.io (`docs/public/CNAME`). The sidebar is built from the first `# ` heading of each page; `docs/spec/`, `docs/audit.md` and `docs/roadmap-v4.md` are excluded. Relative links to files outside `docs/` are rewritten to GitHub. Dead links fail the build; external links (docs, root Markdown, docblocks) are checked by lychee in `.github/workflows/links.yml` (config `lychee.toml`, also weekly). The "JSON on the wire" sections between the `json-examples` markers are generated by `tools/generate-json-examples.php` (request bodies captured from the SDK into `docs/snippets/json/`, responses imported from the contract fixtures); never edit them by hand, add a request or page in the tool and run `composer docs:json`.
 
 ## Architecture
 

diff --git a/docs/testing.md b/docs/testing.md
@@ -202,7 +202,8 @@ PHPStan runs without a baseline: every finding fails CI and is fixed in the code
 2. **PSR-18 compat** — a smoke test with Guzzle and without Symfony (`.github/compat/guzzle`).
 3. **Quality** — `composer lint`, `composer analyse`, `composer refactor:dry`, `composer generate:check`, `composer audit`.
 4. **Backward compatibility** — [`roave/backward-compatibility-check`](https://github.com/Roave/BackwardCompatibilityCheck) compares the public API against the latest `v4.*` tag. Accepted findings go into `.roave-backward-compatibility-check.xml`. Until 4.0.0-beta.1 the job is informational (`continue-on-error`).
-5. **Mutation testing** — on PRs only the changed lines (`--git-diff-lines`, 90 % MSI); on `main`/`4.x` the full run with the thresholds from `infection.json5`.
+5. **Links** (`.github/workflows/links.yml`, separate workflow) — [lychee](https://lychee.cli.rs) checks the links in `docs/`, the root Markdown files and the Billomat links in the docblocks (`src/`, `tools/codegen/definitions/`), configured in `lychee.toml`. It also runs weekly to catch links that break without a change on our side.
+6. **Mutation testing** — on PRs only the changed lines (`--git-diff-lines`, 90 % MSI); on `main`/`4.x` the full run with the thresholds from `infection.json5`.
 
 To run the BC check locally, install the tool outside the project (it needs Symfony 7 components) and call it from the repository root:
 

diff --git a/lychee.toml b/lychee.toml
@@ -0,0 +1,28 @@
+# Link-Check (lychee) für Doku, README, CHANGELOG und die Billomat-Links in den Docblocks.
+# Läuft in .github/workflows/links.yml; lokal: lychee 'docs/**/*.md' '*.md' 'src/**/*.php' 'tools/codegen/definitions/*.php'
+
+exclude_path = [
+    "docs/node_modules",
+    "docs/.vitepress",
+    "docs/spec",
+    "docs/audit.md",
+    "docs/roadmap-v4.md",
+    "vendor",
+    "build",
+    "graphify-out",
+]
+
+# Platzhalter aus Beispielen, keine echten Ziele.
+exclude = [
+    '^https?://([a-z0-9-]+\.)?example\.(com|org|net)',
+    '^https?://mycompany\.billomat\.net',
+    '^https?://localhost',
+]
+
+max_concurrency = 8
+max_retries = 3
+# 429: der Server lebt, er drosselt nur.
+accept = ["200..=299", "429"]
+
+cache = true
+max_cache_age = "1d"
diff --git a/src/Api/ConfirmationCommentCreateOptions.php b/src/Api/ConfirmationCommentCreateOptions.php
@@ -12,7 +12,7 @@
  * Null-Werte bedeuten "nicht gesetzt" und werden beim Serialisieren ignoriert.
  *
  * Doku:
- * https://www.billomat.com/en/api/confirmations/comments/
+ * https://www.billomat.com/api/auftragsbestaetigungen/
  *
  * Generiert aus tools/codegen/definitions/confirmation-comments.php – nicht von Hand bearbeiten,
  * sondern die Definition anpassen und `composer generate` ausführen.

diff --git a/src/Api/ConfirmationItemCreateOptions.php b/src/Api/ConfirmationItemCreateOptions.php
@@ -14,7 +14,7 @@
  * Null-Werte bedeuten "nicht gesetzt" und werden beim Serialisieren ignoriert.
  *
  * Doku:
- * https://www.billomat.com/en/api/confirmations/items/
+ * https://www.billomat.com/api/auftragsbestaetigungen/
  *
  * Generiert aus tools/codegen/definitions/confirmation-items.php – nicht von Hand bearbeiten,
  * sondern die Definition anpassen und `composer generate` ausführen.

diff --git a/src/Api/ConfirmationItemUpdateOptions.php b/src/Api/ConfirmationItemUpdateOptions.php
@@ -14,7 +14,7 @@
  * Billomat lässt nicht gesendete Felder unverändert.
  *
  * Doku:
- * https://www.billomat.com/en/api/confirmations/items/
+ * https://www.billomat.com/api/auftragsbestaetigungen/
  *
  * Generiert aus tools/codegen/definitions/confirmation-items.php – nicht von Hand bearbeiten,
  * sondern die Definition anpassen und `composer generate` ausführen.

diff --git a/src/Api/ConfirmationTagCreateOptions.php b/src/Api/ConfirmationTagCreateOptions.php
@@ -8,7 +8,7 @@
  * Typisierter Payload für POST /confirmation-tags gemäß Billomat-API.
  *
  * Doku:
- * https://www.billomat.com/en/api/confirmations/tags/
+ * https://www.billomat.com/api/auftragsbestaetigungen/
  *
  * Generiert aus tools/codegen/definitions/confirmation-tags.php – nicht von Hand bearbeiten,
  * sondern die Definition anpassen und `composer generate` ausführen.

diff --git a/src/Api/DeliveryNoteCommentCreateOptions.php b/src/Api/DeliveryNoteCommentCreateOptions.php
@@ -12,7 +12,7 @@
  * Null-Werte bedeuten "nicht gesetzt" und werden beim Serialisieren ignoriert.
  *
  * Doku:
- * https://www.billomat.com/en/api/delivery-notes/comments/
+ * https://www.billomat.com/api/lieferscheine/
  *
  * Generiert aus tools/codegen/definitions/delivery-note-comments.php – nicht von Hand bearbeiten,
  * sondern die Definition anpassen und `composer generate` ausführen.

diff --git a/src/Api/DeliveryNoteItemCreateOptions.php b/src/Api/DeliveryNoteItemCreateOptions.php
@@ -14,7 +14,7 @@
  * Null-Werte bedeuten "nicht gesetzt" und werden beim Serialisieren ignoriert.
  *
  * Doku:
- * https://www.billomat.com/en/api/delivery-notes/items/
+ * https://www.billomat.com/api/lieferscheine/
  *
  * Generiert aus tools/codegen/definitions/delivery-note-items.php – nicht von Hand bearbeiten,
  * sondern die Definition anpassen und `composer generate` ausführen.

diff --git a/src/Api/DeliveryNoteItemUpdateOptions.php b/src/Api/DeliveryNoteItemUpdateOptions.php
@@ -14,7 +14,7 @@
  * Billomat lässt nicht gesendete Felder unverändert.
  *
  * Doku:
- * https://www.billomat.com/en/api/delivery-notes/items/
+ * https://www.billomat.com/api/lieferscheine/
  *
  * Generiert aus tools/codegen/definitions/delivery-note-items.php – nicht von Hand bearbeiten,
  * sondern die Definition anpassen und `composer generate` ausführen.

diff --git a/src/Api/InboxDocumentCreateOptions.php b/src/Api/InboxDocumentCreateOptions.php
@@ -7,7 +7,7 @@
 /**
  * Payload für POST /inbox-documents.
  *
- * Doku: https://www.billomat.com/en/api/inbox-documents/
+ * Doku: https://www.billomat.com/api/eingangsrechnungen/inbox/
  */
 final readonly class InboxDocumentCreateOptions implements WriteOptions
 {

diff --git a/src/Api/InboxDocumentsApi.php b/src/Api/InboxDocumentsApi.php
@@ -13,7 +13,7 @@
 /**
  * API-Wrapper für Posteingangs-Dokumente (Inbox Documents).
  *
- * Doku: https://www.billomat.com/en/api/inbox-documents/
+ * Doku: https://www.billomat.com/api/eingangsrechnungen/inbox/
  *
  * Endpoints:
  *  - GET    /inbox-documents

diff --git a/src/Api/RecurringEmailReceiversApi.php b/src/Api/RecurringEmailReceiversApi.php
@@ -22,7 +22,7 @@
  *  - PUT    /recurring-email-receivers/{id}
  *  - DELETE /recurring-email-receivers/{id}
  *
- * Doku: https://www.billomat.com/api/abo-rechnungen/email-empfaenger/
+ * Doku: https://www.billomat.com/api/abo-rechnungen/empfaenger/
  *
  * @extends AbstractSubResourceApi<RecurringEmailReceiver>
  */

diff --git a/src/Api/ReminderItemsApi.php b/src/Api/ReminderItemsApi.php
@@ -19,7 +19,7 @@
  *  - GET /reminder-items?reminder_id={id}
  *  - GET /reminder-items/{id}
  *
- * Doku: https://www.billomat.com/en/api/reminders/items/
+ * Doku: https://www.billomat.com/api/mahnungen/positionen/
  *
  * @extends AbstractSubResourceApi<ReminderItem>
  */

diff --git a/src/Model/ConfirmationComment.php b/src/Model/ConfirmationComment.php
@@ -22,7 +22,7 @@
  *    enthält den ursprünglichen String aus der API.
  *
  * Dokumentation:
- * https://www.billomat.com/en/api/confirmations/comments/
+ * https://www.billomat.com/api/auftragsbestaetigungen/
  *
  * Generiert aus tools/codegen/definitions/confirmation-comments.php – nicht von Hand bearbeiten,
  * sondern die Definition anpassen und `composer generate` ausführen.

diff --git a/src/Model/ConfirmationItem.php b/src/Model/ConfirmationItem.php
@@ -13,7 +13,7 @@
  * Dieses Model bildet die Struktur von GET /confirmation-items?confirmation_id={id} bzw. GET /confirmation-items/{id} ab.
  *
  * Dokumentation:
- * https://www.billomat.com/en/api/confirmations/items/
+ * https://www.billomat.com/api/auftragsbestaetigungen/
  *
  * Generiert aus tools/codegen/definitions/confirmation-items.php – nicht von Hand bearbeiten,
  * sondern die Definition anpassen und `composer generate` ausführen.

diff --git a/src/Model/ConfirmationTag.php b/src/Model/ConfirmationTag.php
@@ -12,7 +12,7 @@
  * Dieses Model bildet die Struktur von GET /confirmation-tags?confirmation_id={id} bzw. GET /confirmation-tags/{id} ab.
  *
  * Dokumentation:
- * https://www.billomat.com/en/api/confirmations/tags/
+ * https://www.billomat.com/api/auftragsbestaetigungen/
  *
  * Generiert aus tools/codegen/definitions/confirmation-tags.php – nicht von Hand bearbeiten,
  * sondern die Definition anpassen und `composer generate` ausführen.

diff --git a/src/Model/ConfirmationTagCloudEntry.php b/src/Model/ConfirmationTagCloudEntry.php
@@ -12,7 +12,7 @@
  * Jedes Schlagwort wird einmal mit seiner Häufigkeit geliefert.
  *
  * Dokumentation:
- * https://www.billomat.com/en/api/confirmations/tags/
+ * https://www.billomat.com/api/auftragsbestaetigungen/
  *
  * Generiert aus tools/codegen/definitions/confirmation-tags.php – nicht von Hand bearbeiten,
  * sondern die Definition anpassen und `composer generate` ausführen.

diff --git a/src/Model/DeliveryNoteComment.php b/src/Model/DeliveryNoteComment.php
@@ -22,7 +22,7 @@
  *    enthält den ursprünglichen String aus der API.
  *
  * Dokumentation:
- * https://www.billomat.com/en/api/delivery-notes/comments/
+ * https://www.billomat.com/api/lieferscheine/
  *
  * Generiert aus tools/codegen/definitions/delivery-note-comments.php – nicht von Hand bearbeiten,
  * sondern die Definition anpassen und `composer generate` ausführen.

diff --git a/src/Model/DeliveryNoteItem.php b/src/Model/DeliveryNoteItem.php
@@ -13,7 +13,7 @@
  * Dieses Model bildet die Struktur von GET /delivery-note-items?delivery_note_id={id} bzw. GET /delivery-note-items/{id} ab.
  *
  * Dokumentation:
- * https://www.billomat.com/en/api/delivery-notes/items/
+ * https://www.billomat.com/api/lieferscheine/
  *
  * Generiert aus tools/codegen/definitions/delivery-note-items.php – nicht von Hand bearbeiten,
  * sondern die Definition anpassen und `composer generate` ausführen.

diff --git a/src/Model/Enum/ConfirmationCommentActionKey.php b/src/Model/Enum/ConfirmationCommentActionKey.php
@@ -7,7 +7,7 @@
 /**
  * Typ eines Confirmation-Kommentars (actionkey).
  *
- * Doku: https://www.billomat.com/en/api/confirmations/comments/
+ * Doku: https://www.billomat.com/api/auftragsbestaetigungen/
  */
 enum ConfirmationCommentActionKey: string
 {

diff --git a/src/Model/Enum/DeliveryNoteCommentActionKey.php b/src/Model/Enum/DeliveryNoteCommentActionKey.php
@@ -7,7 +7,7 @@
 /**
  * Typ eines DeliveryNote-Kommentars (actionkey).
  *
- * Doku: https://www.billomat.com/en/api/delivery-notes/comments/
+ * Doku: https://www.billomat.com/api/lieferscheine/
  */
 enum DeliveryNoteCommentActionKey: string
 {

diff --git a/src/Model/Enum/OfferCommentActionKey.php b/src/Model/Enum/OfferCommentActionKey.php
@@ -13,7 +13,7 @@
  * Unbekannte Werte werden über `tryFrom()` als null behandelt; der Roh-String
  * wird im Modell zusätzlich aufgehoben.
  *
- * Doku: https://www.billomat.com/en/api/estimates/comments/
+ * Doku: https://www.billomat.com/api/angebote/kommentare/
  */
 enum OfferCommentActionKey: string
 {

diff --git a/src/Model/Enum/RecurringEmailReceiverType.php b/src/Model/Enum/RecurringEmailReceiverType.php
@@ -7,7 +7,7 @@
 /**
  * Typ eines E-Mail-Empfängers bei einer Abo-Rechnung.
  *
- * Doku: https://www.billomat.com/api/abo-rechnungen/email-empfaenger/
+ * Doku: https://www.billomat.com/api/abo-rechnungen/empfaenger/
  */
 enum RecurringEmailReceiverType: string
 {

diff --git a/src/Model/InboxDocument.php b/src/Model/InboxDocument.php
@@ -12,7 +12,7 @@
 /**
  * Posteingangs-Dokument (Inbox Document).
  *
- * Doku: https://www.billomat.com/en/api/inbox-documents/
+ * Doku: https://www.billomat.com/api/eingangsrechnungen/inbox/
  */
 final readonly class InboxDocument
 {

diff --git a/tests/Integration/Recurrings/RecurringsIntegrationTest.php b/tests/Integration/Recurrings/RecurringsIntegrationTest.php
@@ -199,9 +199,9 @@ public function canManageRecurringEmailReceiversInSandbox(): void
     {
         $billomat = $this->createBillomatClientOrSkip();
 
-        // E-Mail-Empfänger setzen ein Recurring voraus, das überhaupt Mails verschickt.
-        // Daher action=EMAIL mit minimalen E-Mail-Feldern. startDate weit in der Zukunft
-        // verhindert ungewollten Versand.
+        // Billomat nimmt Empfänger bei jeder action an (auch CREATE), wirksam werden sie aber nur
+        // beim Versand. Der Test nutzt daher action=EMAIL mit minimalen E-Mail-Feldern; startDate
+        // weit in der Zukunft verhindert ungewollten Versand.
         $opts = $this->buildSafeDraft($billomat)
             ->withAction(RecurringAction::EMAIL)
             ->withEmailSubject('Integrationstest Abo-Versand')

diff --git a/tools/codegen/definitions/confirmation-comments.php b/tools/codegen/definitions/confirmation-comments.php
@@ -15,5 +15,5 @@
     label: 'einer Auftragsbestätigung',
     parentField: 'confirmation_id',
     specResource: null,
-    docUrl: 'https://www.billomat.com/en/api/confirmations/comments/',
+    docUrl: 'https://www.billomat.com/api/auftragsbestaetigungen/',
 );
diff --git a/tools/codegen/definitions/confirmation-items.php b/tools/codegen/definitions/confirmation-items.php
@@ -15,5 +15,5 @@
     label: 'Position einer Auftragsbestätigung',
     parentField: 'confirmation_id',
     specResource: null,
-    docUrl: 'https://www.billomat.com/en/api/confirmations/items/',
+    docUrl: 'https://www.billomat.com/api/auftragsbestaetigungen/',
 );
diff --git a/tools/codegen/definitions/confirmation-tags.php b/tools/codegen/definitions/confirmation-tags.php
@@ -15,5 +15,5 @@
     label: 'einer Auftragsbestätigung',
     parentField: 'confirmation_id',
     specResource: null,
-    docUrl: 'https://www.billomat.com/en/api/confirmations/tags/',
+    docUrl: 'https://www.billomat.com/api/auftragsbestaetigungen/',
 );
diff --git a/tools/codegen/definitions/delivery-note-comments.php b/tools/codegen/definitions/delivery-note-comments.php
@@ -15,5 +15,5 @@
     label: 'einem Lieferschein',
     parentField: 'delivery_note_id',
     specResource: null,
-    docUrl: 'https://www.billomat.com/en/api/delivery-notes/comments/',
+    docUrl: 'https://www.billomat.com/api/lieferscheine/',
 );
diff --git a/tools/codegen/definitions/delivery-note-items.php b/tools/codegen/definitions/delivery-note-items.php
@@ -15,6 +15,6 @@
     label: 'Lieferscheinposition',
     parentField: 'delivery_note_id',
     specResource: null,
-    docUrl: 'https://www.billomat.com/en/api/delivery-notes/items/',
+    docUrl: 'https://www.billomat.com/api/lieferscheine/',
     optionsOnly: ['unit_price', 'tax_name', 'tax_rate', 'reduction', 'total_gross', 'total_net', 'total_gross_unreduced', 'total_net_unreduced', 'created'],
 );