README

Ein PHP SDK für die DATEV Desktop API (DATEVconnect) und die DATEV Online-APIs (Cloud-Datenservices), das programmatischen Zugriff auf die deutsche Buchhaltungs- und Lohnabrechnungssoftware ermöglicht.

🚀 Features

Flexible Authentifizierung: Basic Auth, Bearer Token und OAuth2 über austauschbare Authentication-Klassen
Domain-Driven Design: Strikte Trennung zwischen API-Clients, Endpoints, Entities und Contracts
Über 120 Desktop-Endpoints für umfassende DATEVconnect-Integration:
- Buchhaltung (Accounting) - 34 Endpoints
- Mandantenstammdaten (Client Master Data) - 19 Endpoints
- Lohn & Gehalt (Payroll/HR) - 32 Endpoints
- Dokumentenmanagement (DMS) - 11 Endpoints
- Auftragsverwaltung (Order Management) - 21 Endpoints
- Rechtswesen (Law) - 15 Endpoints
- Öffentlicher Sektor (Public Sector) - 12 Endpoints
- Identity & Access Management (SCIM) - 5 Endpoints
- Diagnostics - 2 Endpoints
14 DATEV Online-Dienste (Cloud) mit 111 Operationen vollständig abgedeckt:
- accounting-clients, accounting:documents (Belegbilderservice), accounting:dxso-jobs, accounting:extf-files, Accounting Data Exchange (Buchungsdatenservice)
- hr:exchange, hr:exports, hr:files, hr:payrollreports, hr:eau, Datenservice Dokumente Personalwirtschaft
- cashregister:import (Kassenarchiv), Health-Endpunkte (master-data, my-tax)
Async-Job-Unterstützung (202 + Location, State-Polling, mehrstufige Jobs) über einen konfigurierbaren JobPoller

📋 Voraussetzungen

PHP 8.2, 8.3 oder 8.4
DATEV Software mit aktivierter Desktop API (läuft standardmäßig auf Port 58452)
Composer

📦 Installation

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

⚙️ Konfiguration

Verbindung zur DATEV Desktop API

Die API läuft standardmäßig auf https://127.0.0.1:58452.

Authentifizierung

HTTP Basic Auth (empfohlen):

use APIToolkit\API\Authentication\BasicAuthentication;
use Datev\API\Desktop\Client;

$authentication = new BasicAuthentication('Benutzer', 'Passwort');
$client = new Client($authentication, 'https://127.0.0.1:58452');

Bearer Token Auth:

use APIToolkit\API\Authentication\BearerAuthentication;
use Datev\API\Desktop\Client;

$authentication = new BearerAuthentication(
    'your-api-key',
    ['X-Datev-Client-ID' => 'your-client-id']
);
$client = new Client($authentication, 'https://127.0.0.1:58452');

📚 Verwendung

Beispiel: Mandanten abrufen (Accounting)

use APIToolkit\API\Authentication\BasicAuthentication;
use Datev\API\Desktop\Client;
use Datev\API\Desktop\Endpoints\Accounting\ClientsEndpoint;

$client = new Client(new BasicAuthentication('user', 'password'));
$endpoint = new ClientsEndpoint($client);

// Alle Mandanten abrufen
$clients = $endpoint->get();

// Einzelnen Mandanten abrufen
$singleClient = $endpoint->get(id: $clientId);

Beispiel: Mitarbeiter abrufen (Payroll)

use APIToolkit\API\Authentication\BasicAuthentication;
use Datev\API\Desktop\Client;
use Datev\API\Desktop\Endpoints\Payroll\EmployeesEndpoint;
use Datev\Entities\Common\Clients\ClientID;

$client = new Client(new BasicAuthentication('user', 'password'));
$endpoint = new EmployeesEndpoint($client, clientID: new ClientID('<mandanten-guid>'));

// reference-date ist Pflicht; ohne Angabe nimmt search() das heutige Datum
$employees = $endpoint->search(['reference-date' => '2024-01-01']);
$employee  = $endpoint->get($employeeId, expand: 'all', referenceDate: new DateTime('2024-01-01'));

