README

实现了 Balikobot API v2，该 API 在官方文档中描述，直到 v2.004 (2024-08-06)。

如果您想使用较旧的 API v1，请使用 ^4.0 版本。

更多详细信息请参阅变更日志。

使用示例

在使用部分，您可以查看更多可用的方法文档。

此处展示的所有代码片段均已修改以增强可读性，因此它们可能无法直接运行。

创建套餐并订购货运

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.'
]
*/

测试套餐数据 / 删除套餐

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);

跟踪套餐

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 
}

导入分支机构

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'
    ...
  }
  */
}

系统要求

如果您仍在使用较旧的 PHP 版本，您可以使用此包的 ^5.0 版本（适用于 PHP 7.1+）。

安装

运行 composer require 命令

composer require inspirum/balikobot

或将需求添加到您的 composer.json

"inspirum/balikobot": "^7.0"

设置服务

可用的框架集成

但是，您也可以在没有框架实现的情况下使用它

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),
);

// ...

使用

该模块包含几个辅助类，其中包含与 Balikobot API 一起工作所需的大部分常量。

测试

要运行单元测试，请运行

composer test:test

您还可以仅运行单元测试或集成测试套件，请运行

composer test:unit
composer test:integration

要显示覆盖率，请运行

composer test:coverage

要运行所有测试（phpcs、phpstan、phpunit 等），请运行

composer test

为测试目的，您可以使用以下凭据

API 用户名： balikobot_test2cztest
API 密钥： #lS1tBVo

贡献

请参阅 CONTRIBUTING 和 CODE_OF_CONDUCT 以获取详细信息。

安全性

如果您发现任何安全相关的问题，请通过电子邮件 tomas.novotny@inspirum.cz 而不是使用问题跟踪器。

鸣谢

许可证

MIT 许可证（MIT）。有关更多信息，请参阅许可证文件。

inspirum / balikobot

维护者

详细信息