Search by

kennzeichenservices / dropshipping-sdk

caspahouzer

Production-ready PHP SDK for the Dropshipping API

Package info

github.com/kennzeichenservices/dropshipping-sdk

pkg:composer/kennzeichenservices/dropshipping-sdk

Statistics

Installs: 1 337

Dependents: 0

Suggesters: 0

Stars: 1

Open Issues: 0

2.7.2 2026-11-17 15:03 UTC

README

A PHP SDK for the Kennzeichen Services Dropshipping API. It provides typed request/response objects, webhook processing with middleware pipeline support, and async queue integration.

Features

  • Typed endpoints for orders, shipments, products, registration offices, vehicle holder industries, webhooks, GKS configurations, vehicle deregistrations, and vehicle registrations
  • Immutable DTOs for all requests and responses
  • Webhook processing with configurable middleware pipeline (signature validation, payload validation, deserialization)
  • Async webhook processing via queue abstraction
  • HMAC-SHA256 webhook signature verification
  • Multipart file upload support for emission sticker orders
  • PSR-18 HTTP client / PSR-17 HTTP factory compatible (bring your own HTTP client)
  • Built-in request/response debug logging via KS_DROPSHIPPING_DEBUG constant

Requirements

  • PHP 8.2 or higher
  • A PSR-18 HTTP client implementation (e.g. guzzlehttp/guzzle, symfony/http-client)
  • A PSR-17 HTTP factory implementation (e.g. guzzlehttp/psr7, nyholm/psr7)

Installation

composer require kennzeichenservices/dropshipping-sdk

Configuration

use Dropshipping\Configuration\DropshippingConfig;

$config = new DropshippingConfig(
    host: 'api.example.com',
    dropshippingClientId: 123,
    username: 'your-username',
    password: 'your-password',
    webhookSignatureSecret: 'your-webhook-secret', // optional
);

Usage

Creating the Client

The client requires a PSR-18 HTTP client and PSR-17 request/stream factories. Example using Guzzle:

use Dropshipping\Client\ApiClient;
use GuzzleHttp\Client;
use GuzzleHttp\Psr7\HttpFactory;

$httpClient = new Client();
$factory = new HttpFactory();

$client = new ApiClient(
    config: $config,
    httpClient: $httpClient,
    psrRequestFactory: $factory,
    streamFactory: $factory,
);

Using DS

Instead of importing individual DTO classes, use Dropshipping\DS as a single entry point for all request objects:

use Dropshipping\DS;
use Dropshipping\Enums\Gender;

$address  = DS::address(firstName: 'Max', ..., gender: Gender::Male);
$response = $client->orders->create(
    DS::order(
        externalId: 'order-001',
        email: 'max@example.com',
        deliveryAddress: $address,
        invoiceAddress: $address,
        items: [DS::orderItem(42, 'Zulassung', 'ZL-001', 1, DS::plate('B', 'AB', '1234'))],
    )
);

The only imports you need are Dropshipping\DS and the enums you use (e.g. Gender, LicensePlateType). See the examples/ directory for complete runnable scripts.

The client exposes nine endpoint groups as public readonly properties:

  • $client->orders -- Order operations
  • $client->shipments -- Shipment operations (license plate reservations)
  • $client->products -- Product operations (availability checks, product catalog)
  • $client->registrationOffices -- Registration office listing (requires API 2.6.0)
  • $client->vehicleHolderIndustries -- Industry listing for legal person vehicle holders (requires API 2.7.0)
  • $client->webhooks -- Webhook operations
  • $client->gksConfigurations -- GKS configuration management (KBA interface)
  • $client->vehicleDeregistrations -- Vehicle deregistration operations
  • $client->vehicleRegistrations -- Vehicle registration operations (requires API 2.4.0 or later)

The SDK talks to dropshipping API 2.4.0 by default and supports 2.5.0, 2.6.0 and 2.7.0. The API version is part of the request URL, and an API version your client is not entitled to answers 403 Forbidden on every endpoint -- not just the new ones. api-version in composer.json therefore always names a version that is live for all clients, so an SDK update never moves you onto a version you cannot use. Opt into a newer version per integration, once your client is enabled for it:

DROPSHIPPING_API_VERSION=2.6.0

Or pass it directly, which takes precedence over the environment:

$config = new DropshippingConfig(
    host: 'api.example.com',
    dropshippingClientId: 12345,
    username: '...',
    password: '...',
    apiVersion: '2.6.0',
);

Vehicle registration works on the default, except for a Halteränderung (HA): it needs 2.5.0. 2.4.0 requires the ZB II security code for every service type code, while 2.5.0 forbids it for HA -- and the SDK follows 2.5.0.

2.6.0 adds three operations and one required field. The product catalog ($client->products->getCatalog()), the registration office listing ($client->registrationOffices->getAll()) and the document type change ($client->vehicleRegistrations->updateIdentityVerificationDocumentType()) exist only there and answer 403 Forbidden below it. On 2.6.0, a registration request must carry identityVerificationDocumentType, which 2.4.0 and 2.5.0 do not know: the SDK keeps it optional and omits it from the payload when null, so set it whenever you run on 2.6.0 or the API answers 400.

2.7.0 adds the legal person vehicle holder, one operation and a required discriminator. The industry listing ($client->vehicleHolderIndustries->getAll()) exists only there. A registration request must carry vehicleHolder.type, which no earlier version knows, so the holder you pass decides which payload goes out:

Holder type in the payload API versions
DS::vehicleRegistration(...), which wraps VehicleRegistrationVehicleHolder not sent 2.4.0 to 2.6.0
DS::registrationNaturalPersonVehicleHolder(...) NATURAL_PERSON 2.7.0
DS::registrationLegalPersonVehicleHolder(...) LEGAL_PERSON 2.7.0

Nothing about an existing integration changes on an SDK update: DS::vehicleRegistration(...) sends what it always sent. Switch to DS::vehicleRegistrationWithHolder(...) with one of the two new holders when you move to 2.7.0 -- see Submitting a Vehicle Registration.

Examples

Ready-to-run PHP scripts are available in the examples/ directory. Each example has an accompanying Markdown file that explains what it does.

