README

内容

安装
跟踪
- 单次访问
  - 关于到付信息的说明
- 批量访问
发送
- 计算邮寄费用
- 获取余额
- 数据归一化和验证
- 文件
  - 用于订单的F7p表格
  - 用于订单的F112ЭК表格
  - 订单文件包（在形成批次之前）
  - 订单文件包（在形成批次之后）
  - 批次文件包
  - 批次内容检查单
  - 用于批次的F103表格
  - 在一页打印页上生成退货标签
  - 准备和发送F103表格的电子版（用于批次）
- 用户设置
- 订单
  - 创建
  - 按商店标识符搜索
  - 按俄罗斯邮政标识符搜索
  - 编辑
  - 删除
  - 返回“新”
- 批次
  - 创建订单批次
  - 更改批次在OPS的发送日
  - 将订单移动到批次
  - 将订单添加到批次
  - 从批次中删除订单
  - 请求批次订单数据
  - 按名称搜索批次
  - 搜索所有批次
  - 按SHP搜索订单
  - 按俄罗斯邮政标识符搜索订单
- 存档
  - 请求批次数据
  - 将批次转移到存档
  - 从存档中恢复批次
- 搜索OPS
  - 按索引
  - 按地址
  - 按坐标
  - 在居民点搜索索引
  - OPS的邮政服务
  - 按服务组标识符搜索OPS的邮政服务
  - 从OPS护照中导出
- 长期存储
  - 请求订单数据

仅在与俄罗斯邮政签订合同的情况下才能使用批量跟踪API和发送API。

可以与合同或简单注册（但有限制 - 每日100次请求）一起使用单个跟踪API。

安装

最低要求是PHP 7.1+、ext-soap和ext-json。

请使用包管理器 Composer 进行安装

composer require appwilio/russianpost-sdk

当使用 Laravel 框架时，SDK将自动注册可用服务。

最低的Laravel版本为5.8。

日志记录

可以通过连接任何实现PSR-3标准的日志记录器来记录请求和响应，例如，Monolog

use Monolog\Logger;
use Monolog\Handler\StreamHandler;

$log = (new Logger('pochta.ru'))
    ->pushHandler(new StreamHandler('path/to/your.log', Logger::INFO));

// SingleAccessClient, PacketAccessClient, DispatchingClient
$client->setLogger($log);

在Laravel框架中，应在容器中添加名为appwilio.russianpost.logger的日志记录器。

use Monolog\Logger;
use Monolog\Handler\StreamHandler;

$this->app->singleton('appwilio.russianpost.logger', static function () {
    return (new Logger('pochta.ru'))
        ->pushHandler(new StreamHandler('path/to/your.log', Logger::INFO));
});

跟踪

文档

Laravel中的配置

请在services.php中添加以下密钥

// ...
'russianpost' => [
    'tracking' => [
        'login' => \env('RUSSIAN_POST_TRACKING_LOGIN'),
        'password' => \env('RUSSIAN_POST_TRACKING_PASSWORD'),
    ],
],
// ...

如果它们已被缓存，请务必重新生成设置缓存！

单次访问

单个访问客户端类的构造函数接受两个参数 - 俄罗斯邮政网站的登录名和密码。

use Appwilio\RussianPostSDK\Tracking\SingleAccessClient;

$tracker = new SingleAccessClient($login = 'login', $password = 'secret');

如果找不到SHP（跟踪码）信息，则抛出异常 Appwilio\RussianPostSDK\Tracking\Exceptions\SingleAccessException 并显示相应的消息。

获取SHP（跟踪码）数据

$response = $tracker->getTrackingEvents('29014562148754');

对象 $response 实现了接口 \IteratorAggregate，因此可以直接在循环中遍历。

foreach ($response as $events) {
    $parameters = $events->getOperationParameters();
    
    echo $parameters->getOperationId();
    echo $parameters->getAttributeId();
    echo $parameters->getPerformedAt()->format('d.m.Y в h:i:s'); // 17.09.2019 в 17:20:48
}

通过SPS（跟踪商）获取代付款信息。

$response = $tracker->getCashOnDeliveryEvents('29014562148754');

对象 $response 实现了接口 \IteratorAggregate，因此可以直接在循环中遍历。

foreach ($response as $event) {
    $parameters = $event->getOperationParameters();
    
    echo $parameters->getTransferNumber();
    echo $parameters->getPayment(); // 7410
    echo $parameters->getPerformedAt()->format('d.m.Y в h:i:s'); // 17.09.2019 в 17:20:48
}

批量访问

use Appwilio\RussianPostSDK\Tracking\PacketAccessClient;

$tracker = new PacketAccessClient($login = 'login', $password = 'secret');

获取SHP（跟踪码）数据

$ticket = $tracker->getTicket(['29014562148754', 'RA325487125CN']); // максимум 3 000 треков

建议在请求信息之前等待15分钟。

$response = $tracker->getTrackingEvents($ticket->getId());

echo $response->getPreparedAt()->format('d.m.Y в h:m:s');

对象 $response 实现了接口 \IteratorAggregate，因此可以直接在循环中遍历。

foreach ($response as $item) {
    echo $item->getBarcode();
    
    foreach ($item as $events) {
        echo $events->getOperationId();
        echo $events->getAttributeId();
        echo $events->getPerformedAt()->format('d.m.Y в h:m:s'); // 17.09.2019 в 17:20:48
    }
}

发送

文档

配置

类 DispatchingClient 的构造函数接受三个必填参数：在俄罗斯邮政网站个人账户的登录名和密码，以及当连接“发送”服务时发送到邮箱的访问令牌，该令牌可以在个人账户中修改。

use GuzzleHttp\Client as GuzzleClient;
use Appwilio\RussianPostSDK\Dispatching\DispatchingClient;