Beispiel: Echo-Test (Verbindung prüfen)

use APIToolkit\API\Authentication\BasicAuthentication;
use Datev\API\Desktop\Client;
use Datev\API\Desktop\Endpoints\Diagnostics\EchoEndpoint;

$client = new Client(new BasicAuthentication('user', 'password'));
$echoEndpoint = new EchoEndpoint($client);

$response = $echoEndpoint->get();

🏗️ Projektstruktur

src/
├── API/
│   └── Desktop/
│       ├── Client.php              # API Client (unterstützt alle Auth-Typen)
│       └── Endpoints/
│           ├── Accounting/         # 34 Endpoints (accounting/v1)
│           ├── ClientMasterData/   # 19 Endpoints (master-data/v1)
│           ├── Diagnostics/        # 2 Endpoints (Echo & Domains)
│           ├── DocumentManagement/ # 11 Endpoints (dms/v2)
│           ├── IdentityAndAccessManagement/  # 5 Endpoints (SCIM)
│           ├── Law/                # 15 Endpoints (law/v1)
│           ├── OrderManagement/    # 21 Endpoints
│           ├── Payroll/            # 32 Endpoints (hr/v3)
│           └── PublicSector/       # 12 Endpoints (public-sector/v1)
├── Contracts/
│   ├── Abstracts/                  # Basis-Klassen
│   └── Interfaces/                 # Interface-Definitionen
├── Entities/                       # Domain-Entities
└── Enums/                          # Enumerations (20+ Typen)

🔌 API-Endpunkte

Accounting (`accounting/v1`)

Buchungssätze, Kostenstellen, Konten, Kreditoren, Debitoren und mehr.

Endpoint	Beschreibung
`ClientsEndpoint`	Mandantenverwaltung
`AccountingRecordsEndpoint`	Buchungssätze
`AccountingSequencesEndpoint`	Buchungsstapel
`GeneralLedgerAccountsEndpoint`	Sachkonten
`CreditorsEndpoint` / `DebitorsEndpoint`	Kreditoren & Debitoren
`CostCentersEndpoint`	Kostenstellen
`FiscalYearsEndpoint`	Wirtschaftsjahre
`TermsOfPaymentEndpoint`	Zahlungsbedingungen
`PostingProposal*Endpoint`	Buchungsvorschläge (Kasse, Ein-/Ausgangsrechnungen)
... und 24 weitere

Client Master Data (`master-data/v1`)

Mandantenstammdaten, Adressaten und Finanzämter.

Endpoint	Beschreibung
`ClientsEndpoint`	Mandantenstammdaten
`AddresseesEndpoint`	Adressatenverwaltung
`TaxAuthoritiesEndpoint`	Finanzämter
`BanksEndpoint`	Bankverbindungen
`LegalFormsEndpoint`	Rechtsformen
`ClientCategoriesEndpoint`	Mandantenkategorien
`RelationshipsEndpoint`	Beziehungen
... und 12 weitere

Payroll / HR (`hr/v3`)

Lohn- und Gehaltsabrechnung. Hinweis: Alle HR-Endpoints erfordern ein reference-date.

Endpoint	Beschreibung
`EmployeesEndpoint`	Mitarbeiterverwaltung
`SalariesEndpoint`	Gehälter
`SocialInsuranceEndpoint`	Sozialversicherung
`TaxationEndpoint`	Besteuerung
`WorkingHoursEndpoint`	Arbeitszeiten
`VacationEntitlementEndpoint`	Urlaubsansprüche
`GrossPaymentsEndpoint`	Bruttobezüge
... und 25 weitere

Document Management (`dms/v2`)

Dokumentenverwaltung und Archivierung.

Endpoint	Beschreibung
`DocumentsEndpoint`	Dokumentverwaltung
`DocumentFilesEndpoint`	Dateien zu Dokumenten
`DocumentStatesEndpoint`	Dokumentstatus
`DomainsEndpoint`	Mandantenbereiche
`StructureItemsEndpoint`	Strukturelemente (Dateien) eines Dokuments, mit `document_file_id` für `DocumentFilesEndpoint`
`SecureAreasEndpoint`	Sicherheitsbereiche
... und 5 weitere