Example Description
create-order.php · docs Create a standard order with a license plate item
create-emission-sticker-order.php · docs Create an emission sticker order with file upload
create-reshipped-order.php · docs Create a reshipped order for a returned delivery
check-license-plate-availability.php · docs Check available license plate numbers at a registration office
reserve-license-plate.php · docs Reserve a license plate
product-catalog.php · docs List every orderable product with its net costs (API 2.6.0)
registration-offices.php · docs List every registration office with its reservation fee (API 2.6.0)
vehicle-holder-industries.php · docs List the industries a legal person vehicle holder can be registered under (API 2.7.0)
gks-configurations.php · docs Create, update, list, and get GKS configurations
vehicle-deregistration.php · docs Submit a vehicle deregistration and handle the XKFZ webhook with file download
vehicle-registration.php · docs Submit a vehicle registration
durable-powers-of-attorney.php · docs Create, list and look up durable powers of attorney (API 2.7.0)
webhooks.php · docs Process incoming webhooks with the middleware pipeline
async-webhooks.php · docs Enqueue and process webhooks asynchronously via a queue

Creating an Order

use Dropshipping\DS;
use Dropshipping\Enums\Gender;

$address = DS::address(
    firstName: 'Max',
    lastName: 'Mustermann',
    gender: Gender::Male,
    streetName: 'Musterstraße',
    houseNumber: '1',
    zipCode: '12345',
    cityName: 'Berlin',
    countryCode: 'DE',
);

$response = $client->orders->create(
    DS::order(
        externalId: 'order-001',
        email: 'max@example.com',
        deliveryAddress: $address,
        invoiceAddress: $address,
        items: [DS::orderItem(42, 'Zulassung', 'ZL-001', 1, DS::plate('B', 'AB', '1234'))],
    )
);

echo $response->id; // Order ID

Creating an Emission Sticker Order

use Dropshipping\DS;

$response = $client->orders->createEmissionStickerOrder(
    DS::emissionStickerOrder(
        externalId: 'sticker-001',
        email: 'max@example.com',
        deliveryAddress: $address,
        invoiceAddress: $address,
        plate: DS::plate('B', 'AB', '1234'),
        electric: false,
        emissionKeyNumber: '0005',
        filePaths: ['/path/to/fahrzeugschein.pdf'],
    )
);

Creating a Reshipped Order

use Dropshipping\DS;

$response = $client->orders->createReshippedOrder(
    DS::reshippedOrder(
        externalId: 'reship-001',
        returnedDeliveryId: 456,
        deliveryAddress: $address,
        invoiceAddress: $address,
    )
);

Checking License Plate Availability

use Dropshipping\DS;
use Dropshipping\Enums\{LicensePlateType, VehicleType};

$response = $client->products->checkLicensePlateAvailability(
    DS::availabilityCheck(
        registrationOfficeServiceId: 1,
        city: 'B',
        middle: 'AB',
        end: '1234',
        licensePlateType: LicensePlateType::Regular,
        vehicleType: VehicleType::Car,
    )
);

foreach ($response->availableLicensePlateNumbers as $plate) {
    echo "{$plate->city} {$plate->middle} {$plate->end}\n";
}

Fetching the Product Catalog

Requires API 2.6.0. The catalog is the same content as the product catalog CSV export of the dropshipping self service, and it is where productVariantId for an order item comes from. Costs are decimal strings, not floats, because they are billed cent amounts.

$catalog = $client->products->getCatalog();

foreach ($catalog->ofType('LICENSE_PLATE') as $product) {
    echo "{$product->productVariantId}: {$product->productVariantName} from {$product->costItem1} EUR\n";
}

// Cost of the second plate of a pair, plus the supplier's shipping cost.
$plate = $catalog->findByVariantId(2);
echo $plate?->costForItem(2), ' ', $plate?->shippingCost;

The listing is not paginated and changes rarely, so cache it on your side rather than fetching it per order.

Fetching the Registration Offices

Requires API 2.6.0. The same content as the registration office CSV export of the dropshipping self service. reservationPrice is the fee the office charges in advance.

The spec does not say whether id is the same identifier as the registrationOfficeServiceId the availability check and the license plate reservation take. The names differ and so do the formats (int64 here against int32 there), so confirm with the API before passing one for the other.

$offices = $client->registrationOffices->getAll();

$office = $offices->findById(1);

if ($office?->chargesReservationFee()) {
    echo "{$office->name} charges {$office->reservationPrice} EUR up front\n";
}

// A region code is not unique, so this returns every office issuing it.
foreach ($offices->findByRegionCode('BO') as $match) {
    echo "{$match->id}: {$match->name} ({$match->stateName})\n";
}

Fetching the Vehicle Holder Industries

Requires API 2.7.0. The industries (Wirtschaftszweige) a legal person vehicle holder can be registered under, taken from the Berufsschlüssel of the ErfassRL Kfz, a KBA reference table. A code from here goes into industryCode of DS::registrationLegalPersonVehicleHolder(...).

A code is not unique: the same one can appear under several industry names, so the lookup returns a list. The listing is not paginated and changes rarely, so cache it on your side rather than fetching it per order.

$industries = $client->vehicleHolderIndustries->getAll();

if (!$industries->hasCode('G01')) {
    throw new RuntimeException('G01 is no longer an accepted industry code');
}

// A code can carry several names, so this returns every match.
foreach ($industries->findByCode('G01') as $industry) {
    echo "{$industry->sectionName}: {$industry->name}\n";
}

// For a two-level picker.
foreach ($industries->groupedBySection() as $sectionName => $entries) {
    echo $sectionName, "\n";

    foreach ($entries as $entry) {
        echo "  {$entry->code} {$entry->name}\n";
    }
}

Reserving a License Plate

use Dropshipping\DS;
use Dropshipping\Enums\{LicensePlateType, VehicleType};

$response = $client->shipments->createLicensePlateReservation(
    DS::licensePlateReservation(
        email: 'max@example.com',
        customization: DS::reservationCustomization(
            registrationOfficeServiceId: 1,
            licensePlateType: LicensePlateType::Regular,
            vehicleType: VehicleType::Car,
            plate: DS::plate('B', 'AB', '1234'),
        ),
        vehicleHolder: DS::reservationVehicleHolder(address: $address),
    )
);

Managing GKS Configurations

use Dropshipping\DS;

