PHP library for Balikobot API

v6.4.0 2022-03-26 14:44 UTC


Created as part of inspishop e-commerce platform by inspirum team.

Latest Stable Version Build Status Coverage Status Quality Score PHPStan Total Downloads Software License

Offers implementation of Balikobot API v2 described in the documentation

  • Support for all API requests
  • Simple add/track/drop package methods
  • All package options are accessible via setter and getter methods
  • The entire code is covered by unit and integration tests
  • Customizable Requester for easy functionality expandability (caching, etc.)

Usage example

See more available methods' documentation in Usage section.

All the code snippets shown here are modified for clarity, so they may not be executable.

Setup service

// get credentials
$apiUser = getenv('BALIKOBOT_API_USER');
$apiKey  = getenv('BALIKOBOT_API_KEY');

// init balikobot class
$requester = new Requester($apiUser, $apiKey, sslVerify: true);
$balikobot = new Balikobot($requester);

Create packages and order shipment

// create new package collection for specific shipper
$packages = new PackageCollection(Shipper::CP);

// create new package
$package = new Package();
$package->setRecName('Josef Novák');

// add package to collection

// upload packages to balikobot
$orderedPackages = $balikobot->addPackages($packages);

// save package IDs
$data             = [];
$data['packages'] = $orderedPackages->getPackageIds();

// save track URL for each package
foreach($orderedPackages as $orderedPackage) {
  $data['trackUrl'][] = $orderedPackage->getTrackUrl();

// order shipment for packages
$orderedShipment = $balikobot->orderShipment($orderedPackages);

// save order ID and labels URL
$data['orderId']     = $orderedShipment->getOrderId();
$data['labelsUrl']   = $orderedShipment->getLabelsUrl();
$data['handoverUrl'] = $orderedShipment->getHandoverUrl();

  'packages'    => [
    0 => 42719
    1 => 42720
  'trackUrl'    => [
    0 => ''
    1 => '' 
  'orderId'     => 2757
  'labelsUrl'   => ''
  'handoverUrl' => ''

Test packages data / delete packages

// check if packages data is valid
try {
} catch (ExceptionInterface $exception) {
    return $exception->getErrors();

// drop packages if shipment is not ordered yet

Track packages

// track last package status
$status = $balikobot->trackPackageLastStatus($orderedPackages[0]);
Inspirum\Balikobot\Model\Values\PackageStatus {
  'date'        => DateTime { '2018-07-02 09:15:01.000000' }
  'id'          => 2.2
  'name'        => 'Zásilka byla doručena příjemci.'
  'description' => 'Dodání zásilky. (77072 - Depo Olomouc 72)'
  'type'        => 'event'

if (Status::isError($status->getId())) {
  // handle package delivery error

if ($status->getId() === Status::COD_PAID) {
  // CoD has been credited to the sender's account

if (Status::isDelivered($status->getId())) {
  // handle delivered package 

Import branches

// get only branches for Zasilkovna in CZ/SK
$branches = $balikobot->getBranchesForShipperForCountries(
  [Country::CZECH_REPUBLIC, Country::SLOVAKIA]

foreach($branches as $branch) {
  Inspirum\Balikobot\Model\Values\Branch {
    private $shipper  => 'zasilkovna'
    private $service  => null
    private $branchId => '10000'
    private $uid      => 'VMCZ-zasilkovna-branch-10000'
    private $id       => '10000'
    private $type     => 'branch'
    private $name     => 'Hradec Králové, Dukelská tř. 1713/7 (OC Atrium - Traficon) Tabák Traficon'
    private $city     => 'Hradec Králové'
    private $street   => 'Dukelská tř. 1713/7'
    private $zip      => '50002'
    private $cityPart => null
    private $district => 'okres Hradec Králové'
    private $region   => 'Královéhradecký kraj'
    private $country  => 'CZ'

System requirements

If you are still using older PHP version, you can use this package in ^5.0 version (for PHP 7.1+).


Run composer require command:

composer require inspirum/balikobot

or add a requirement to your composer.json:

"inspirum/balikobot": "^6.0"


Support all options for Balikobot API v2 described in the official documentation until v1.955 (2022-03-24).

If you want to use older API v1, please use ^4.0 version.

More details are available in changelog.



The module contains several helper classes that contain most of the constants needed to work with the Balikobot API.


Support all options for Balikobot API described in given documentation.


Extension over Client that uses custom DTO classes as an input and output for its methods.


To run unit tests, run:

composer test:test

You can also run only Unit or Integration test suites, run:

composer test:unit
composer test:integration

To show coverage, run:

composer test:coverage

To run all test (phpcs, phpstan, phpunit, etc.), run:

composer test

For testing purposes, you can use these credentials:

  • API username: balikobot_test2cztest
  • API key: #lS1tBVo


Please see CONTRIBUTING and CODE_OF_CONDUCT for details.


If you discover any security related issues, please email instead of using the issue tracker.



The MIT License (MIT). Please see License File for more information.