Download the PHP package kennzeichenservices/dropshipping-sdk without Composer

Dropshipping SDK

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, webhooks, GKS configurations, and vehicle deregistrations
• 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

Configuration

Usage

Creating the Client

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

Using DS

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

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 six endpoint groups as public readonly properties:

• $client->orders -- Order operations
• $client->shipments -- Shipment operations (license plate reservations)
• $client->products -- Product operations (availability checks)
• $client->webhooks -- Webhook operations
• $client->gksConfigurations -- GKS configuration management (KBA interface)
• $client->vehicleDeregistrations -- Vehicle deregistration operations

Examples

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

Creating an Order

Creating an Emission Sticker Order

Creating a Reshipped Order

Checking License Plate Availability

Reserving a License Plate

Managing GKS Configurations

Submitting a Vehicle Deregistration

Downloading a Deregistration File

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

Handling Webhooks

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

Async Webhook Processing

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

Architecture Overview

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

Webhook Event Types

Enums

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:

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

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:

Error Handling

All exceptions extend DropshippingException:

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:

License

Proprietary