$request = DS::gksConfiguration(
    name: 'My KBA Config',
    kopaKey: 'kopa-key-value',
    username: 'kba-username',
    password: 'kba-password',
    publicKeyCertificate: file_get_contents('/path/to/cert.pem'),
    privateKey: file_get_contents('/path/to/private.key'),
    company: DS::gksCompany(
        name: 'Musterfirma GmbH',
        streetName: 'Musterstraße',
        houseNumber: '1',
        zipCode: '12345',
        cityName: 'Berlin',
        countryCode: 'DE',
    ),
);

// Create
$cfg = $client->gksConfigurations->create($request);
echo $cfg->id;   // UUID of the new configuration

// Update
$client->gksConfigurations->update($cfg->id, $request);

// List all
foreach ($client->gksConfigurations->getOverviews()->overviewGksConfigurations as $overview) {
    echo "{$overview->id}: {$overview->name}\n";
}

// Get single
$single = $client->gksConfigurations->getOverview($cfg->id);
echo $single->gksClientVersionNumber;   // "2.0"

// Which GKS client versions may a configuration reference?
$versions = $client->gksConfigurations->getEnabledClientVersions();
print_r($versions->versionNumbers());   // ["2.0", "3.0"]

gksClientVersionNumber is required by dropshipping API 2.4.0 and defaults to 2.0, the version the API assumed before the field existed. Pass another one to move a configuration:

$request = DS::gksConfiguration(
    // ... same fields as above ...
    company: $company,
    gksClientVersionNumber: '3.0',
);

Submitting a Vehicle Deregistration

use Dropshipping\DS;
use Dropshipping\Enums\{VehicleDeregistrationLicensePlateType, VehicleDeregistrationVehicleType};

$response = $client->vehicleDeregistrations->createDeregistration(
    DS::vehicleDeregistration(
        email: 'max@example.com',
        customization: DS::deregistrationCustomization(
            vehicleType: VehicleDeregistrationVehicleType::Car,
            plate: DS::plate('B', 'AB', '1234'),
            licensePlateReservationIncluded: false,
            vehicleIdentificationNumber: 'WBA12345678901234',
            vehicleRegistrationCertificateSecurityCode: 'ABC123',
            rearLicensePlateSecurityCode: 'XY9876',
        ),
        vehicleHolderAddress: $address,
        externalOrderId: 'deregistration-001',  // optional
        gksConfigurationId: 'your-gks-uuid',    // optional
        contractPartnerKopaKey: 'K123X',        // optional
    )
);

echo $response->orderId; // Created order ID

Downloading a Deregistration File

Files attached to a VEHICLE_DEREGISTRATION_XKFZ_EVENT webhook can be downloaded using the fileAccessKey from the event:

use Dropshipping\Client\ApiClient;
use Dropshipping\Contracts\WebhookHandlerInterface;
use Dropshipping\DTO\Webhooks\{VehicleDeregistrationXkfzEvent, WebhookEventInterface};
use Dropshipping\Enums\WebhookEventType;

class DeregistrationXkfzHandler implements WebhookHandlerInterface
{
    public function __construct(private readonly ApiClient $client) {}

    public function supports(WebhookEventInterface $event): bool
    {
        return $event->getEventType() === WebhookEventType::VehicleDeregistrationXkfzEvent;
    }

    public function handle(WebhookEventInterface $event): void
    {
        /** @var VehicleDeregistrationXkfzEvent $event */
        echo "Order {$event->order->id} status: {$event->status->value} ({$event->derivedStatus})\n";

        foreach ($event->messages ?? [] as $message) {
            echo "[{$message->type}] {$message->text}\n";
        }

        foreach ($event->files ?? [] as $file) {
            $content = $this->client->vehicleDeregistrations->downloadFileContent($file->fileAccessKey);
            file_put_contents("{$file->purposeType->value}.pdf", $content);
        }
    }
}

Submitting a Vehicle Registration

Works on the default API version 2.4.0, except for a Halteränderung, which needs 2.5.0, and a legal person as the vehicle holder, which needs 2.7.0 -- see below and the version notice above.

use Dropshipping\DS;
use Dropshipping\Enums\{
    IdentityVerificationDocumentType,
    VehicleRegistrationLicensePlateType,
    VehicleRegistrationServiceTypeCode,
    VehicleRegistrationVehicleType,
};

$response = $client->vehicleRegistrations->createRegistration(
    DS::vehicleRegistration(
        email: 'max@example.com',
        customization: DS::registrationCustomization(
            licensePlateNumberAssignmentStrategy: DS::randomLicensePlateNumber(
                licensePlateType: VehicleRegistrationLicensePlateType::Regular,
            ),
            vehicleRegistrationServiceTypeCode: VehicleRegistrationServiceTypeCode::NZ,
            deregistered: true,                                 // must be true for NZ, WZ and WG
            vehicleType: VehicleRegistrationVehicleType::Car,
            electronicInsuranceConfirmationNumber: 'ABC1234',   // eVB-Nummer, exactly 7 chars
            vehicleIdentificationNumber: 'WBA12345678901234',
            vehicleTitleSecurityCode: 'B12345678900',           // ZB II code, exactly 12 chars
            iban: 'DE89370400440532013000',
            bic: 'COBADEFFXXX',                                 // only required for an MC, SM or CH iban
        ),
        vehicleHolderAddress: $address,
        vehicleHolderPlaceOfBirth: 'Berlin',   // required
        vehicleHolderBirthDate: '1990-01-31',  // required, ISO 8601
        vehicleHolderBirthName: 'Musterfrau',  // optional
        externalOrderId: 'registration-001',   // optional
        gksConfigurationId: 'your-gks-uuid',   // optional
        identityVerificationDocumentType:      // required on API 2.6.0, unknown to 2.4.0 and 2.5.0
            IdentityVerificationDocumentType::GermanId,
    )
);

echo $response->orderId;

The response carries nothing but the order ID. The customer still must identify themselves and sign the documents before anything is processed -- but both URLs arrive as webhooks, not in this response: identityVerificationUrl on VEHICLE_REGISTRATION_IDENTITY_VERIFICATION_INITIALIZED and documentSignatureUrl on VEHICLE_REGISTRATION_DOCUMENT_SIGNATURE_INITIALIZED. Send the customer to each as it comes in.