$dispatching = new DispatchingClient(
    $login = 'login', $password = 'secret', $token = 'QWERTY', new GuzzleClient()
);

Laravel中的配置

请在services.php中添加以下密钥

// ...
'russianpost' => [
    'dispatching' => [
        'token' => \env('RUSSIAN_POST_DISPATCHING_TOKEN'),
        'login' => \env('RUSSIAN_POST_TDISPATCHING_LOGIN'),
        'password' => \env('RUSSIAN_POST_DISPATCHING_PASSWORD'),
        'guzzle' => [
            'timeout' => 5,
        ],
    ],
],
// ...

如果它们已被缓存，请务必重新生成设置缓存！

计算邮寄费用

use Appwilio\RussianPostSDK\Dispatching\Enum\MailType;
use Appwilio\RussianPostSDK\Dispatching\Enum\MailCategory;
use Appwilio\RussianPostSDK\Dispatching\Enum\MailEntryType;
use Appwilio\RussianPostSDK\Dispatching\Endpoints\Services\Requests\CalculationRequest;

$response = $dispatching->services->calculate(
    CalculationRequest::create('123456', 200)
        ->ofMailType(MailType::PARCEL_POSTAL())
        ->ofMailCategory(MailCategory::ORDINARY())
        ->ofEntriesType(MailEntryType::GOODS())
        ->fragile()
        ->withSmsNotice()
);

echo $response->getTotal()->getRate();
echo $response->getTotal()->getVAT(); // НДС

数据归一化和验证

姓名规范化

use Appwilio\RussianPostSDK\Dispatching\Endpoints\Services\Requests\NormalizeFioRequest;

$response = $dispatching->services->normalizeFio(
    NormalizeFioRequest::one('иванов иван иванович')
);

if ($response[0]->isUseful()) {
    echo $response[0]->getFirstName().' '.$response[0]->getLastName(); // Иван Иванов
}

地址规范化

use Appwilio\RussianPostSDK\Dispatching\Endpoints\Services\Requests\NormalizeAddressRequest;

$response = $dispatching->services->normalizeAddress(
    NormalizeAddressRequest::one('Москва варшавское шоссе 37-45')
);

电话规范化

use Appwilio\RussianPostSDK\Dispatching\Endpoints\Services\Requests\NormalizePhoneRequest;

$response = $dispatching->services->normalizePhone(NormalizePhoneRequest::one('89001234567'));

检查收件人信誉

use Appwilio\RussianPostSDK\Dispatching\Endpoints\Services\Requests\CheckRecipientRequest;

$response = $dispatching->services->checkRecipient(
    CheckRecipientRequest::one('Москва, Варшавское шоссе, 37-45', 'Иванов Иван Иванович', '+7 123 456-78-90')
);

$response[0]->isFraud(); // ненадёжный
$response[0]->isReliable(); // надёжный

use Appwilio\RussianPostSDK\Dispatching\Endpoints\Services\Requests\CheckRecipientRequest;

$request = CheckRecipientRequest::create();
$request->addRecipient('123456 Москва, Варшавское шоссе, 37-45', 'Иванов Иван Иванович', '+7 123 456-78-90');

$response = $dispatching->services->checkRecipient($request);

foreach ($response as $recipient) {
    echo $recipient->getAddress.': '.$recipient->isReliable();
}

文件

$file = $dispatching->documents->orderF7Form('12345678');

echo $file->getClientFilename(); // f7p.pdf

// Сохранение
$file->moveTo("storage/printforms/12345678-{$file->getClientFilename()}");

// Перенаправление в браузер (Laravel)
return \response()->streamDownload(staticfunction () use ($file) {
    (string) $file->getStream();
}, $file->getClientName(), ['Content-Type' => $file->getClientMediaType()]);

用于订单的F7p表格

use Appwilio\RussianPostSDK\Dispatching\Enum\PrintType;

$pdf = $dispatching->documents->orderF7Form(
    '12345678', new \DateTime('2019-01-01'), PrintType::PAPER()
);

用于订单的F112ЭК表格

$pdf = $dispatching->documents->orderF112Form('12345678', new \DateTime('2019-01-01'));

订单文件包（在形成批次之前）

$zip = $dispatching->documents->orderFormsBundleBacklog('12345678', new \DateTime('2019-01-01'));

订单文件包（在形成批次之后）

use Appwilio\RussianPostSDK\Dispatching\Enum\PrintType;

$zip = $dispatching->documents->orderFormBundle(
    '12345678', new \DateTime('2019-01-01'), PrintType::THERMO()
);

批次文件包

$zip = $dispatching->documents->batchFormBundle('87654321');

批次内容检查单

$pdf = $dispatching->documents->batchCheckingForm('87654321');

用于批次的F103表格

$pdf = $dispatching->documents->batchF103Form('87654321');

返回标签

use Appwilio\RussianPostSDK\Dispatching\Enum\PrintType;

$pdf = $dispatching->documents->easyReturnForm('29014562148754', PrintType::THERMO());

启动测试

$ vendor/bin/phpunit

作者

许可协议

本SDK在MIT许可证下发布。

appwilio / russianpost-sdk

维护者

详细信息

README

内容

安装

日志记录

跟踪

Laravel中的配置

单次访问

获取SHP（跟踪码）数据

通过SPS（跟踪商）获取代付款信息。

批量访问

获取SHP（跟踪码）数据

发送

配置

Laravel中的配置

计算邮寄费用

数据归一化和验证

姓名规范化

地址规范化

电话规范化

检查收件人信誉

文件

用于订单的F7p表格

用于订单的F112ЭК表格

订单文件包（在形成批次之前）

订单文件包（在形成批次之后）

批次文件包

批次内容检查单

用于批次的F103表格

返回标签

启动测试

作者

许可协议