Lexware-API-Vertrag und Lieferantenabgleich korrigieren

Finding: F05 Priorität: P0 Status: OFFEN Stand: 2026-07-16

Problembeschreibung

• Reale Config nutzt api.lexoffice.io; offiziell gilt seit Mai 2025 api.lexware.io, die alte Verfügbarkeit war nur bis Dezember 2025 angekündigt.
• Adapter nutzt /v1/billing-documents und salesinvoice (LexofficeApiAdapter.php:84); Eingangsbelege sind purchaseinvoice, offiziell sind Vouchers/Files.
• Kontaktpayload ist flach statt Roles/Company/Addresses.
• Namensmatch ohne Adresse/Steuer-ID wird akzeptiert (ResolveVendorUseCase.php:33).

Ziel

Integration entspricht dem aktuellen offiziellen Lexware-Vertrag und ordnet nur eindeutig validierte Lieferanten zu.

Aufgabe

1. Gateway/Endpunkte migrieren.
2. Purchaseinvoice über Vouchers/Files modellieren.
3. Vendor-Rolle, Company, Adressen korrekt payloaden; Matching und Contract-Tests ergänzen.

Scope

• In Scope: alle unter Code Blast genannten Komponenten, Daten, Verträge und Tests.
• Out of Scope: neue Features und produktive externe Mutation ohne separate Freigabe.

Harte Spezifikation

• MUST: Base URL https://api.lexware.io.
• MUST: nur offizielle Payloads und purchaseinvoice.
• MUST: Name allein ist kein Match.
• MUST: Status, IDs und Async-Schemas validiert.

Harte Quality Gateways

• Contract-Tests Contacts/Voucherlist/Vouchers/Files.
• Zwei gleichnamige Kontakte führen Review.
• Request-Capture belegt aktuelle URL/Typ/Struktur.
• Live-Smoke GET-only, Mutation nur Testtenant.
• Global: PHPStan Level 8 und PHPUnit liefern 0 Fehler; kein Ignore oder Baseline.

Code Blast

• Direkt: Lexoffice-Credentials, Adapter/Port, Resolve/Post, CLI.
• Extern: Lexware Contacts/Voucherlist/Vouchers/Files.

Code-Impact-Analyse

• Behebt veralteten Gatewayvertrag/falschen Belegtyp.
• Strenger Match erzeugt Review, verhindert falschen Kreditor.

Risikoanalyse

| Risiko | Eintritt | Schaden | |---|---|---| | Alter Gateway/Endpoint | hoch | hoch | | Falscher Belegtyp/Lieferant | mittel | kritisch |

Strategie zur Risikonullierung

1. Prevent: aktuelle Schemas.
2. Detect: Contract/Response.
3. Contain: unklarer Match stoppt.
4. Recover: Remote-ID/Korrelation; https://developers.lexware.io/docs/ .

Abschlussnachweis

Erledigt erst, wenn alle MUST-Spezifikationen implementiert, alle Gateways mit unveränderlicher Evidenz grün und Restrisiken technisch ausgeschlossen oder ausdrücklich fachlich akzeptiert sind.