The assignment strategy is an object, not a plain enum value -- it serializes with a strategyType discriminator and carries the plate data belonging to that strategy. Build it with DS::randomLicensePlateNumber(...), DS::reservedLicensePlateNumber(...) or DS::retainedLicensePlateNumber():

licensePlateNumberAssignmentStrategy: DS::reservedLicensePlateNumber(
    plate: DS::plate('B', 'AB', '1234'),
    licensePlateType: VehicleRegistrationLicensePlateType::ElectricSeason,
    reservationPin: '1234',
    seasonStartMonth: 4,  // optional, for *_SEASON plate types
    seasonEndMonth: 10,   // optional
),

RANDOM leaves only the number to the registration office -- the plate type is still yours to choose, so it takes a licensePlateType too. RETAINMENT carries nothing; it takes the number from the DS::previousLicensePlate(...) on the customization, which it therefore requires -- and it requires that plate to come without its two security codes, since the plates are never handed in.

The service type code decides what a previous registration contributes. A Neuzulassung has none, every other code continues one, and the customization throws either way round:

Field NZ every other code
vehicleRegistrationCertificateSecurityCode (ZB I) must be null required
previousLicensePlate must be null required
deregistered must be true true for WZ and WG, free otherwise

RETAINMENT is out for NZ as a consequence -- it has no previous plate to keep the number of. The API reports the ZB I violation as verificationCode must be null, its internal name for that field. The spec's field descriptions only name the NZ side; that the other codes require both fields, and that WZ and WG need a deregistered vehicle, is known from API rejections alone. The API only rejects the request after the customer has identified themselves and signed, which is why the SDK catches all of it up front.

A Halteränderung (HA) only changes the holder. The vehicle stays registered and keeps its plate, and the Fahrzeugbrief is not involved. Spec 2.5.0 publishes what follows from that, and the customization enforces it:

Field HA every other code
deregistered must be false see above
licensePlateNumberAssignmentStrategy must be RETAINMENT free (but not RETAINMENT for NZ)
vehicleTitleSecurityCode, vehicleTitleNumber (ZB II) must be null security code required
electronicInsuranceConfirmationNumber optional required
iban optional required, unless the holder pays the tax through customs (see below)
customization: DS::registrationCustomization(
    licensePlateNumberAssignmentStrategy: DS::retainedLicensePlateNumber(),
    vehicleRegistrationServiceTypeCode: VehicleRegistrationServiceTypeCode::HA,
    deregistered: false,
    vehicleType: VehicleRegistrationVehicleType::Car,
    electronicInsuranceConfirmationNumber: null,
    vehicleIdentificationNumber: 'WBA12345678901234',
    vehicleTitleSecurityCode: null,
    iban: null,
    bic: null,
    vehicleRegistrationCertificateSecurityCode: 'SEC1234',  // ZB I code, required
    previousLicensePlate: DS::previousLicensePlate(        // the plate the vehicle keeps
        plate: DS::plate('B', 'AB', '1234'),
        licensePlateType: VehicleRegistrationLicensePlateType::Regular,
    ),
),

The BIC is only required for three countries. Spec 2.7.0 narrows it down: an iban from Monaco (MC), San Marino (SM) or Switzerland (CH) needs a bic alongside it, every other country does not. Up to 2.6.0 the spec called it required for every code but HA, and the SDK enforced that; it no longer does, so a German IBAN without a BIC now goes out rather than being rejected locally.

A legal person (juristische Person) as the vehicle holder. Requires API 2.7.0 and is not accepted for HA. Build the holder separately and pass it to DS::vehicleRegistrationWithHolder(...):

$response = $client->vehicleRegistrations->createRegistration(
    DS::vehicleRegistrationWithHolder(
        email: 'einkauf@autohaus-muster.de',
        customization: $customization,
        vehicleHolder: DS::registrationLegalPersonVehicleHolder(
            address: $address,                      // the address of the company
            name: 'Autohaus Muster GmbH',           // the name of the holder
            industryCode: 'G01',                    // from $client->vehicleHolderIndustries->getAll()
            companyNumber: 'HRB 123456',            // company register number, for the verification
            customsMajorCustomerId: null,           // optional Zoll-GK-Nr., see below
        ),
        identityVerificationDocumentType: IdentityVerificationDocumentType::GermanId,
    )
);

The address is the address of the company. Its firstName, lastName and gender name a contact person, and its companyName is not read as the holder's name -- that is what name is for, so a company with a companyName on its address still has to repeat it there. The two may differ.

industryCode has to be a code the API knows; fetch it from the industry listing. The SDK checks the shape (three characters of A-Z and 0-9), the API checks existence.

Paying the motor vehicle tax through customs. A company holding a major customer ID of the customs administration (Großkunden-ID der Zollverwaltung, Zoll-GK-Nr.) settles the tax that way instead of by SEPA direct debit mandate. Pass it as customsMajorCustomerId and leave iban and bic empty on the customization -- the request throws if both are given, since the API rejects that combination:

vehicleHolder: DS::registrationLegalPersonVehicleHolder(
    address: $address,
    name: 'Autohaus Muster GmbH',
    industryCode: 'G01',
    companyNumber: 'HRB 123456',
    customsMajorCustomerId: '123A4567',  // three digits, a letter, four digits
),

A natural person on 2.7.0. DS::vehicleRegistration(...) keeps sending the payload without vehicleHolder.type, which is what 2.4.0 to 2.6.0 expect and 2.7.0 rejects with 400. On 2.7.0 use the explicit holder instead:

DS::vehicleRegistrationWithHolder(
    email: 'max@example.com',
    customization: $customization,
    vehicleHolder: DS::registrationNaturalPersonVehicleHolder(
        address: $address,
        placeOfBirth: 'Berlin',
        birthDate: '1990-01-31',
        birthName: 'Musterfrau',  // optional
    ),
    identityVerificationDocumentType: IdentityVerificationDocumentType::GermanId,
);

Reusing an earlier identification. recycledVehicleRegistrationOrderId points at an earlier registration order whose identity verification and signed files this one takes over, so the customer identifies themselves and signs only once. Requires API 2.6.0; the field has been in the spec since then, but 2.7.0 is the first version to describe it.

DS::vehicleRegistrationWithHolder(
    email: 'max@example.com',
    customization: $customization,
    vehicleHolder: $holder,
    recycledVehicleRegistrationOrderId: 12345,  // serialized as recycledVehicleRegistration.orderId
);

