{"id":20016911,"url":"https://github.com/inspirum/balikobot-php","last_synced_at":"2025-04-06T08:15:48.663Z","repository":{"id":46308888,"uuid":"163284572","full_name":"inspirum/balikobot-php","owner":"inspirum","description":"PHP library for Balikobot API.","archived":false,"fork":false,"pushed_at":"2024-12-12T13:54:41.000Z","size":1096,"stargazers_count":19,"open_issues_count":0,"forks_count":12,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-30T07:11:18.389Z","etag":null,"topics":["api-client","api-wrapper","balikobot","carriers","delivery-api","php"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/inspirum.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"docs/CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":"docs/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-12-27T11:06:16.000Z","updated_at":"2025-03-17T10:40:35.000Z","dependencies_parsed_at":"2023-02-10T17:15:42.849Z","dependency_job_id":"dba7a17e-6202-4677-b5c7-3c15eefcdcf3","html_url":"https://github.com/inspirum/balikobot-php","commit_stats":{"total_commits":332,"total_committers":3,"mean_commits":"110.66666666666667","dds":"0.012048192771084376","last_synced_commit":"2580ba712315df4e21845f3b310984292999ad5f"},"previous_names":[],"tags_count":60,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inspirum%2Fbalikobot-php","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inspirum%2Fbalikobot-php/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inspirum%2Fbalikobot-php/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inspirum%2Fbalikobot-php/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/inspirum","download_url":"https://codeload.github.com/inspirum/balikobot-php/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247451666,"owners_count":20940944,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-client","api-wrapper","balikobot","carriers","delivery-api","php"],"created_at":"2024-11-13T08:13:41.024Z","updated_at":"2025-04-06T08:15:48.643Z","avatar_url":"https://github.com/inspirum.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Balikobot API\n\n[![Latest Stable Version][ico-packagist-stable]][link-packagist-stable]\n[![Build Status][ico-workflow]][link-workflow]\n[![Coverage Status][ico-scrutinizer]][link-scrutinizer]\n[![Quality Score][ico-code-quality]][link-code-quality]\n[![PHPStan][ico-phpstan]][link-phpstan]\n[![Total Downloads][ico-packagist-download]][link-packagist-download]\n[![Software License][ico-license]][link-licence]\n\nOffers implementation of Balikobot API [v2][link-api-v2-upgrade] described in the official [documentation][link-api-v2] until **v2.008** *(2024-11-20)*.\n\n\u003e If you want to use older API [v1][link-api], please use [`^4.0`](https://github.com/inspirum/balikobot-php/tree/v4.5.0) version.\n\nMore details are available in [changelog][link-changelog].\n\n\n## Usage example\n\nSee more available methods' documentation in [Usage](#usage) section.\n\n\u003e *All the code snippets shown here are modified for clarity, so they may not be executable.*\n\n#### Create packages and order shipment\n\n```php\nuse Inspirum\\Balikobot\\Definitions\\Carrier;\nuse Inspirum\\Balikobot\\Definitions\\Country;\nuse Inspirum\\Balikobot\\Definitions\\Currency;\nuse Inspirum\\Balikobot\\Definitions\\Service;\nuse Inspirum\\Balikobot\\Model\\PackageData\\DefaultPackageData;\nuse Inspirum\\Balikobot\\Model\\PackageData\\DefaultPackageDataCollection;\nuse Inspirum\\Balikobot\\Service\\PackageService;\n\n/** @var Inspirum\\Balikobot\\Service\\PackageService $packageService */\n\n// create new package collection for specific carrier\n$packagesData = new DefaultPackageDataCollection(Carrier::CP);\n\n// create new package\n$packageData = new DefaultPackageData();\n$packageData-\u003esetServiceType(Service::CP_NP);\n$packageData-\u003esetRecName('Josef Novák');\n$packageData-\u003esetRecZip('11000');\n$packageData-\u003esetRecCountry(Country::CZECH_REPUBLIC);\n$packageData-\u003esetRecPhone('776555888');\n$packageData-\u003esetCodPrice(1399.00);\n$packageData-\u003esetCodCurrency(Currency::CZK);\n\n// add package to collection\n$packagesData-\u003eadd($packageData);\n\n// upload packages to balikobot\n$packages = $packageService-\u003eaddPackages($packagesData);\n\n// save package IDs\n$data = [];\n$data['packages'] = $packages-\u003egetPackageIds();\n\n// save track URL for each package\nforeach($packages as $package) {\n  $data['trackUrl'][] = $package-\u003egetTrackUrl();\n}\n\n// order shipment for packages\n$orderedShipment = $packageService-\u003eorderShipment($orderedPackages);\n\n// save order ID and labels URL\n$data['orderId'] = $orderedShipment-\u003egetOrderId();\n$data['labelsUrl'] = $orderedShipment-\u003egetLabelsUrl();\n$data['handoverUrl'] = $orderedShipment-\u003egetHandoverUrl();\n\n/**\nvar_dump($data);\n[\n  'packages' =\u003e [\n    0 =\u003e 42719\n    1 =\u003e 42720\n  ]\n  'trackUrl' =\u003e [\n    0 =\u003e 'https://www.postaonline.cz/trackandtrace/-/zasilka/cislo?parcelNumbers=DR00112233M'\n    1 =\u003e 'https://www.postaonline.cz/trackandtrace/-/zasilka/cislo?parcelNumbers=DR00112234M' \n  ]\n  'orderId' =\u003e 2757\n  'labelsUrl' =\u003e 'https://pdf.balikobot.cz/cp/eNorMTIwt9A1NbYwM76cMBAXAn4.'\n  'handoverUrl' =\u003e 'https://pdf.balikobot.cz/cp/eNorMTIwt9A1NbawtARcMBAhAoU.'\n]\n*/\n```\n\n\n#### Test packages data / delete packages\n\n```php\nuse Inspirum\\Balikobot\\Exception\\Exception;\n\n/** @var Inspirum\\Balikobot\\Service\\PackageService $packageService */\n\n// check if packages data is valid\ntry {\n    $packageService-\u003echeckPackages($packagesData);\n} catch (Exception $exception) {\n    return $exception-\u003egetErrors();\n}\n\n// drop packages if shipment is not ordered yet\n$packageService-\u003edropPackages($packages);\n````\n\n\n#### Track packages\n\n```php\nuse Inspirum\\Balikobot\\Definitions\\Status;\n\n/** @var Inspirum\\Balikobot\\Service\\TrackService $trackService */\n\n// track last package status\n$status = $trackService-\u003etrackPackageLastStatus($packages[0]);\n/**\nvar_dump($status);\nInspirum\\Balikobot\\Model\\Status\\DefaultStatus {\n  private $carrier =\u003e 'cp'\n  private $carrierId =\u003e '1234'\n  private $id =\u003e 2.2\n  private $name =\u003e 'Zásilka byla doručena příjemci.'\n  private $description =\u003e 'Dodání zásilky. (77072 - Depo Olomouc 72)'\n  private $type =\u003e 'event'\n  private $date =\u003e DateTimeImmutable { '2018-07-02 09:15:01.000000' }\n}\n*/\n        \nif (Status::isError($status-\u003egetId())) {\n  // handle package delivery error\n}\n\nif ($status-\u003egetId() === Status::COD_PAID) {\n  // CoD has been credited to the sender's account\n}\n\nif (Status::isDelivered($status-\u003egetId())) {\n  // handle delivered package \n}\n```\n\n#### Import branches\n\n```php\nuse Inspirum\\Balikobot\\Definitions\\Carrier;\nuse Inspirum\\Balikobot\\Definitions\\Country;\n\n/** @var Inspirum\\Balikobot\\Service\\BranchService $branchService */\n\n// get only branches for Zasilkovna in CZ/SK\n$branches = $branchService-\u003egetBranchesForCarrierAndCountries(\n  Carrier::ZASILKOVNA, \n  [Country::CZECH_REPUBLIC, Country::SLOVAKIA]\n); \n\nforeach($branches as $branch) {\n  /**\n  var_dump($branch);\n  Inspirum\\Balikobot\\Model\\Branch\\DefaultBranch {\n    private $carrier =\u003e 'zasilkovna'\n    private $service =\u003e null\n    private $branchId =\u003e '10000'\n    private $uid =\u003e 'VMCZ-zasilkovna-branch-10000'\n    private $id =\u003e '10000'\n    private $type =\u003e 'branch'\n    private $name =\u003e 'Hradec Králové, Dukelská tř. 1713/7 (OC Atrium - Traficon) Tabák Traficon'\n    private $city =\u003e 'Hradec Králové'\n    private $street =\u003e 'Dukelská tř. 1713/7'\n    private $zip =\u003e '50002'\n    private $cityPart =\u003e null\n    private $district =\u003e 'okres Hradec Králové'\n    private $region =\u003e 'Královéhradecký kraj'\n    private $country =\u003e 'CZ'\n    ...\n  }\n  */\n}\n```\n\n\n## System requirements\n\n* [PHP 8.1+](http://php.net/releases/8_1_0.php)\n* [ext-curl](http://php.net/curl)\n* [ext-json](http://php.net/json)\n\nIf you are still using older PHP version, you can use this package in [`^5.0`](https://github.com/inspirum/balikobot-php/tree/5.x) version (for PHP 7.1+).\n\n## Installation\n\nRun composer require command:\n```\ncomposer require inspirum/balikobot\n```\nor add a requirement to your `composer.json`:\n```json\n\"inspirum/balikobot\": \"^7.0\"\n```\n\n### Setup service\n\nAvailable framework integrations:\n\n- [Symfony](https://github.com/inspirum/balikobot-php-symfony)\n- [Laravel](https://github.com/inspirum/balikobot-php-laravel)\n- [Nette](https://github.com/TomasHalasz/balikobot-nette)\n\nBut you can also use it without any framework implementation:\n\n```php\nuse Inspirum\\Balikobot\\Client\\DefaultClient;\nuse Inspirum\\Balikobot\\Client\\DefaultCurlRequester;\nuse Inspirum\\Balikobot\\Client\\Response\\Validator;\nuse Inspirum\\Balikobot\\Model\\Label\\DefaultLabelFactory;\nuse Inspirum\\Balikobot\\Model\\OrderedShipment\\DefaultOrderedShipmentFactory;\nuse Inspirum\\Balikobot\\Model\\Package\\DefaultPackageFactory;\nuse Inspirum\\Balikobot\\Model\\PackageData\\DefaultPackageDataFactory;\nuse Inspirum\\Balikobot\\Model\\ProofOfDelivery\\DefaultProofOfDeliveryFactory;\nuse Inspirum\\Balikobot\\Model\\Status\\DefaultStatusFactory;\nuse Inspirum\\Balikobot\\Model\\TransportCost\\DefaultTransportCostFactory;\nuse Inspirum\\Balikobot\\Service\\DefaultPackageService;\nuse Inspirum\\Balikobot\\Service\\DefaultTrackService;\n\n$apiUser = getenv('BALIKOBOT_API_USER');\n$apiKey = getenv('BALIKOBOT_API_KEY');\n\n$requester = new DefaultCurlRequester($apiUser, $apiKey, sslVerify: true);\n$validator = new Validator();\n$client = new DefaultClient($requester, $validator);\n\n$packageService = new DefaultPackageService(\n    $client,\n    new DefaultPackageDataFactory(),\n    new DefaultPackageFactory($validator),\n    new DefaultOrderedShipmentFactory(),\n    new DefaultLabelFactory(),\n    new DefaultProofOfDeliveryFactory($validator),\n    new DefaultTransportCostFactory($validator),\n);\n\n$trackService = new DefaultTrackService(\n    $client,\n    new DefaultStatusFactory($validator),\n);\n\n// ...\n```\n\n## Usage\n\nThe module contains several helper classes that contain most of the constants needed to work with the Balikobot API.\n\n- [**Definitions**](./docs/definitions.md)\n- [**Package service**](./docs/services.md#package-service)\n- [**Track service**](./docs/services.md#track-service)\n- [**Branch service**](./docs/services.md#branch-service)\n- [**Setting service**](./docs/services.md#setting-service)\n- [**Info service**](./docs/services.md#info-service)\n- [**Providers**](./docs/services.md#providers)\n\n\n## Testing\n\nTo run unit tests, run:\n\n```\ncomposer test:test\n```\n\nYou can also run only Unit or Integration test suites, run:\n\n```\ncomposer test:unit\ncomposer test:integration\n```\n\nTo show coverage, run:\n\n```\ncomposer test:coverage\n```\n\nTo run all test (phpcs, phpstan, phpunit, etc.), run:\n\n```\ncomposer test\n```\n\nFor testing purposes, you can use these credentials:\n\n- **API username:** `balikobot_test2cztest`\n- **API key:** `#lS1tBVo`\n\n\n## Contributing\n\nPlease see [CONTRIBUTING][link-contributing] and [CODE_OF_CONDUCT][link-code-of-conduct] for details.\n\n\n## Security\n\nIf you discover any security related issues, please email tomas.novotny@inspirum.cz instead of using the issue tracker.\n\n\n## Credits\n\n- [Tomáš Novotný](https://github.com/tomas-novotny)\n- [All Contributors][link-contributors]\n\n\n## License\n\nThe MIT License (MIT). Please see [License File][link-licence] for more information.\n\n\n[ico-license]:              https://img.shields.io/github/license/inspirum/balikobot-php.svg?style=flat-square\u0026colorB=blue\n[ico-workflow]:             https://img.shields.io/github/actions/workflow/status/inspirum/balikobot-php/master.yml?branch=master\u0026style=flat-square\n[ico-scrutinizer]:          https://img.shields.io/scrutinizer/coverage/g/inspirum/balikobot-php/master.svg?style=flat-square\n[ico-code-quality]:         https://img.shields.io/scrutinizer/g/inspirum/balikobot-php.svg?style=flat-square\n[ico-packagist-stable]:     https://img.shields.io/packagist/v/inspirum/balikobot.svg?style=flat-square\u0026colorB=blue\n[ico-packagist-download]:   https://img.shields.io/packagist/dt/inspirum/balikobot.svg?style=flat-square\u0026colorB=blue\n[ico-phpstan]:              https://img.shields.io/badge/style-level%208-brightgreen.svg?style=flat-square\u0026label=phpstan\n\n[link-author]:              https://github.com/inspirum\n[link-contributors]:        https://github.com/inspirum/balikobot-php/contributors\n[link-licence]:             ./LICENSE.md\n[link-changelog]:           ./CHANGELOG.md\n[link-contributing]:        ./docs/CONTRIBUTING.md\n[link-code-of-conduct]:     ./docs/CODE_OF_CONDUCT.md\n[link-workflow]:            https://github.com/inspirum/balikobot-php/actions\n[link-scrutinizer]:         https://scrutinizer-ci.com/g/inspirum/balikobot-php/code-structure\n[link-code-quality]:        https://scrutinizer-ci.com/g/inspirum/balikobot-php\n[link-api]:                 https://balikobot.docs.apiary.io/#introduction/prehled-zmen\n[link-api-v2]:              https://balikobotv2.docs.apiary.io/#introduction/prehled-zmen\n[link-api-v2-upgrade]:      https://balikobotv2.docs.apiary.io/#introduction/rozdil-api-v2-vs-api-v1\n[link-packagist-stable]:    https://packagist.org/packages/inspirum/balikobot\n[link-packagist-download]:  https://packagist.org/packages/inspirum/balikobot/stats\n[link-phpstan]:             https://github.com/phpstan/phpstan\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finspirum%2Fbalikobot-php","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Finspirum%2Fbalikobot-php","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finspirum%2Fbalikobot-php/lists"}