README

Ukrposhta 是用于操作乌克兰邮政 API 的库，以下简称 UP。在此项目中实现了以下功能：

• 目录 - 乌克兰邮政分支机构地址列表，包括地区、区域、城市、分支机构和街道。
• 客户 - 与合作伙伴（创建、编辑）的工作。客户用于创建发送。
• 地址 - 与客户地址（创建、编辑）的工作。地址绑定到客户并在创建发送时使用。
• 发送 - 与邮政发送（创建、编辑、跟踪状态）的工作。
• 表格 - 获取发送表单（运单）的 pdf 格式。
• 文档 - 获取 API 的最新文档。

安装

composer

composer require zaman-ua/ukrposhta

使用

配置

每个类都接受一个构造函数参数对象-配置：Ukrposhta\Data\Configuration。在此类中，我们使用相应的setter方法设置 token 和 bearer。

$config = new Ukrposhta\Data\Configuration();
$config->setBearer('string bearer'); 
$config->setToken('string token');

此外，您还可以使用相应的方法添加请求头。

$config->addHeaders([
    'Content-Type' => 'application/json'
]);

通用文档

API

有关 API 参数和返回字段的最新文档可以在官方 网站 上获得，或使用该库中的类。

$config = new Ukrposhta\Data\Configuration();
$config->setBearer('string bearer'); 
$doc = new Ukrposhta\Doc($config);
$doc->save('./');

方法 save 接受两个参数。第一个是必需的 - 这是保存文件的路径，第二个是非必需的 - 这是保存的文件名，默认为 "documentation.pdf"。

返回数据，异常(Exceptions)

当 API 必须返回数据时（例如，当处理目录或 API 文档时） - 将返回数据数组。当发生错误时，无论是服务器错误还是 API 错误 - 该库将根据 GuzzleHttp\Client 的 HTTP 请求行为抛出异常（Exception）。

查询参数

当需要将参数传递给查询时，相应的类方法作为参数接受对象类 Ukrposhta\Data\Storage。Storage 类的构造函数（Storage）接受一个可选参数，即包含键值对的数组。可以通过多种方式指定数据

$params = [
    'firstName' => 'Test_First_Name',
    'lastName' => 'Test_Last_Name'
    'middleName' => 'Test_Middle_Name'
];
$storage = new Ukrposhta\Data\Storage($params);
$storage->addData($storage);
$storage->setData('lastName', Test2_Last_Name);
$storage->firstName = 'Test2_First_Name';

目录处理

目录处理由以下类表示

• Ukrposhta\Directory\City
• Ukrposhta\Directory\District
• Ukrposhta\Directory\Postoffice
• Ukrposhta\Directory\Region
• Ukrposhta\Directory\Street

对于获取城市、地区、区域和街道的列表，有相应的类的 getList 方法。

$config = new Ukrposhta\Data\Configuration();
$config->setBearer('string bearer'); 
$config->setToken('string token');
$cities = new Ukrposhta\Directory\City($config)->getList();
$districts = Ukrposhta\Directory\District($config)->getList();
$regions = Ukrposhta\Directory\Region($config)->getList();
$streets = Ukrposhta\Directory\Street($config)->getList();

对于按区域过滤城市列表

$params = new Ukrposhta\Data\Storage();
$params->region_id = 1;
$cities = new Ukrposhta\Directory\City($config)->getList($params);

按城市 id 获取部门列表

$postoffices = new Ukrposhta\Directory\Postoffice($config)->getByCityId(1);

按邮政编码获取部门

$storage = new Ukrposhta\Data\Storage();
$postoffices = new Ukrposhta\Directory\Postoffice($config)->getByPostIndex(72370);

地址、合作伙伴、发送

数据模型处理实现在以下类中

• Ukrposhta\Address
• Ukrposhta\Client
• Ukrposhta\Shipment

要创建合作伙伴地址、合作伙伴和发送，需要使用相应类的 save 方法。此方法将第一个参数作为 Ukrposhta\Data\Storage 类的对象，其中包含查询参数。
创建合作伙伴的示例

$config = new Ukrposhta\Data\Configuration();
$config->setBearer('string bearer'); 
$config->setToken('string token');
$params = [
    'firstName' => 'Марк'
    'lastName' => 'Зотов'
    'middleName' => 'Олегович'
    'addressId' => 1250990
    'type' => 'INDIVIDUAL'
];
$storage = new Ukrposhta\Data\Storage($params);
$client = new Ukrposhta\Client($config);
$client->save($storage);

要更新合作伙伴的信息，需要在 save 方法中第二个参数中指定合作伙伴的 UUID

$client->save($storage, 'string client UUID');

要获取客户信息，请使用 get 方法

$client->get('customer id');

此方法接受第一个参数为客户标识符，默认为合作伙伴的 UUID。如果指定第二个参数为 true，则在这种情况下第一个参数将作为 external-id。

打印运单

处理运单有一个名为 Ukrposhta\Form 的类，其中包含一个名为 getSticker 的方法

$config = new Ukrposhta\Data\Configuration();
$config->setBearer('string bearer'); 
$config->setToken('string token');
$form = new Ukrposhta\Form($config);
$resource = \GuzzleHttp\Psr7\Utils::tryFopen('/path/to/sticker.pdf', 'w');
$params = new Storage([
    'sink' => $resource
])



$form->getSticker('shipment uuid or barcode', $params);

该方法接受两个必填参数，第一个是发送标识符（UUID 发送或条形码），第二个是作为对象传递到请求中的参数列表，该对象属于 Ukrposhta\Data\Storage 类。此外，您还可以在该对象中指定用于保存的文件路径，链接至 保存文件的说明。第四个是用于处理响应的闭包。