The referenced order has to match this one: the same vehicleHolder.type, and for a legal person the same vehicleHolder.name (compared case insensitively, ignoring surrounding whitespace). It also has to carry the files this registration needs, which are the power of attorney, the SEPA direct debit mandate (except for HA and for a holder with a customsMajorCustomerId) and, for a natural person, the GDPR consent declaration (except for HA).

None of that is checkable in the SDK, since it is all about the other order, so the API is what rejects a mismatch. The SDK only rejects an order ID of zero or less, which cannot name an order.

A deviating delivery address for the registration documents. By default the registration office posts both the Zulassungsbescheinigung Teil I (Fahrzeugschein) and Teil II (Fahrzeugbrief) to the vehicle holder. Pass deliveryConfigurations to send either of them somewhere else -- to a dealership taking the Teil II, say:

$dealer = DS::registrationDocumentCompany(
    address: DS::registrationDeliveryAddress(
        streetName: 'Autohausstraße',
        houseNumber: '7a',
        zipCode: '80331',
        cityName: 'München',
    ),
    name: 'Autohaus Muster GmbH',
);

customization: DS::registrationCustomization(
    // ...
    deliveryConfigurations: DS::registrationDeliveryConfigurations(
        vehicleRegistrationCertificate: DS::deliverToVehicleHolder(),
        vehicleTitle: DS::deliverToThirdParty($dealer),
    ),
),

Both documents have to be configured together -- there is no way to redirect one and leave the other unmentioned, so the one that stays with the holder gets DS::deliverToVehicleHolder(). Omitting deliveryConfigurations altogether keeps the default for both.

Each document takes one of three options:

Factory What happens
DS::deliverToVehicleHolder() Posted to the vehicle holder. Carries no recipient.
DS::deliverToThirdParty($recipient) Posted to the third party at its own address.
DS::pickupByThirdParty($recipient) Left at the registration office for the third party to collect.

A recipient is either a company (DS::registrationDocumentCompany(...), taking a name) or a private individual (DS::registrationDocumentPerson(...), taking first and last name, gender and birth date). Both carry the address, built with DS::registrationDeliveryAddress(...) -- street, house number, postal code and city only. It is deliberately not DS::address(...): the office gets the name from the recipient and delivers within Germany, so there is no country code.

PICKUP_BY_THIRD_PARTY posts nothing, but still wants the address -- the office records who is entitled to collect the document and identifies them by it.

Everything after the order creation arrives as VEHICLE_REGISTRATION_* webhooks: the identity check and signing steps report their start and outcome, and VEHICLE_REGISTRATION_XKFZ_EVENT carries the registration office's verdict along with the assigned plate. See Webhook Event Types.

Changing the Identity Verification Document Type

Requires API 2.6.0. The customer picks the document they identify themselves with when the order is created. This corrects that choice afterwards, for instance when they turn out not to hold a German ID card.

use Dropshipping\Enums\IdentityVerificationDocumentType;

$client->vehicleRegistrations->updateIdentityVerificationDocumentType(
    orderId: 12345,
    documentType: IdentityVerificationDocumentType::GermanPassportWithProofOfAddress,
);

The API answers 202 and does the work asynchronously, so a successful call means the change was accepted, not that a new link exists yet. Depending on the change, a fresh verification URL arrives as another VEHICLE_REGISTRATION_IDENTITY_VERIFICATION_INITIALIZED webhook. An ApiException with status 409 means document signing has already started or the order is not eligible for a change, and 404 means the order ID is unknown.

Managing Durable Powers of Attorney

Requires API 2.7.0. A durable power of attorney (Dauervollmacht) lets a company authorise vehicle registrations once instead of signing a power of attorney per order. Creating one mails the signer and starts the signing; the outcome arrives as a webhook.

use Dropshipping\DS;

$created = $client->vehicleRegistrations->createDurablePowerOfAttorney(DS::durablePowerOfAttorney(
    company: DS::durablePowerOfAttorneyCompany(
        name: 'Muster Autohaus GmbH',
        streetName: 'Hauptstraße',
        houseNumber: '12A',
        zipCode: '10115',
        cityName: 'Berlin',
        taxData: DS::durablePowerOfAttorneySepaTaxData(iban: 'DE89370400440532013000'),
        // or: DS::durablePowerOfAttorneyCustomsTaxData('123A4567')
        number: 'HRB 123456',
    ),
    signerFirstName: 'Erika',
    signerLastName: 'Musterfrau',
    signerEmail: 'erika.musterfrau@example.com',
    expirationDate: null, // the API sets the maximum, one year from today
));

$created->status;   // INCOMPLETE until VEHICLE_REGISTRATION_DURABLE_POWER_OF_ATTORNEY_COMPLETION arrives

$all = $client->vehicleRegistrations->getDurablePowersOfAttorney();
$usable = $all->usable(); // COMPLETE, not revoked, not expired

$one = $client->vehicleRegistrations->getDurablePowerOfAttorney($created->id);

The create call is not idempotent, so check the listing before retrying after a timeout. getDurablePowerOfAttorney() only accepts a UUID and throws a DropshippingException before any request for anything else.

Responses are read leniently: a status or tax data type this SDK does not know comes back as UNKNOWN instead of failing the whole listing. The request DTOs, on the other hand, check every length, the IBAN/BIC rule and the date format before anything is sent.

API 2.7.0 does not yet take a durable power of attorney as a reference when ordering a registration; that part is announced but not live.

Handling Webhooks

Set up a webhook receiver with the built-in middleware pipeline:

use Dropshipping\Contracts\WebhookHandlerInterface;
use Dropshipping\DS;
use Dropshipping\DTO\Webhooks\WebhookEventInterface;
use Dropshipping\Enums\WebhookEventType;

// Implement a handler
class ShipmentHandler implements WebhookHandlerInterface
{
    public function supports(WebhookEventInterface $event): bool
    {
        return $event->getEventType() === WebhookEventType::DeliveryShipment;
    }

    public function handle(WebhookEventInterface $event): void
    {
        echo "Order {$event->order->id} shipped, tracking: {$event->delivery->trackingCode}\n";
    }
}

