README

Ein PHP SDK für die Lexoffice API, das programmatischen Zugriff auf die deutsche Buchhaltungssoftware ermöglicht.

Inspiriert vom Projekt eike-grundke/lexoffice-php-sdk, wurde die Struktur komplett überarbeitet.

🚀 Features

Bearer Token Authentifizierung: Einfache API-Key Authentifizierung
Domain-Driven Design: Strikte Trennung zwischen API-Clients, Endpoints, Entities und Contracts
20 Endpoints für umfassende Lexoffice-Integration
Umfassende API-Abdeckung für verschiedene Bereiche:
- Artikel (Articles) - 1 Endpoint
- Kontakte (Contacts) - 1 Endpoint
- Dokumente (Documents) - 8 Endpoints
- Zahlungen (Payments) - 1 Endpoint
- Vouchers - 2 Endpoints
- Event-Subscriptions - 1 Endpoint
- Profile, Länder, Dateien und mehr

📋 Voraussetzungen

PHP 8.2, 8.3 oder 8.4
Lexoffice Account mit API-Zugang
Composer

📦 Installation

composer require daniel-jorg-schuppelius/lexoffice-php-sdk

⚙️ Konfiguration

API-Schlüssel

Um die API zu nutzen, benötigen Sie einen API-Schlüssel aus Ihrem Lexoffice-Account:

Melden Sie sich bei Lexoffice an
Gehen Sie zu Einstellungen → Öffentliche API
Erstellen Sie einen neuen API-Schlüssel

Verbindung zur Lexoffice API

use Lexoffice\API\Client;

$client = new Client('your-api-key');

📚 Verwendung

Beispiel: Artikel abrufen

use Lexoffice\API\Client;
use Lexoffice\API\Endpoints\ArticlesEndpoint;

$client = new Client('your-api-key');
$endpoint = new ArticlesEndpoint($client);

// Einzelnen Artikel abrufen
$article = $endpoint->get($articleId);

Beispiel: Kontakte abrufen

use Lexoffice\API\Client;
use Lexoffice\API\Endpoints\ContactsEndpoint;

$client = new Client('your-api-key');
$endpoint = new ContactsEndpoint($client);

// Kontakt abrufen
$contact = $endpoint->get($contactId);

Beispiel: Rechnung erstellen

use Lexoffice\API\Client;
use Lexoffice\API\Endpoints\Documents\InvoicesEndpoint;
use Lexoffice\Entities\Documents\Invoices\Invoice;

$client = new Client('your-api-key');
$endpoint = new InvoicesEndpoint($client);

// Rechnung erstellen
$invoice = new Invoice($invoiceData);
$result = $endpoint->create($invoice);

Beispiel: Profil abrufen

use Lexoffice\API\Client;
use Lexoffice\API\Endpoints\ProfileEndpoint;

$client = new Client('your-api-key');
$endpoint = new ProfileEndpoint($client);

// Firmenprofil abrufen
$profile = $endpoint->get();

🏗️ Projektstruktur

docs/
├── lexoffice-API-Samples.postman_collection.json  # Postman Collection (korrigiert)
└── NOTES.md                        # Dokumentierte Abweichungen zur offiziellen API

tools/
└── check-endpoint-coverage.php     # Prüft SDK-Abdeckung gegen Postman Collection

src/
├── API/
│   ├── Client.php                  # API Client mit Bearer Auth
│   └── Endpoints/
│       ├── ArticlesEndpoint.php
│       ├── ContactsEndpoint.php
│       ├── CountriesEndpoint.php
│       ├── EventSubscriptionsEndpoint.php
│       ├── FilesEndpoint.php
│       ├── PaymentConditionsEndpoint.php
│       ├── PaymentsEndpoint.php
│       ├── PostingCategoriesEndpoint.php
│       ├── PrintLayoutsEndpoint.php
│       ├── ProfileEndpoint.php
│       ├── VoucherListEndpoint.php
│       ├── VouchersEndpoint.php
│       └── Documents/              # 8 Dokument-Endpoints
│           ├── CreditNotesEndpoint.php
│           ├── DeliveryNotesEndpoint.php
│           ├── DownPaymentInvoicesEndpoint.php
│           ├── DunningsEndpoint.php
│           ├── InvoicesEndpoint.php
│           ├── OrderConfirmationsEndpoint.php
│           ├── QuotationsEndpoint.php
│           └── RecurringTemplatesEndpoint.php
├── Contracts/
│   ├── Abstracts/                  # Basis-Klassen
│   └── Interfaces/                 # Interface-Definitionen
├── Entities/                       # Domain-Entities
└── Enums/                          # Enumerations (20 Typen)

