daika7ana / bookurier-php-sdk
Typed PHP SDK for the Bookurier courier services API.
Requires
- php: >=8.3
- ext-dom: *
- 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:48:27 UTC
README
Bookurier PHP SDK
A modern, type-safe PHP SDK for the Bookurier courier services API
π Framework-agnostic, XML-native, fully typed with DTOs, and built for Romanian courier shipments.
The SDK wraps Bookurier's form-POST endpoints behind a PSR-18 client, builds and
parses the XML payloads internally, and returns AWB labels, daily bordero
documents and pickup borderos as the documents Bookurier sent. Authentication is
the Bookurier account username and password sent as userid and pwd on every
API request β there is no API key, OAuth exchange or token refresh.
Table of Contents
- Features
- Requirements
- Installation
- Quick Start
- Configuration
- Authentication
- Supported Resources
- Framework Support
- Testing
- Documentation
Features
Core Strengths
- β PSR-18 HTTP Client β Bundled Guzzle transport by default; any PSR-18 client can be supplied instead
- β
Typed DTOs β Build a shipment with
Order; read status, history and batch results from readonly response objects - β
XML Built and Parsed Internally β Order payloads are escaped and wrapped for you; the API's
<cmd>envelopes are mapped to DTOs - β All 15 Vendor Endpoints β Create, batch create, delete, status, history, labels, daily bordero and pickup
- β Byte-Exact Documents β HTML and PDF labels, daily bordero documents and pickup borderos are returned as the raw response body, not re-encoded
- β
In-Band Error Mapping β HTTP 200 error bodies (
-1,-2,-3) becomeApiException; authentication, transport and unexpected bodies have their own exception types - β
Opaque AWB Formats β
BOKplus seven digits, twelve digits on partner routes, orCKCplus six digits for Bucharest Today; all are treated as opaque strings and validated leniently - β
Document Guards β PDF labels must start with
%PDF; the host's HTML challenge page and empty bodies are rejected - β
Static Analysis with PHPStan β Level 8 over the
src/codebase - β
Zero Framework Coupling β No Laravel, Symfony or other framework in
require; no service provider required - β Comprehensive Tests β Unit suite with a fake transport, plus a live smoke suite
Perfect For
- π― Romanian courier shipments β AWB labels, daily borderos and pickup requests
- π― PHP frameworks and standalone applications alike
- π― Type-safe order creation, status and history workflows
- π― Production integrations validated against the live service with a smoke suite
Requirements
- PHP 8.3+
ext-domfor XML parsing- Composer 2
- A PSR-7/17/18 compatible environment
Installation
Via Composer
composer require daika7ana/bookurier-php-sdk
Quick Start
Pass the Bookurier account credentials explicitly, or let the client read
BOOKURIER_USERNAME and BOOKURIER_PASSWORD:
use Daika7ana\Bookurier\Client; use Daika7ana\Bookurier\Config\ClientConfig; use Daika7ana\Bookurier\DTOs\Order\Order; use Daika7ana\Bookurier\Enums\ServiceType; $client = Client::create(config: new ClientConfig( userId: 'your-bookurier-user', password: 'your-bookurier-password', clientId: 1234, // your Bookurier client code )); $awb = $client->orders()->create(new Order( uniqueId: 'A1', // your own order id recipientName: 'Ionescu Vasile', phone: '0744-666847', city: 'Bucuresti', street: 'Nicolae Oncescu nr. 6', service: ServiceType::Bucharest24h, weight: 0.5, district: 'Sect 1', cashOnDelivery: 100.65, notes: 'De sunat cu 1/2 inainte', )); echo $awb; // e.g. BOK3925457 $label = $client->labels()->pdf($awb); file_put_contents("awb-{$awb}.pdf", $label->contents);
For the full flow β order, label, status, delete and error handling β see docs/QUICKSTART.md.
Resource methods do not accept a timeout; configure one on ClientConfig or use
the low-level Client::post() / Client::send() methods. See
docs/CONFIGURATION.md.
That's it! You've created an AWB and written its PDF label to disk.
Configuration
Base URL
The default base URL is https://www.bookurier.ro/colete/serv. The vendor
documentation lists http:// URLs, but the SDK uses the same host over HTTPS.
Environment Variables
Client::create() with no config calls ClientConfig::fromEnvironment(), which
reads BOOKURIER_USERNAME (falling back to BOOKURIER_USERID),
BOOKURIER_PASSWORD, BOOKURIER_CLIENT_ID, BOOKURIER_BASE_URL and
BOOKURIER_TIMEOUT. A ClientConfig you construct yourself does not read the
environment.
For every variable and its default, see docs/CONFIGURATION.md.
Request Timeouts
Set a default on ClientConfig::timeout; per-call overrides exist on the
low-level Client::post() / Client::send() methods. Precedence: per-call
Client::post(..., timeout:) / Client::send($request, $t) β
ClientConfig::timeout β transport constructor arguments β 30.0/10.0.
Authentication
Bookurier authenticates with a Bookurier account username and password, sent as
userid and pwd on every form POST. There is no API key, no OAuth exchange and
no token refresh. Client::post() throws AuthenticationException before
sending when either value is empty; Client::send() adds no credentials.
use Daika7ana\Bookurier\Client; use Daika7ana\Bookurier\Config\ClientConfig; $client = Client::create(config: new ClientConfig( userId: 'your-bookurier-user', password: 'your-bookurier-password', ));
Order XML requires <client> (your Bookurier client code). It comes from
Order::$clientCode, or from ClientConfig::clientId when that is null. With
neither set, create() and createBatch() throw InvalidArgumentException
before sending. The password is protected only by HTTPS, so redact userid,
pwd and request bodies from logs.
See docs/AUTHENTICATION.md for environment variables, credential handling and redaction guidance, and docs/ERRORS.md for rejected-request codes.
Supported Resources
All endpoints are POST requests relative to
https://www.bookurier.ro/colete/serv. The SDK adds userid and pwd to every
form body. Order-creating calls also send your client code as <client> inside
the XML, taken from Order::$clientCode or, when that is null, from
ClientConfig::clientId.
| Resource | Methods |
|---|---|
orders() |
create, createBatch, delete, deleteByUniqueId, status, statusByUniqueId, history, historyByUniqueId |
labels() |
html, pdf, htmlByUniqueId, pdfByUniqueId, daily |
reports() |
dailyBordero |
pickup() |
request (@experimental) |
history($awb) is not usable on the live service: it answers -2 even for a
valid AWB. Use historyByUniqueId(). pickup()->request() dispatches a physical
courier and has never been exercised live.
See docs/RESOURCES.md for the endpoint and return type of each method, and docs/DTOS.md for the request and response objects.
Error Handling
use Daika7ana\Bookurier\Exceptions\ApiException; use Daika7ana\Bookurier\Exceptions\AuthenticationException; use Daika7ana\Bookurier\Exceptions\BookurierException; use Daika7ana\Bookurier\Exceptions\TransportException; use Daika7ana\Bookurier\Exceptions\UnexpectedResponseException; try { $awb = $client->orders()->create($order); } catch (AuthenticationException $e) { // userId or password is empty; no request was sent } catch (ApiException $e) { // Bookurier answered a negative code or a non-empty <err> } catch (TransportException $e) { // DNS, TLS, timeout or connection failure; original is getPrevious() } catch (UnexpectedResponseException $e) { // body was empty, not XML where XML was expected, not the success value, // or the host's HTML challenge page } catch (BookurierException $e) { // any other SDK failure }
Bookurier returns HTTP 200 even for errors, so the SDK classifies responses by body rather than status code. See docs/ERRORS.md.
Documentation Limits
Bookurier publishes no OpenAPI schema and provides no sandbox. This SDK was built from the documentation, then checked against the live service with Bookurier's test account, which established these points and corrected several in the documentation:
- AWBs vary server-side by destination county and service:
BOKplus seven digits on the own network (BOK3925457), twelve digits on partner routes (062568455929), orCKCplus six digits for Bucharest Today (CKC122336). The SDK treats the AWB as an opaque string and validates with the lenient/^[A-Za-z]{0,4}\d{3,}$/. - Failures are negative codes in a HTTP 200 body:
-1rejected request,-2record not found / invalid data,-3incomplete request. add_cmd.phprequires<client>(your client code).- Every
msgmust be wrapped in<msg>β¦</msg>; the SDK always sends that envelope, and a bare<cmd>without the wrapper is rejected with-1. get_history.php(history by AWB) answers-2even for an existing AWB. UsehistoryByUniqueId().unqis not enforced unique: two orders with the sameunqboth get an AWB.add_cmds.phpanswers with a comma separated AWB list and nounq, so batch results are paired positionally with the orders you sent.- The host sits behind a bot filter: a burst of requests eventually gets an HTML
"One moment, pleaseβ¦" challenge page with HTTP 200 instead of the API answer.
Every endpoint, including the document endpoints, surfaces that as
UnexpectedResponseException; wait a few minutes before retrying reads, and reconcilecreate()/createBatch()before retrying them.
pickup()->request() (@experimental) dispatches a physical courier and was
never exercised against the live service; it is covered by unit tests only.
Validate your own integration against your account before production rollout.
Framework Support
Zero Framework Dependencies
This package works equally well everywhere, with no Laravel, Symfony or other
framework in require and no service provider required:
- π Laravel applications
- π Symfony projects
- π Standalone PHP applications
- π Microservices
- π Any PHP 8.3+ environment
Custom HTTP Client
A bare PSR-18 client is wrapped automatically:
use Daika7ana\Bookurier\Client; use GuzzleHttp\Client as GuzzleClient; $client = Client::create( httpClient: new GuzzleClient(['timeout' => 10.0]), );
A wrapped client keeps its own timeout, so ClientConfig::timeout must stay
null; passing both throws InvalidArgumentException. Implement
Daika7ana\Bookurier\Http\HttpClientInterface instead if you need the SDK's
per-call timeout:
use Daika7ana\Bookurier\Client; use Daika7ana\Bookurier\Http\HttpClientInterface; /** @var HttpClientInterface $transport */ $client = Client::create(httpClient: $transport);
Testing
Run Static Analysis
composer stan # PHPStan level 8 over src/ # or vendor/bin/phpstan --no-progress
Run Full Test Suite
composer test # full PHPUnit suite # or vendor/bin/phpunit
The unit suite never touches the network and needs no Bookurier credentials: a fake transport records the request and returns canned bodies. Every endpoint has a test covering both the outgoing request and the response mapping. See docs/TESTING.md for the helpers and an example test.
Run Live Smoke Tests
composer test:smoke # tests/Smoke only, needs BOOKURIER_TEST_* env vars
The smoke tests hit the live API. They skip themselves unless
BOOKURIER_TEST_USERNAME, BOOKURIER_TEST_PASSWORD and
BOOKURIER_TEST_CLIENT_ID are set; creating an AWB also needs
BOOKURIER_TEST_ALLOW_WRITES=1.
Run The Same Checks As CI
composer ci # validate --strict -> pint --test -> phpstan -> phpunit tests/Unit composer pint # style check only, never fixes composer test:unit # tests/Unit only
Test Environment Variables
Configure these in the environment to enable smoke tests:
| Variable | Purpose |
|---|---|
BOOKURIER_TEST_USERNAME |
Test account username |
BOOKURIER_TEST_PASSWORD |
Test account password |
BOOKURIER_TEST_CLIENT_ID |
Bookurier client code |
BOOKURIER_TEST_ALLOW_WRITES |
Set to 1 to create (and delete) a live AWB |
Documentation
Complete guides and references:
| Guide | Purpose |
|---|---|
| π Quickstart | First AWB, PDF label, status and delete |
| π§ Installation | Requirements and setup |
| βοΈ Configuration | Credentials, base URL, environment, timeouts, custom clients |
| π Authentication | Account credentials, client code, rejected requests |
| π Usage | Orders, batches, status, history, labels, bordero documents, pickup |
| π Resources | Method-level endpoint reference |
| π¦ DTOs | Order field mapping, enums and response objects |
| β Errors | Exception hierarchy and failure modes |
| β Testing | Test commands and helpers |
GPL-3.0-or-later. See LICENSE.
Made with β€οΈ
Questions? Check the docs or open an issue