// Wire up pipeline and dispatcher
$dispatcher = DS::webhookDispatcher(DS::webhookPipeline($config->getWebhookSignatureSecret()));
$dispatcher->registerHandler(new ShipmentHandler());

// Receive a webhook (e.g. in a controller)
$dispatcher->dispatch(DS::incomingWebhook());

Async Webhook Processing

For high-throughput scenarios, queue webhooks for background processing:

use Dropshipping\Contracts\WebhookQueueInterface;
use Dropshipping\DS;

// Implement WebhookQueueInterface with your queue backend (Redis, RabbitMQ, database, etc.)
$queue = new YourQueueImplementation();

// In your HTTP controller: enqueue instead of processing inline
DS::queueWebhookDispatcher($queue, $config->getWebhookSignatureSecret())
    ->dispatch(DS::incomingWebhook());

// In a background worker process
$processed = DS::webhookWorker($queue, $dispatcher)->run(maxMessages: 100);

The signature is verified before the message is enqueued, so a forged payload never reaches your queue. Catch WebhookException in the controller and answer 401:

use Dropshipping\Exceptions\WebhookException;

try {
    DS::queueWebhookDispatcher($queue, $config->getWebhookSignatureSecret())
        ->dispatch(DS::incomingWebhook());
} catch (WebhookException) {
    http_response_code(401);

    return;
}

http_response_code(202);

The worker-side pipeline verifies the signature a second time, which is intentional — messages may sit in the queue across a secret rotation, and the worker is the last point where a bad message can be rejected before a handler runs.

Architecture Overview

src/
├── Async/              Queue-based webhook processing
├── Client/             API client and HTTP authentication
├── Configuration/      SDK configuration
├── Contracts/          Interfaces for serialization, webhooks, and queues
├── DS.php              Static facade — single import for all request DTOs
├── DTO/
│   ├── Requests/       Request objects with toArray() serialization
│   ├── Responses/      Response objects with fromArray() factories
│   └── Webhooks/       Webhook event types and factories
├── Endpoints/          API endpoint classes (Orders, Shipments, Products, Webhooks, GksConfigurations, VehicleDeregistrations, VehicleRegistrations)
├── Enums/              Backed string enums for type safety
├── Exceptions/         Exception hierarchy
├── Http/               PSR-7 request building and response mapping
├── Security/           HMAC-SHA256 signature verification
├── Serialization/      JSON encode/decode
├── Support/            Input validation utilities
└── Webhook/            Middleware pipeline and dispatcher

The SDK follows these patterns:

  • Immutable DTOs -- All request and response objects are final readonly classes.
  • Static factories -- Response DTOs provide fromArray() constructors; request DTOs provide toArray() for serialization.
  • Middleware pipeline -- Webhook processing uses composable middleware (signature validation, payload validation, deserialization).
  • PSR compliance -- No HTTP client is bundled. The SDK depends on PSR-18 (HTTP Client), PSR-17 (HTTP Factories), and PSR-7 (HTTP Messages).

Key Components

Endpoints

Endpoint Method Description
$client->orders->create() POST /orders Create a standard order
$client->orders->createEmissionStickerOrder() POST /orders/emissionStickerOrders Create emission sticker order (multipart)
$client->orders->createReshippedOrder() POST /orders/reshippedOrders Create reshipped order
$client->shipments->createLicensePlateReservation() POST /licensePlateReservations/reservations Reserve a license plate
$client->products->checkLicensePlateAvailability() POST /licensePlateReservations/availabilityChecks Check license plate availability
$client->products->getCatalog() GET /products List every orderable product with its net costs (API 2.6.0)
$client->registrationOffices->getAll() GET /registrationOffices List every registration office with its reservation fee (API 2.6.0)
$client->vehicleHolderIndustries->getAll() GET /vehicleHolderIndustries List the industries a legal person vehicle holder can be registered under (API 2.7.0)
$client->gksConfigurations->create() POST /gksConfigurations Create a GKS configuration
$client->gksConfigurations->update() PUT /gksConfigurations/{id} Update a GKS configuration
$client->gksConfigurations->getOverviews() GET /gksConfigurations/overviews List all GKS configurations
$client->gksConfigurations->getOverview() GET /gksConfigurations/overviews/{id} Get a single GKS configuration
$client->gksConfigurations->getEnabledClientVersions() GET /gksClientVersions/enabled List the GKS client versions a configuration may reference
$client->vehicleDeregistrations->createDeregistration() POST /vehicleDeregistrations/deregistrations Submit a vehicle deregistration
$client->vehicleDeregistrations->downloadFileContent() GET /vehicleDeregistrations/files/content/{fileAccessKey} Download a file from a VEHICLE_DEREGISTRATION_XKFZ_EVENT webhook
$client->vehicleRegistrations->createRegistration() POST /vehicleRegistrations/registrations Submit a vehicle registration
$client->vehicleRegistrations->updateIdentityVerificationDocumentType() PUT /vehicleRegistrations/{orderId}/identityVerifications Change the identity document of an existing order (API 2.6.0)
$client->vehicleRegistrations->downloadFileContent() GET /vehicleRegistrations/files/content/{fileAccessKey} Download a file from a VEHICLE_REGISTRATION_XKFZ_EVENT webhook
$client->vehicleRegistrations->downloadApplicationFileContent() GET /vehicleRegistrations/applicationFiles/content/{fileAccessKey} Download a signed document from a VEHICLE_REGISTRATION_DOCUMENT_SIGNATURE_SUCCEEDED webhook
$client->vehicleRegistrations->createDurablePowerOfAttorney() POST /vehicleRegistrations/durablePowersOfAttorney Create a durable power of attorney (API 2.7.0)
$client->vehicleRegistrations->getDurablePowersOfAttorney() GET /vehicleRegistrations/durablePowersOfAttorney List every durable power of attorney (API 2.7.0)
$client->vehicleRegistrations->getDurablePowerOfAttorney() GET /vehicleRegistrations/durablePowersOfAttorney/{id} Get one durable power of attorney by UUID (API 2.7.0)

Webhook Event Types