🔌 API-Endpunkte

Artikel & Kontakte

Endpoint	Beschreibung
`ArticlesEndpoint`	Artikelverwaltung
`ContactsEndpoint`	Kontaktverwaltung

Dokumente

Endpoint	Beschreibung
`InvoicesEndpoint`	Rechnungen
`CreditNotesEndpoint`	Gutschriften
`DeliveryNotesEndpoint`	Lieferscheine
`DownPaymentInvoicesEndpoint`	Abschlagsrechnungen
`DunningsEndpoint`	Mahnungen
`OrderConfirmationsEndpoint`	Auftragsbestätigungen
`QuotationsEndpoint`	Angebote
`RecurringTemplatesEndpoint`	Wiederkehrende Vorlagen

Zahlungen & Finanzen

Endpoint	Beschreibung
`PaymentsEndpoint`	Zahlungen
`PaymentConditionsEndpoint`	Zahlungsbedingungen
`VouchersEndpoint`	Belege
`VoucherListEndpoint`	Belegliste
`PostingCategoriesEndpoint`	Buchungskategorien

Sonstiges

Endpoint	Beschreibung
`ProfileEndpoint`	Firmenprofil
`CountriesEndpoint`	Länder
`FilesEndpoint`	Dateien
`PrintLayoutsEndpoint`	Drucklayouts
`EventSubscriptionsEndpoint`	Event-Webhooks

Eingehende Webhooks

Das SDK verwaltet Event-Subscriptions (anlegen, lesen, löschen), enthält aber bewusst keine Signaturprüfung für die eingehenden Callbacks: eine Subscription besteht nur aus eventType und callbackUrl, ein gemeinsames Secret gibt es nicht. Ein eingehendes Event ist deshalb erst dann belastbar, wenn die referenzierte Ressource über die API nachgeladen wurde — der Callback selbst ist ein Hinweis, kein Beleg. (APIToolkit\API\Webhook\WebhookVerifier setzt eine HMAC-Signatur voraus und passt hier nicht.)

🧪 Tests

Test-Konfiguration

Kopieren Sie .samples/postman_config.json.sample nach .samples/postman_config.json
Tragen Sie Ihren Lexoffice API-Key ein

Tests ausführen

composer test
# oder
vendor/bin/phpunit

Hinweis: Die meisten Tests erfordern einen gültigen API-Key und sind daher standardmäßig deaktiviert.

📖 Abhängigkeiten

php-api-toolkit (^2.2) - Basis-Klassen für Clients, Endpoints und Entities
GuzzleHttp - HTTP Client
PSR-3 Logger - Logging-Interface

Toolkit-Features

Das SDK nutzt die erweiterten Funktionen des php-api-toolkit:

Feature	Beschreibung
E-Mail-Validierung	`EmailAddress::isValid()`, `getDomain()`, `isDisposable()`
Telefonnummer-Formatierung	`PhoneNumber::toE164()`, `format()`, `isGermanMobile()`
Adress-Validierung	`Address::isValidZip()`, `getGermanState()`, `getFullAddress()`
Personen-Handling	Strukturierte Vor-/Nachname-Verwaltung mit Anrede

📄 Lizenz

Dieses Projekt ist unter der MIT-Lizenz lizenziert.

💖 Unterstützung

Wenn Ihnen dieses Projekt gefällt und es Ihnen bei Ihrer Arbeit hilft, würde ich mich sehr über eine Spende freuen!

👤 Autor

Daniel Jörg Schuppelius

Website: schuppelius.org
E-Mail: info@schuppelius.org

daniel-jorg-schuppelius / lexoffice-php-sdk

Maintainers

Package info

Statistics

Security