inspirum / balikobot
PHP library for Balikobot API
Installs: 255 586
Dependents: 3
Suggesters: 0
Security: 0
Stars: 20
Watchers: 5
Forks: 12
Open Issues: 0
Requires
- php: ^8.1
- ext-curl: *
- ext-json: *
- guzzlehttp/psr7: ^1.5 || ^2.0
- inspirum/arrayable: ^1.3
- psr/http-message: ^1.1 || ^2.0
Requires (Dev)
- ext-zlib: *
- inspirum/coding-standard: ^1.6
- inspirum/phpunit-extension: ^1.1
- phpstan/phpstan: ^2.0
- phpunit/phpunit: ^10.5 || ^11.0
- shipmonk/composer-dependency-analyser: ^1.8
- squizlabs/php_codesniffer: ^3.11
- dev-master
- v7.12.0
- v7.11.0
- v7.10.0
- v7.9.0
- v7.8.0
- v7.7.0
- v7.6.1
- v7.6.0
- v7.5.1
- v7.5.0
- v7.4.0
- v7.3.0
- v7.2.0
- v7.1.0
- v7.0.0
- 6.x-dev
- v6.4.1
- v6.4.0
- v6.3.0
- v6.2.1
- v6.2.0
- v6.1.0
- v6.0.0
- 5.x-dev
- v5.7.2
- v5.7.1
- v5.7.0
- v5.6.0
- v5.5.0
- v5.4.1
- v5.4.0
- v5.3.0
- v5.2.0
- v5.1.0
- v5.0.0
- v4.5.0
- v4.4.0
- v4.3.0
- v4.2.0
- v4.1.0
- v4.0.0
- v3.3.0
- v3.2.2
- v3.2.1
- v3.2.0
- v3.1.0
- v3.0.0
- v2.0.1
- v2.0.0
- v1.4.0
- v1.3.2
- v1.3.1
- v1.3.0
- v1.2.0
- v1.1.2
- v1.1.1
- v1.1.0
- v1.0.4
- v1.0.3
- v1.0.2
- v1.0.1
- v1.0.0
This package is auto-updated.
Last update: 2024-11-20 14:59:57 UTC
README
Offers implementation of Balikobot API v2 described in the official documentation until v2.008 (2024-11-20).
More details are available in changelog.
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.
Create packages and order shipment
use Inspirum\Balikobot\Definitions\Carrier; use Inspirum\Balikobot\Definitions\Country; use Inspirum\Balikobot\Definitions\Currency; use Inspirum\Balikobot\Definitions\Service; use Inspirum\Balikobot\Model\PackageData\DefaultPackageData; use Inspirum\Balikobot\Model\PackageData\DefaultPackageDataCollection; use Inspirum\Balikobot\Service\PackageService; /** @var Inspirum\Balikobot\Service\PackageService $packageService */ // create new package collection for specific carrier $packagesData = new DefaultPackageDataCollection(Carrier::CP); // create new package $packageData = new DefaultPackageData(); $packageData->setServiceType(Service::CP_NP); $packageData->setRecName('Josef Novák'); $packageData->setRecZip('11000'); $packageData->setRecCountry(Country::CZECH_REPUBLIC); $packageData->setRecPhone('776555888'); $packageData->setCodPrice(1399.00); $packageData->setCodCurrency(Currency::CZK); // add package to collection $packagesData->add($packageData); // upload packages to balikobot $packages = $packageService->addPackages($packagesData); // save package IDs $data = []; $data['packages'] = $packages->getPackageIds(); // save track URL for each package foreach($packages as $package) { $data['trackUrl'][] = $package->getTrackUrl(); } // order shipment for packages $orderedShipment = $packageService->orderShipment($orderedPackages); // save order ID and labels URL $data['orderId'] = $orderedShipment->getOrderId(); $data['labelsUrl'] = $orderedShipment->getLabelsUrl(); $data['handoverUrl'] = $orderedShipment->getHandoverUrl(); /** var_dump($data); [ 'packages' => [ 0 => 42719 1 => 42720 ] 'trackUrl' => [ 0 => 'https://www.postaonline.cz/trackandtrace/-/zasilka/cislo?parcelNumbers=DR00112233M' 1 => 'https://www.postaonline.cz/trackandtrace/-/zasilka/cislo?parcelNumbers=DR00112234M' ] 'orderId' => 2757 'labelsUrl' => 'https://pdf.balikobot.cz/cp/eNorMTIwt9A1NbYwM76cMBAXAn4.' 'handoverUrl' => 'https://pdf.balikobot.cz/cp/eNorMTIwt9A1NbawtARcMBAhAoU.' ] */
Test packages data / delete packages
use Inspirum\Balikobot\Exception\Exception; /** @var Inspirum\Balikobot\Service\PackageService $packageService */ // check if packages data is valid try { $packageService->checkPackages($packagesData); } catch (Exception $exception) { return $exception->getErrors(); } // drop packages if shipment is not ordered yet $packageService->dropPackages($packages);
Track packages
use Inspirum\Balikobot\Definitions\Status; /** @var Inspirum\Balikobot\Service\TrackService $trackService */ // track last package status $status = $trackService->trackPackageLastStatus($packages[0]); /** var_dump($status); Inspirum\Balikobot\Model\Status\DefaultStatus { private $carrier => 'cp' private $carrierId => '1234' private $id => 2.2 private $name => 'Zásilka byla doručena příjemci.' private $description => 'Dodání zásilky. (77072 - Depo Olomouc 72)' private $type => 'event' private $date => DateTimeImmutable { '2018-07-02 09:15:01.000000' } } */ 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
use Inspirum\Balikobot\Definitions\Carrier; use Inspirum\Balikobot\Definitions\Country; /** @var Inspirum\Balikobot\Service\BranchService $branchService */ // get only branches for Zasilkovna in CZ/SK $branches = $branchService->getBranchesForCarrierAndCountries( Carrier::ZASILKOVNA, [Country::CZECH_REPUBLIC, Country::SLOVAKIA] ); foreach($branches as $branch) { /** var_dump($branch); Inspirum\Balikobot\Model\Branch\DefaultBranch { private $carrier => '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+).
Installation
Run composer require command:
composer require inspirum/balikobot
or add a requirement to your composer.json
:
"inspirum/balikobot": "^7.0"
Setup service
Available framework integrations:
But you can also use it without any framework implementation:
use Inspirum\Balikobot\Client\DefaultClient; use Inspirum\Balikobot\Client\DefaultCurlRequester; use Inspirum\Balikobot\Client\Response\Validator; use Inspirum\Balikobot\Model\Label\DefaultLabelFactory; use Inspirum\Balikobot\Model\OrderedShipment\DefaultOrderedShipmentFactory; use Inspirum\Balikobot\Model\Package\DefaultPackageFactory; use Inspirum\Balikobot\Model\PackageData\DefaultPackageDataFactory; use Inspirum\Balikobot\Model\ProofOfDelivery\DefaultProofOfDeliveryFactory; use Inspirum\Balikobot\Model\Status\DefaultStatusFactory; use Inspirum\Balikobot\Model\TransportCost\DefaultTransportCostFactory; use Inspirum\Balikobot\Service\DefaultPackageService; use Inspirum\Balikobot\Service\DefaultTrackService; $apiUser = getenv('BALIKOBOT_API_USER'); $apiKey = getenv('BALIKOBOT_API_KEY'); $requester = new DefaultCurlRequester($apiUser, $apiKey, sslVerify: true); $validator = new Validator(); $client = new DefaultClient($requester, $validator); $packageService = new DefaultPackageService( $client, new DefaultPackageDataFactory(), new DefaultPackageFactory($validator), new DefaultOrderedShipmentFactory(), new DefaultLabelFactory(), new DefaultProofOfDeliveryFactory($validator), new DefaultTransportCostFactory($validator), ); $trackService = new DefaultTrackService( $client, new DefaultStatusFactory($validator), ); // ...
Usage
The module contains several helper classes that contain most of the constants needed to work with the Balikobot API.
Testing
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
Contributing
Please see CONTRIBUTING and CODE_OF_CONDUCT for details.
Security
If you discover any security related issues, please email tomas.novotny@inspirum.cz instead of using the issue tracker.
Credits
License
The MIT License (MIT). Please see License File for more information.