Order Management

Auftragsverwaltung mit Gebührenplanung.

Endpoint	Beschreibung
`OrdersEndpoint`	Aufträge
`InvoicesEndpoint`	Rechnungen
`FeePlansEndpoint`	Gebührenpläne
`ChargeRatesEndpoint`	Verrechnungssätze
`CostItemsEndpoint`	Kostenträger
`ExpensePostingsEndpoint`	Auslagenbuchungen
... und 15 weitere

Law (`law/v1`)

Aktenverwaltung für Rechtsanwälte und Notare.

Endpoint	Beschreibung
`FilesEndpoint`	Akten
`ExpensesEndpoint`	Auslagen
`FeeVersionsEndpoint`	Gebührenversionen
`CausesEndpoint`	Fallursachen
`PartyRolesEndpoint`	Parteirollen
`SecurityZonesEndpoint`	Sicherheitszonen
... und 9 weitere

Public Sector (`public-sector/v1`)

Kommunalverwaltung und öffentlicher Sektor.

Endpoint	Beschreibung
`CitizensEndpoint`	Bürgerverwaltung
`MetersEndpoint`	Zählerverwaltung
`MeterReadingsEndpoint`	Zählerablesungen
`NotificationsEndpoint`	Bescheide
`DuesEndpoint`	Gebühren
`ConsumptionsEndpoint`	Verbrauchsdaten
... und 6 weitere

Identity & Access Management (SCIM)

Benutzer- und Gruppenverwaltung nach SCIM-Standard.

Endpoint	Beschreibung
`UsersEndpoint`	Benutzerverwaltung
`GroupsEndpoint`	Gruppenverwaltung
`SchemasEndpoint`	SCIM-Schemas
`ResourceTypesEndpoint`	Ressourcentypen
`ServiceProviderConfigEndpoint`	Provider-Konfiguration

Diagnostics

Verbindungstests und Systemdiagnose.

Endpoint	Beschreibung
`EchoEndpoint`	Verbindungstest
`DomainsEndpoint`	Verfügbare Domains

☁️ DATEV Online-APIs (Cloud)