Event Class Description
PING PingEvent Connection test
DELIVERY_SHIPMENT DeliveryShipmentEvent Delivery shipped with tracking code
DELIVERY_RETURN DeliveryReturnEvent Delivery returned with reason and reshipping offer
DELIVERY_CANCELLATION DeliveryCancellationEvent Delivery cancelled
LICENSE_PLATE_RESERVATION_APPROVAL LicensePlateReservationApprovalEvent Reservation approved with PIN, price and, if sent, reservationDurationDays
LICENSE_PLATE_RESERVATION_REJECTION LicensePlateReservationRejectionEvent Reservation rejected with alternatives
LICENSE_PLATE_RESERVATION_TIMEOUT LicensePlateReservationTimeoutEvent Reservation timed out
VEHICLE_DEREGISTRATION_XKFZ_EVENT VehicleDeregistrationXkfzEvent Vehicle deregistration XKFZ status update — includes status, derivedStatus, optional files (with fileAccessKey for download), optional costBreakdown, and optional messages
VEHICLE_REGISTRATION_XKFZ_EVENT VehicleRegistrationXkfzEvent Vehicle registration XKFZ status update — same shape as the deregistration event, plus the assigned licensePlate. Files carry a fileAccessKey for downloadFileContent()
VEHICLE_REGISTRATION_IDENTITY_VERIFICATION_INITIALIZED VehicleRegistrationIdentityVerificationInitializedEvent Identity check started — send the customer to identityVerificationUrl
VEHICLE_REGISTRATION_IDENTITY_VERIFICATION_SUCCEEDED VehicleRegistrationIdentityVerificationSucceededEvent Customer identified successfully
VEHICLE_REGISTRATION_IDENTITY_VERIFICATION_FAILED VehicleRegistrationIdentityVerificationFailedEvent Identity check failed, with an optional message. For a legal person the company and representative check can refuse the order here, before any link exists; failureReason() maps its keys (company_not_found, no_matching_representative, …) to VehicleRegistrationIdentityVerificationFailureReason and returns null for any other text
VEHICLE_REGISTRATION_DOCUMENT_SIGNATURE_INITIALIZED VehicleRegistrationDocumentSignatureInitializedEvent Signing started — send the customer to documentSignatureUrl
VEHICLE_REGISTRATION_DOCUMENT_SIGNATURE_SUCCEEDED VehicleRegistrationDocumentSignatureSucceededEvent Documents signed — applicationFiles carries them, each with a fileAccessKey for downloadApplicationFileContent()
VEHICLE_REGISTRATION_DOCUMENT_SIGNATURE_FAILED VehicleRegistrationDocumentSignatureFailedEvent Signing failed, with an optional message
VEHICLE_REGISTRATION_DURABLE_POWER_OF_ATTORNEY_COMPLETION VehicleRegistrationDurablePowerOfAttorneyCompletionEvent A durable power of attorney is signed. Carries durablePowerOfAttorney->id, no order
VEHICLE_REGISTRATION_DURABLE_POWER_OF_ATTORNEY_ERROR VehicleRegistrationDurablePowerOfAttorneyErrorEvent A durable power of attorney failed. Carries durablePowerOfAttorney->id and a free-text message, no order
(any unrecognised type) UnknownWebhookEvent Only produced when the pipeline is built with tolerateUnknownEvents: true. Carries rawEventType and the full payload — see below

Unknown event types

The table above covers webhooks spec 3.3.0. The API can start sending a new event type before a matching SDK release exists — by default such an eventType throws a WebhookException. Opt into tolerance to receive them instead:

$pipeline = DS::webhookPipeline($secret, tolerateUnknownEvents: true);

Unrecognised payloads then arrive as UnknownWebhookEvent with getEventType() === WebhookEventType::Unknown, the original type string in rawEventType, and the complete decoded payload in payload.

Note this only covers an unknown eventType. An unmodelled value inside a known event still throws, except where the SDK defines a fallback — status on both XKFZ events degrades to UNKNOWN rather than failing the delivery.

Enums

Enum Values
Gender FEMALE, MALE, UNSPECIFIED
VehicleType CAR, MOTORCYCLE
LicensePlateType REGULAR, REGULAR_SEASON, ELECTRIC, ELECTRIC_SEASON, HISTORICAL, HISTORICAL_SEASON
LicensePlateUsageType EURO, PARKING
ProductType LICENSE_PLATE, VEHICLE_DEREGISTRATION, VEHICLE_REGISTRATION, OTHER
VehicleDeregistrationVehicleType CAR, LIGHT_MOTORCYCLE, MOTORCYCLE, OTHER, TRACTOR, TRAILER, TRUCK
VehicleDeregistrationLicensePlateType REGULAR, REGULAR_SEASON, ELECTRIC, ELECTRIC_SEASON, HISTORICAL, HISTORICAL_SEASON
VehicleDeregistrationXkfzEventStatus ACCEPTED, APPROVED, APPROVED_WITH_DOCUMENTS, FAILED, FORWARDED, PROCESSED, REJECTED, REJECTED_WITH_DOCUMENTS, UNKNOWN
VehicleDeregistrationXkfzEventFilePurposeType CERTIFICATE, RECEIPT, APPLICATION, UNSPECIFIED
VehicleRegistrationVehicleType CAR, MOTORCYCLE, TRAILER
VehicleRegistrationLicensePlateType REGULAR, REGULAR_SEASON, ELECTRIC, ELECTRIC_SEASON, HISTORICAL, HISTORICAL_SEASON
VehicleRegistrationLicensePlateNumberAssignmentStrategyType RANDOM, RESERVATION, RETAINMENT
VehicleRegistrationDeliveryConfigurationDeliveryOption DELIVERY_TO_OWNER, DELIVERY_TO_THIRD_PARTY, PICKUP_BY_THIRD_PARTY
VehicleRegistrationDeliveryConfigurationRecipientType NATURAL_PERSON, LEGAL_PERSON
VehicleRegistrationServiceTypeCode NZ, WZ, UO, UI, UM, WG, UG, HA
VehicleRegistrationVehicleHolderType NATURAL_PERSON, LEGAL_PERSON
IdentityVerificationDocumentType GERMAN_ID, RESIDENCE_PERMIT, GERMAN_PASSPORT_WITH_PROOF_OF_ADDRESS, FOREIGN_PAPERS_WITH_PROOF_OF_ADDRESS
VehicleRegistrationIdentityVerificationFailureReason company_not_found, company_not_verified, company_not_active, company_name_mismatch, company_number_mismatch, missing_holder_name, no_matching_representative, ambiguous_representative, missing_sole_signing_authority, company_representative_verification_failed. Not hydrated: failureReason() on VehicleRegistrationIdentityVerificationFailedEvent resolves it from the free-text message and returns null for anything else
VehicleRegistrationDurablePowerOfAttorneyStatus INCOMPLETE, COMPLETE, ERROR, UNKNOWN (local fallback for unmodelled values)
VehicleRegistrationDurablePowerOfAttorneyCompanyTaxDataType CUSTOMS_MAJOR_CUSTOMER, SEPA_DIRECT_DEBIT_MANDATE, UNKNOWN (local fallback for unmodelled values)
VehicleRegistrationXkfzEventStatus ACCEPTED, APPROVED, APPROVED_WITH_DOCUMENTS, FAILED, FORWARDED, PROCESSED, REJECTED, REJECTED_WITH_DOCUMENTS, UNKNOWN
VehicleRegistrationXkfzEventFilePurposeType OTHER, PROVISIONAL_VEHICLE_REGISTRATION_CERTIFICATE, VEHICLE_REGISTRATION_APPLICATION_POWER_OF_ATTORNEY, VEHICLE_REGISTRATION_APPROVAL_NOTICE, VEHICLE_REGISTRATION_CERTIFICATE_TOKEN, VEHICLE_REGISTRATION_CHARGES_NOTICE, VEHICLE_REGISTRATION_ELECTRONIC_INSURANCE_CONFIRMATION, VEHICLE_REGISTRATION_GDPR_CONSENT_DECLARATION, VEHICLE_REGISTRATION_MOTOR_VEHICLE_TAX_SEPA_DIRECT_DEBIT_MANDATE, VEHICLE_REGISTRATION_REJECTION_NOTICE
WebhookEventType see Webhook Event Types, plus UNKNOWN for unrecognised types

