README

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

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

安装

composer

composer require vldmrk/ukrposhta

使用

配置

每个类都接受一个对象作为构造函数参数：Ukrposhta\Data\Configuration。在此类中，我们使用相应的方法-设置器设置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错误，库将抛出异常（Exception），具体取决于GuzzleHttp\Client库对HTTP请求的行为。

查询参数

如果需要在请求中传递参数，则相应类的对应方法接受一个对象作为参数：Ukrposhta\Data\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类对象的形式，同时也可以传递用于保存的文件的路径。保存文件的路径也可以在这里传递。第四个参数是用于处理响应的闭包。

vldmrk / ukrposhta

维护者

详细信息