Neben der lokalen Desktop API deckt das SDK alle 14 DATEV-Online-Dienste vollständig ab (src/API/Online/). Jeder Dienst hat einen eigenen Host (https://<service>.api.datev.de/platform[-sandbox]/vN); die Dienstfakten (Host, Basispfad, Header-Schreibweise) kapselt das Enum Datev\API\Online\OnlineService.

Client und Authentifizierung

Die Authentifizierung erfolgt per OAuth2-Bearer-Token plus X-DATEV-Client-Id-Header. Die Token-Beschaffung (Authorization Code Flow über login.datev.de) ist Sache des Aufrufers — das php-api-toolkit liefert dafür OAuth2AuthorizationCodeGrant und OAuth2BearerAuthentication.

use APIToolkit\API\Authentication\BearerAuthentication;
use Datev\API\Online\{Client, OnlineService};

$client = new Client(
    OnlineService::AccountingClients,
    new BearerAuthentication($accessToken),
    'meine-datev-client-id',   // X-DATEV-Client-Id
    sandbox: true               // /platform-sandbox statt /platform
);

// ApiKey-only-Dienste (Kassenarchiv, Health-Endpunkte):
$cashClient = Client::forApiKey(OnlineService::CashRegister, $clientId, $clientSecret);

Beispiel: Mandanten und Belegtransfer

use Datev\API\Online\Endpoints\AccountingClients\ClientsEndpoint;
use Datev\API\Online\Endpoints\AccountingDocuments\DocumentsEndpoint;

// Mandantenliste inkl. freigeschalteter Datenservices (OData-Paging)
$clients = (new ClientsEndpoint($client))->searchPage(['top' => 100]);
echo $clients->getTotalItems();

// Beleg hochladen (Belegbilderservice, multipart)
$documents = new DocumentsEndpoint($documentsClient, '29098-55003');
$document = $documents->upload(
    file_get_contents('rechnung.pdf'),
    'rechnung.pdf',
    ['document_type' => 'Rechnungseingang', 'note' => 'Juli 2026']
);

Beispiel: EXTF-Import mit Job-Polling

use Datev\API\Online\Endpoints\AccountingExtfFiles\ExtfFilesEndpoint;
use Datev\Enums\Online\ExtfJobResult;

$extf = new ExtfFilesEndpoint($extfClient, '29098-100');   // Verbundnummer
$jobLocation = $extf->import($extfContent, 'EXTF_Buchungsstapel.csv');
$job = $extf->waitForImport($jobLocation);                  // pollt bis succeeded/failed

if ($job?->getResult() === ExtfJobResult::Failed) {
    echo $job->getValidationDetails()?->getDetail();
}

Online-Dienste im Überblick

Dienst (`OnlineService::…`)	Endpoints	Besonderheiten
`AccountingClients`	Mandanten + Datenservices	OData `top/skip/filter`, `Link`/`Total-Items`-Paging
`AccountingDocuments`	Belegbilderservice	Multipart-Uploads, stapled Documents
`AccountingDxsoJobs`	DXSO-Datentransfer	create → addFile → finalize → Status/Protokoll
`AccountingExtfFiles`	EXTF-Import	octet-stream + `Filename`-Header, 202 + Location
`AccountingDataExchange`	Buchungsdatenservice	ndjson-Antworten, Header-Paging, Export-Jobs
`CashRegister`	Kassenarchiv	Tenant-Adressierung, ApiKey-only
`HrExchange`	Lohn-Datenaustausch	Alle Writes 202-async, Lese-Jobs, RestHooks
`HrExports`	Lohn-Auswertungsdaten	Zeitraumfilter, Arbeitnehmer-/Mandantenebene
`HrFiles`	Lohn-Importdateien	Multipart ≤3 MB, Job-Status
`HrPayrollReports`	Auswertungs-PDFs	PDF/ZIP-Download via Accept-Negotiation
`HrEau`	eAU-Anfragen	Verbundnummer + Personalnummer
`HrDocuments`	Personalakte-Dokumente	Duale Adressierung (GUID/Verbundnummer)
`MasterClientsHealth`, `MyTaxHealth`	Healthchecks	ApiKey-only

Die Abdeckung lässt sich jederzeit prüfen: php tools/OpenApiCoverageAnalyzer.php --type=Online.

🧪 Tests

Test-Konfiguration

Kopieren Sie .samples/config.json.sample nach tests/.samples/config.json
Tragen Sie Ihre DATEV-Zugangsdaten ein:

{
    "DATEV-DESKTOP-API": [
        {
            "key": "resourceurl",
            "value": "https://127.0.0.1:58452"
        },
        {
            "key": "user",
            "value": "IhrBenutzer"
        },
        {
            "key": "password",
            "value": "IhrPasswort"
        }
    ]
}

Tests ausführen

composer test
# oder
vendor/bin/phpunit

# Endpoint-Tests im Mock-Modus (ohne DATEV-Installation, inkl. aller Online-Dienste):
DATEV_SKIP_API_TESTS=0 DATEV_FORCE_MOCK=1 vendor/bin/phpunit

Drei Offline-Prüfungen laufen immer mit und vergleichen das SDK mit den OpenAPI-Dateien unter docs/OpenAPI/Desktop und docs/OpenAPI/Online:

tests/API/OpenApiPathTest.php ruft jede öffentliche Methode der Endpunkte auf und verlangt, dass jeder gebaute Pfad in der Spec steht; bei Desktop zusätzlich, dass er den deklarierten endpointSuffix enthält. Methoden ohne Gegenstück in der Spec sind @deprecated und stehen mit Grund in einer Ausnahmeliste.
tests/API/OpenApiResponseTest.php liest für jede GET-Operation ein aus dem Antwortschema erzeugtes Beispiel mit der zurückgegebenen Entität ein und verlangt jedes Feld zurück, auch in verschachtelten Objekten und Listen. Außerdem müssen die Feldtypen zur Spec passen und Enums alle Spec-Werte kennen.
tests/Entities/OpenApiSchemaCoverageTest.php prüft Schemas, die über keine GET-Operation erreichbar sind (Anfrage-Bodies, eingebettete Objekte), Feld für Feld.

Bekannte Grenze: Entitäten bilden JSON-Schlüssel direkt auf Properties ab. Schlüssel, die kein PHP-Bezeichner sind, kommen deshalb nicht an: im Auftragswesen die Verkaufswerte (time_costs (sales_value) und Geschwister in Monatswerten und Teilaufträgen), in der Benutzerverwaltung (SCIM) $ref und die urn:ietf:params:scim:…-Erweiterungen.

Hinweis: Die Endpoint-Tests erfordern standardmäßig eine laufende DATEV-Installation und sind daher deaktiviert (DATEV_SKIP_API_TESTS=1 in phpunit.xml.dist). Im Mock-Modus werden die Antworten aus den OpenAPI-Spezifikationen in docs/OpenAPI/ generiert.

Online-Live-Tests: Mit DATEV_ONLINE_LIVE=1 und dem Abschnitt DATEV-ONLINE-API in .samples/config.json (Sandbox-Bearer-Token + DATEV-Client-Id) laufen die Online-Endpoint-Tests gegen die DATEV-Sandbox statt gegen Mocks.

📖 Abhängigkeiten

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

🔧 Tools

Das SDK enthält ein OpenAPI Coverage Analyzer Tool zur Analyse der API-Abdeckung:

php tools/OpenApiCoverageAnalyzer.php

Dokumentation: docs/OpenApiCoverageAnalyzer.md

📄 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 / datev-php-sdk

Package info

Security

Statistics

README

🚀 Features

📋 Voraussetzungen

📦 Installation

⚙️ Konfiguration

Verbindung zur DATEV Desktop API

Authentifizierung

📚 Verwendung

Beispiel: Mandanten abrufen (Accounting)

Beispiel: Mitarbeiter abrufen (Payroll)

Beispiel: Echo-Test (Verbindung prüfen)

🏗️ Projektstruktur

🔌 API-Endpunkte

Accounting (`accounting/v1`)

Client Master Data (`master-data/v1`)

Payroll / HR (`hr/v3`)

Document Management (`dms/v2`)

Order Management

Law (`law/v1`)

Public Sector (`public-sector/v1`)

Identity & Access Management (SCIM)

Diagnostics

☁️ DATEV Online-APIs (Cloud)

Client und Authentifizierung

Beispiel: Mandanten und Belegtransfer

Beispiel: EXTF-Import mit Job-Polling

Online-Dienste im Überblick

🧪 Tests

Test-Konfiguration

Tests ausführen

📖 Abhängigkeiten

🔧 Tools

📄 Lizenz

💖 Unterstützung

👤 Autor

daniel-jorg-schuppelius / datev-php-sdk

Package info

Security

Statistics

README

🚀 Features

📋 Voraussetzungen

📦 Installation

⚙️ Konfiguration

Verbindung zur DATEV Desktop API

Authentifizierung

📚 Verwendung

Beispiel: Mandanten abrufen (Accounting)

Beispiel: Mitarbeiter abrufen (Payroll)

Beispiel: Echo-Test (Verbindung prüfen)

🏗️ Projektstruktur

🔌 API-Endpunkte

Accounting (accounting/v1)

Client Master Data (master-data/v1)

Payroll / HR (hr/v3)

Document Management (dms/v2)

Order Management

Law (law/v1)

Public Sector (public-sector/v1)

Identity & Access Management (SCIM)

Diagnostics

☁️ DATEV Online-APIs (Cloud)

Client und Authentifizierung

Beispiel: Mandanten und Belegtransfer

Beispiel: EXTF-Import mit Job-Polling

Online-Dienste im Überblick

🧪 Tests

Test-Konfiguration

Tests ausführen

📖 Abhängigkeiten

🔧 Tools

📄 Lizenz

💖 Unterstützung

👤 Autor

Accounting (`accounting/v1`)

Client Master Data (`master-data/v1`)

Payroll / HR (`hr/v3`)

Document Management (`dms/v2`)

Law (`law/v1`)

Public Sector (`public-sector/v1`)