daika7ana / innoship-php-sdk
Typed PHP SDK for the Innoship shipping API.
Requires
- php: >=8.3
- ext-json: *
- daika7ana/simple-collections: ^1.0
- guzzlehttp/guzzle: ^7.0 || ^8.0
- guzzlehttp/psr7: ^2.0 || ^3.0
- psr/http-client: ^1.0
- psr/http-factory: ^1.0
- psr/http-message: ^1.0 || ^2.0
Requires (Dev)
- laravel/pint: ^1.29
- phpstan/phpstan: ^2.1
- phpunit/phpunit: ^12.0 || ^13.0
Suggests
None
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-20 15:22:24 UTC
README
Innoship PHP SDK
A modern, type-safe PHP SDK for the Innoship shipping API
🚀 Framework-agnostic, API-key powered, fully typed with DTOs, production-ready, and built for multi-courier shipping.
Table of Contents
- Features
- Requirements
- Installation
- Quick Start
- Configuration
- Authentication
- Supported Resources
- Framework Support
- Testing
- Documentation
Features
Core Strengths
- ✅ API key authentication — send
X-Api-Keywith every request, no OAuth dance - ✅ Explicit API versioning —
api-versiontravels as both a header and a query parameter - ✅ PSR-18 HTTP client — pluggable; the bundled Guzzle adapter is used by default
- ✅ Fully typed DTOs — request payloads serialize from readonly objects; responses map back to typed objects
- ✅ Enums for every documented enum — couriers, parcel types, payment types, label formats, incoterms, and more
- ✅ Complete API coverage — orders, prices, labels, manifests, pickups, locations, notifications, offline orders, vouchers, repository
- ✅ Strict quality gates — PHPStan level 8, Laravel Pint, PHPUnit
- ✅ Framework-agnostic — works in Laravel, Symfony, or plain PHP
Perfect For
- 🎯 Laravel, Symfony, or plain PHP applications
- 🎯 Multi-courier shipping workflows — orders, carrier price rates, labels, and pickups through one client
- 🎯 Teams that prefer typed request and response DTOs over raw arrays
- 🎯 Projects that enforce strict static analysis and test gates
Requirements
- PHP 8.3+
ext-json- PSR-7 / PSR-17 / PSR-18 compatible environment
Installation
Via Composer
composer require daika7ana/innoship-php-sdk
Quick Start
Creating an order takes a single request DTO:
use Daika7ana\Innoship\Client; use Daika7ana\Innoship\Config\ClientConfig; use Daika7ana\Innoship\DTOs\Orders\OrderContent; use Daika7ana\Innoship\DTOs\Orders\OrderParcel; use Daika7ana\Innoship\DTOs\Orders\OrderParcelSize; use Daika7ana\Innoship\DTOs\Orders\OrderRequest; use Daika7ana\Innoship\DTOs\Orders\OrderRequestAddress; use Daika7ana\Innoship\Enums\ParcelType; use Daika7ana\Innoship\Enums\PaymentType; $client = Client::create(config: new ClientConfig(apiKey: 'your-api-key')); $today = (new DateTimeImmutable('today'))->format('Y-m-d'); $request = new OrderRequest( serviceId: 1, shipmentDate: $today, shipmentDateEnd: $today, externalClientLocation: 'RO', addressFrom: new OrderRequestAddress( name: 'Warehouse SRL', contactPerson: 'Warehouse SRL', country: 'RO', countyId: 10, localityId: 3502, addressText: 'Str. Depozitului 5', postalCode: '010864', phone: '+40734123456', email: 'warehouse@example.com', ), addressTo: new OrderRequestAddress( name: 'Jane Doe', contactPerson: 'Jane Doe', country: 'RO', countyId: 10, localityId: 3502, addressText: 'Str. Exemplu 10', postalCode: '010101', phone: '+40734123456', email: 'jane@example.com', ), payment: PaymentType::Sender, content: new OrderContent( parcelsCount: 1, totalWeight: 1.0, contents: 'Books', parcels: [ new OrderParcel( sequenceNo: 1, weight: 1.0, type: ParcelType::Parcel, size: new OrderParcelSize(width: 20.0, height: 10.0, length: 30.0), ), ], ), ); $order = $client->orders()->create($request); echo $order->courierShipmentId; echo $order->price?->totalAmount;
Get a price without creating an order:
$prices = $client->prices()->getPrices($request); foreach ($prices->rates as $rate) { echo $rate->carrier . ': ' . $rate->rateTotalAmount . ' ' . $rate->rateCurrency; }
Download a label as a PDF:
$label = $client->labels()->downloadLabel( courierId: $order->courier, awb: (string) $order->courierShipmentId, ); file_put_contents('label.pdf', $label->contents());
getLabel() returns the same label as base64 JSON ($label->contents) when you
need it inline rather than as a file.
That's it! You've created an order, priced a shipment, and downloaded a label.
Configuration
Base URL & API Version
The default base URL is https://api.innoship.com. Override it for a proxy or a
test gateway:
use Daika7ana\Innoship\Config\ClientConfig; $config = new ClientConfig( baseUrl: 'https://api.innoship.com', apiKey: 'your-api-key', apiVersion: '1.0', acceptLanguage: 'en', );
apiVersion is sent both as the api-version header and query parameter, as
required by the API.
Environment Variables
Pass the key explicitly or let the client read INNOSHIP_API_KEY:
$client = Client::create(); // reads INNOSHIP_API_KEY $client = Client::create(config: new ClientConfig(apiKey: 'your-api-key')); $client = Client::create()->setApiKey('rotated-key');
Requests throw AuthenticationException when the key is empty.
Request Timeouts
ClientConfig::timeout is null by default. Precedence: the per-call argument → ClientConfig::timeout → the transport's own default (GuzzleHttpClient uses 30 s to respond and 10 s to connect unless you pass timeout:/connectTimeout:; an injected GuzzleClient keeps its own configuration). A bare PSR-18 client keeps its own timeout and cannot receive the per-call argument — passing one throws InvalidArgumentException; combining a bare client with a non-null ClientConfig::timeout also throws.
Set a different SDK default with ClientConfig(timeout: ...) or override per call:
$client->request('GET', '/api/ClientLocation', null, [], 2.5);
Authentication
X-Api-Key
Innoship uses a single API key header:
X-Api-Key: your-api-key
The SDK adds it to every request. 401 responses and a missing key both raise
Daika7ana\Innoship\Exceptions\AuthenticationException.
apiVersion (default 1.0) is sent alongside it as both the api-version
header and a query parameter.
Supported Resources
| Resource | Methods |
|---|---|
orders() |
create, simulate, validate, simulateMultiple, importFile, delete, deleteParcel, updateStatus, updateParcels, updateCustomAttributes, getReturnAwbInfo, uploadDocuments, downloadDocument |
prices() |
getPrices |
labels() |
getLabel, downloadLabel, getVoucherLabel, getParcelLabel, createBulk, getBulk, getCustomLabel, getCustomParcelLabel |
manifests() |
create, get |
couriers() |
requestPickup, generateLocationId, listLocations, setLocationId |
locations() |
list, get, create, update, delete, summary, validate, addCourier, removeCourier, updateCourierServices, uploadLogo, deleteLogo |
notifications() |
sendSms, getByAwb, getByTemplate |
offlineOrders() |
add, edit, activate |
vouchers() |
create, activate |
repository() |
add |
See docs/RESOURCES.md for the endpoint map, parameters, and examples.
Scope Note
The SDK covers the endpoints published in the official Innoship Swagger
(https://api.innoship.com/swagger/v1/swagger.json). Innoship's support docs
also mention read-only endpoints on https://query.innoship.com (order
retrieval, tracking, location lookup); those are not part of that Swagger and
are therefore not wrapped.
Framework Support
Zero Framework Dependencies
The package carries no framework in require and works the same everywhere:
- 🌐 Laravel applications
- 🌐 Symfony projects
- 🌐 Plain PHP applications
- 🌐 Any PHP 8.3+ environment
Custom HTTP Client
The SDK uses its Guzzle adapter by default. To supply your own transport,
implement Daika7ana\Innoship\Http\HttpClientInterface:
use Daika7ana\Innoship\Client; use Daika7ana\Innoship\Http\HttpClientInterface; /** @var HttpClientInterface $customClient */ $client = Client::create(httpClient: $customClient);
A plain PSR-18 client is wrapped automatically, so
Client::create(httpClient: $psr18Client) works. Such a client keeps its own
timeout: leaving ClientConfig::timeout at null is required, otherwise the
constructor throws InvalidArgumentException. Passing it together with a
non-null ClientConfig::timeout throws as well. Implement HttpClientInterface
instead if you need the SDK's per-request timeout.
Both forms use the bundled PSR-17 factories by default; you may also pass
requestFactory: and streamFactory: explicitly to override them.
HttpClientInterface::sendRequest() accepts an optional timeout, so custom
clients can honour per-request timeouts.
Testing
The suite is offline: tests run against a fake PSR-18 client and the JSON
samples in tests/Fixtures/, and there is no live smoke suite.
Run Static Analysis
composer stan # PHPStan level 8 over src/
Run Full Test Suite
composer test # full PHPUnit suite # or composer test:unit # unit tests only
Run The Same Checks As CI
composer ci # validate -> pint -> stan -> test:unit
Test Environment Variables
None. The unit suite reads no environment variables, and no smoke suite needs credentials.
Documentation
| Guide | Purpose |
|---|---|
| 📖 Quickstart | First order, price, and label |
| 🔧 Installation | Setup details |
| ⚙️ Configuration | Base URL, API key, timeouts |
| 🔐 Authentication | API key handling |
| 🔗 Resources | Complete endpoint reference |
| 📦 DTOs | Request/response DTOs and enums |
| ✅ Testing | Running the suite |
| ❌ Errors | Exception handling |
| 📚 All Docs | Documentation index |
Made with ❤️
Questions? Check the docs or open an issue