Extensibility

  • Custom HTTP client -- Pass any PSR-18 compliant HTTP client to ApiClient.
  • Custom serializer -- Implement SerializerInterface and pass it to ApiClient to replace the default ArrayMapper.
  • Custom webhook handlers -- Implement WebhookHandlerInterface and register with WebhookDispatcher.
  • Custom queue backend -- Implement WebhookQueueInterface for async webhook processing with any queue system.
  • Custom middleware -- Implement WebhookMiddlewareInterface to add processing steps to the webhook pipeline.

Security Considerations

  • API authentication uses HTTP Basic Auth. Credentials are added to every request by ApiKeyAuthenticator.
  • Webhook payloads are verified using HMAC-SHA256 signatures via the X-Signature header. The SignatureValidationMiddleware rejects requests with invalid signatures.
  • Store API credentials and webhook secrets outside of version control.

Debugging

The SDK supports request/response logging via PHP constants. Define KS_DROPSHIPPING_DEBUG before making API calls to write detailed logs:

define('KS_DROPSHIPPING_DEBUG', true);

By default, logs are written to dropshipping-debug.log in the current working directory. To use a custom log file path:

define('KS_DROPSHIPPING_DEBUG', true);
define('KS_DROPSHIPPING_DEBUG_FILE', '/var/log/dropshipping.log');

The debug log includes:

  • Timestamp, HTTP method and URL
  • Request headers (Authorization is masked)
  • Request body
  • Response status code and headers
  • Response body
  • Exception details on transport failures

Example log output:

--------------------------------------------------------------------------------
[2026-02-03 14:30:00] POST https://api.example.com/dropshipping-api/123/2.1.0/orders

>>> REQUEST HEADERS
  Authorization: ***
  Content-Type: application/json
  Accept: application/json

>>> REQUEST BODY
{"externalId":"order-001","email":"max@example.com",...}

<<< RESPONSE 201 Created
  Content-Type: application/json
  X-Trace-Id: abc-123

<<< RESPONSE BODY
{"id":42,"status":"created"}
--------------------------------------------------------------------------------

Error Handling

All exceptions extend DropshippingException:

Exception When
DropshippingException Request DTO field validation failure (e.g. string too long, invalid email, empty required field). Thrown before any HTTP request is made.
ApiException Non-expected HTTP status code from the API. Provides getStatusCode() and getTraceId() for debugging.
HttpClientException PSR-18 client-level transport failure. Wraps the original ClientExceptionInterface.
WebhookException Webhook signature verification or payload validation failure.

All request DTOs validate their fields against the API spec constraints when constructed. Invalid values throw a DropshippingException with a descriptive message including the field name and the provided value:

// Throws: Field "firstName" must be between 1 and 100 characters, got 110
new Address(firstName: str_repeat('x', 110), ...);

// Throws: Field "email" must be a valid email address
new OrderCreationRequest(email: 'not-an-email', ...);

// Throws: Field "seasonStartMonth" must be between 1 and 12, got 0
new LicensePlateReservationCustomization(seasonStartMonth: 0, ...);

Development

composer check            # lint + static analysis + unit tests — run before committing
composer test:unit        # unit tests only
composer test:integration # hits the live API, needs credentials in .env
composer lint:fix         # apply code style
composer analyse          # PHPStan: src at level 8, tests at level 6
composer audit:security   # known CVEs in dependencies

PHP is formatted with Laravel Pint, not with your editor's built-in formatter — the two disagree and will overwrite each other. The bundled .vscode/settings.json disables format-on-save for PHP in this project for that reason.

Backward-compatibility check

Run before every release. It answers "if a customer upgrades, does the SDK still behave the same?" by comparing the working tree against a released tag:

composer bc-check              # against the latest tag
composer bc-check -- v2.3.20   # against a specific ref

It reports two things:

  1. Public API surface — every public class, property, method signature and enum case, diffed. A removed parameter or a newly required argument shows up here; that is what breaks a consumer's code at call time.
  2. Hydration behaviour — a corpus of realistic payloads (scripts/bc-check/corpus.php) is run through both versions' DTOs and the resulting objects are compared field by field. This catches silent behaviour changes that no unit test happens to cover.

The command exits non-zero on an unexplained behaviour difference, so it can gate a release. Deliberate changes are recorded in scripts/bc-check/accepted.php with a reason and the release they shipped in — without that, the check would stay red after the first intentional change and everyone would learn to ignore it.

When you add a DTO or a field, add a corpus entry for it. The check can only compare what the corpus exercises.

License

Proprietary