README

由 Michał Biarda 创建

1. 简介

创建此包是为了让您轻松地将 PHP 应用程序与 Inpost ShipX API 连接起来。

ShipX API 文档可在此处找到： https://docs.inpost24.com/display/PL/API+ShipX

此库是开源的。请随时贡献！

2. 安装

安装此包的推荐方法是使用 Composer。

composer require michalbiarda/shipx-php-sdk

注意：此包使用 HTTPlug 进行 HTTP 客户端抽象。请查看他们的官方文档以了解如何正确配置它。

3. SDK 的结构

3.1. 创建 API 客户端

所有对 ShipX API 的调用都是通过 \MB\ShipXSDK\Client\Client 对象进行的。要创建它，您需要提供 API URL（生产或沙盒）和您的 API 密钥（对于某些操作不需要 API 密钥）。

$client = new \MB\ShipXSDK\Client\Client(
    'https://sandbox-api-shipx-pl.easypack24.net',
    'y0urs3cr3tc0d3'
);

3.2. 调用 API 端点

要调用 API 端点，您需要使用客户端的 callMethod 方法。它需要以下参数

$method - 您想要运行的 API 方法；所有方法都可以在 src/Method/ 文件夹的子文件夹中找到；如果您需要，可以添加自己的方法
$uriParams - 需要用于特定方法的 URI 参数数组；您可以在方法的 getUriTemplate 方法中找到所需参数；例如：对于 URI 模板 /v1/organizations/:organization_id/address_books，所需的 URI 参数是 organization_id
$queryParams - 可能用于某些方法的查询参数数组，以便使您的调用更具体
- 如果方法实现了 \MB\ShipXSDK\Method\WithPaginatedResultsInterface，您可以使用以下参数
  - page - 指定您想获取的哪些多页结果页
- 如果方法实现了 \MB\ShipXSDK\Method\WithSortableResultsInterface，您可以使用以下参数
  - sort_by - 指定根据哪个字段对结果进行排序；可能值可以在方法的 getSortableFields 方法中找到
  - sort_order - 指定排序的方向；可能的值是 asc 和 desc
- 如果方法实现了 \MB\ShipXSDK\Method\WithFilterableResultsInterface，您
  - 可以使用方法 getFilters 中定义的所有参数
- 如果方法实现了 \MB\ShipXSDK\Method\WithQueryParamsInterface，您
  - 必须使用方法 getRequiredQueryParams 中定义的所有参数
  - 可以使用方法 getOptionalQueryParams 中定义的所有参数
$payload - 数据传输对象 (\MB\ShipXSDK\DataTransferObject\DataTransferObject)，对于所有实现 \MB\ShipXSDK\Method\WithJsonRequestInterface 的方法都是必需的；所需对象的名称可以在方法的 getRequestPayloadModelName 名称中找到。

callMethod 方法返回 \MB\ShipXSDK\Response\Response 对象。您可以通过运行响应的 getSuccess 方法来检查调用是否成功。响应的主体可以通过运行响应的 getPayload 方法来获取。它将是以下之一

\MB\ShipXSDK\Model\Error 对象，如果发生错误
\MB\ShipXSDK\Model\BinaryContent 对象，如果方法实现了 \MB\ShipXSDK\Method\WithBinaryResponseInterface 并由 API 返回了正确的二进制文件
数据传输对象，其名称可在方法的 getResponsePayloadModelName 方法中找到，如果方法实现了 \MB\ShipXSDK\Method\WithJsonResponseInterface。
如果没有发生错误且方法不需要任何请求体，则为 null。

callMethod 方法可能会抛出

如果响应体与预期的数据传输对象不匹配，则抛出 \MB\ShipXSDK\Exception\InvalidModelException，
如果连接出现问题，则抛出 \GuzzleHttp\Exception\GuzzleException。

3.3. 示例API调用

$addressForm = new \MB\ShipXSDK\Model\AddressForm();
$addressForm->city = 'Warszawa';
$addressForm->post_code = '01-234';
$addressForm->country_code = 'PL';
$addressForm->street = 'Testowa 11';
$addressForm->building_number = '12/23';

$receiver = new \MB\ShipXSDK\Model\TransactionPartyForm();
$receiver->phone = '123456789';
$receiver->email = 'some.guy@gmail.com';
$receiver->first_name = 'Michał';
$receiver->last_name = 'Testowy';
$receiver->address = $addressForm;

$dimensions = new \MB\ShipXSDK\Model\DimensionsSimple();
$dimensions->height = 21.5;
$dimensions->length = 2.1;
$dimensions->width = 1.7;

$weight = new \MB\ShipXSDK\Model\WeightSimple();
$weight->amount = 2.0;

$parcel = new \MB\ShipXSDK\Model\ParcelsSimple();
$parcel->dimensions = $dimensions;
$parcel->weight = $weight;
$parcel->is_non_standard = false;

$shipmentOfferForm = new \MB\ShipXSDK\Model\ShipmentOfferForm();
$shipmentOfferForm->receiver = $receiver;
$shipmentOfferForm->parcels = [$parcel];
$shipmentOfferForm->additional_services = [];
        
$response = $client->callMethod(
new \MB\ShipXSDK\Method\Shipment\CreateOffer(),
    ['organization_id' => '1234'],
    [],
    $shipmentOfferForm
);
if ($response->getSuccess()) {
    /** @var \MB\ShipXSDK\Model\Shipment $payload */
    $payload = $response->getPayload();
    echo 'Shipment ID is ' . $payload->id;
}

4. API端点覆盖范围

覆盖的端点：44/57

有集成测试的端点：38/57

4.1. 货物

4.1.1. 以简化模式创建货物

文档：链接

方法：\MB\ShipXSDK\Method\Shipment\Create

集成测试：\MB\ShipXSDK\Test\Integration\Client\ShipmentResourceTest::testSuccessfulSimpleFlow

4.1.2. 以报价模式创建货物

文档：链接

方法：\MB\ShipXSDK\Method\Shipment\CreateOffer

集成测试：\MB\ShipXSDK\Test\Integration\Client\ShipmentResourceTest::testSuccessfulOfferFlow

4.1.2.1. 为货物付款

文档：链接

方法：\MB\ShipXSDK\Method\Shipment\Buy

集成测试：\MB\ShipXSDK\Test\Integration\Client\ShipmentResourceTest::testSuccessfulOfferFlow

4.1.2.2. 批量选择报价

文档：链接

方法：\MB\ShipXSDK\Method\Shipment\SelectOffers

集成测试：无

4.1.2.3. 选择报价

文档：链接

方法：\MB\ShipXSDK\Method\Shipment\SelectOffer

集成测试：无

4.1.2.4. 批量支付货物

文档：链接

方法：\MB\ShipXSDK\Method\Shipment\BuyBulk

集成测试：\MB\ShipXSDK\Test\Integration\Client\ShipmentResourceTest::testSuccessfulBatchFlowWithoutBuying

4.1.3. 创建和查看多个货物

4.1.3.1. 创建多个货物

文档：链接

方法：\MB\ShipXSDK\Method\Shipment\CreateBatch

集成测试：\MB\ShipXSDK\Test\Integration\Client\ShipmentResourceTest::testSuccessfulBatchFlowWithBuying

4.1.3.2. 查看多个货物

文档：链接

方法：\MB\ShipXSDK\Method\Shipment\GetBatch

集成测试：\MB\ShipXSDK\Test\Integration\Client\ShipmentResourceTest::testSuccessfulBatchFlowWithBuying

4.1.4. 取消货物

文档：链接

方法：\MB\ShipXSDK\Method\Shipment\Cancel

集成测试：\MB\ShipXSDK\Test\Integration\Client\ShipmentResourceTest::testSuccessfulCancellation

注意：有时沙箱API会返回空体而不是错误负载。对于成功的调用，预期为空体。

4.1.5. 更新货物

文档：链接

方法：无

集成测试：无

4.1.6. 重新计算货物价格

文档：链接

方法：无

集成测试：无

4.1.7. 收集货物标签

文档：链接

方法：\MB\ShipXSDK\Method\Shipment\GetLabel

集成测试：\MB\ShipXSDK\Test\Integration\Client\ShipmentResourceTest::testSuccessfulSimpleFlow

4.1.8. 收集多个标签

文档：链接

方法：\MB\ShipXSDK\Method\Shipment\GetLabels

集成测试：\MB\ShipXSDK\Test\Integration\Client\ShipmentResourceTest::testSuccessfulBatchFlowWithBuying

4.1.9. 收集退货标签

文档：链接

方法：\MB\ShipXSDK\Method\Shipment\GetReturnLabels

集成测试：\MB\ShipXSDK\Test\Integration\Client\ShipmentResourceTest::testSuccessfulSimpleFlow

4.1.10. 搜索货物

文档：链接

方法：\MB\ShipXSDK\Method\Shipment\GetList

集成测试：\MB\ShipXSDK\Test\Integration\Client\ShipmentResourceTest::testGetListSuccessCall

注意：沙箱发货搜索经常无法通过ID找到发货信息，尽管使用标准get方法可以找到。

4.2. 状态

4.2.1. 状态列表

文档：链接

方法：\MB\ShipXSDK\Method\Status\GetList

集成测试：\MB\ShipXSDK\Test\Integration\Client\StatusResourceTest::testGetListSuccessfulCall

4.3. 跟踪发货

4.3.1. 发货历史

文档：链接

方法：\MB\ShipXSDK\Method\Tracking\Read

集成测试：\MB\ShipXSDK\Test\Integration\Client\TrackingResourceTest::testReadSuccessfulCall

注意：沙箱API不断返回“未找到资源”错误。

4.3.2. 发货服务历史

文档：链接

方法：无

集成测试：无

4.4. 用户

4.4.1. 用户列表

文档：链接

方法：\MB\ShipXSDK\Method\User\GetList

集成测试：无

注意：沙箱API不断返回“未找到资源”错误。

4.5. 组织

4.5.1. 获取组织信息

文档：链接

方法：\MB\ShipXSDK\Method\Organization\Read

集成测试：\MB\ShipXSDK\Test\Integration\Client\OrganizationResourceTest::testReadSuccessfulCall

4.5.2. 列出所有组织

文档：链接

方法：\MB\ShipXSDK\Method\Organization\GetList

集成测试：\MB\ShipXSDK\Test\Integration\Client\OrganizationResourceTest::testGetListSuccessfulCall

4.5.3. 组织统计

文档：链接

方法：无

集成测试：无

4.6. 发货模板

4.6.1. 下载模板

文档：链接

方法：无

集成测试：无

4.6.2. 模板列表

文档：链接

方法：无

集成测试：无

4.6.3. 添加模板

文档：链接

方法：无

集成测试：无

4.6.4. 删除模板

文档：链接

方法：无

集成测试：无

4.6.5. 编辑模板

文档：链接

方法：无

集成测试：无

4.6.6. 搜索发货模板

文档：链接

方法：无

集成测试：无

4.7. 发货点

4.7.1. 收集点的信息

文档：链接

方法：\MB\ShipXSDK\Method\DispatchPoint\Read

集成测试：无

4.7.2. 发货点列表

文档：链接

方法：\MB\ShipXSDK\Method\DispatchPoint\GetList

集成测试：无

4.8. 发货订单

4.8.1. 创建新的收集订单

文档：链接

方法：\MB\ShipXSDK\Method\DispatchOrder\Create

集成测试：\MB\ShipXSDK\Test\Integration\Client\ShipmentResourceTest::testSuccessfulDispatchOrderFlow

4.8.2. 收集关于收集订单的信息

文档：链接

方法：\MB\ShipXSDK\Method\DispatchOrder\Read

集成测试：\MB\ShipXSDK\Test\Integration\Client\ShipmentResourceTest::testSuccessfulDispatchOrderFlow

4.8.3. 删除收集订单

文档：链接

方法：\MB\ShipXSDK\Method\DispatchOrder\Delete

集成测试：\MB\ShipXSDK\Test\Integration\Client\ShipmentResourceTest::testSuccessfulDispatchOrderFlow

4.8.4. 收集订单列表

文档：链接

方法：\MB\ShipXSDK\Method\DispatchOrder\GetList

集成测试：\MB\ShipXSDK\Test\Integration\Client\ShipmentResourceTest::testSuccessfulDispatchOrderFlow

4.8.5. 为收集订单创建评论

文档：链接

方法：\MB\ShipXSDK\Method\DispatchOrder\CreateComment

集成测试：\MB\ShipXSDK\Test\Integration\Client\ShipmentResourceTest::testSuccessfulDispatchOrderFlow

4.8.6. 更新收集订单的评论

文档：链接

方法：\MB\ShipXSDK\Method\DispatchOrder\UpdateComment

集成测试：\MB\ShipXSDK\Test\Integration\Client\ShipmentResourceTest::testSuccessfulDispatchOrderFlow

4.8.7. 删除派送订单的评论

文档：链接

方法：\MB\ShipXSDK\Method\DispatchOrder\DeleteComment

集成测试：\MB\ShipXSDK\Test\Integration\Client\ShipmentResourceTest::testSuccessfulDispatchOrderFlow

4.8.8. 计算派送订单的价格

文档：链接

方法：\MB\ShipXSDK\Method\DispatchOrder\Calculate

集成测试：无

注意：每个正确的Sandbox API请求都会返回以下错误：“只有预付费用户才能执行此操作。”

4.8.9. 打印派送订单

文档：链接

4.8.9.1. 收集订单

方法：\MB\ShipXSDK\Method\DispatchOrder\GetPrintout

集成测试：\MB\ShipXSDK\Test\Integration\Client\ShipmentResourceTest::testSuccessfulDispatchOrderFlow

4.8.9.2. 指定的包裹编号

方法：\MB\ShipXSDK\Method\DispatchOrder\GetPrintouts

集成测试：\MB\ShipXSDK\Test\Integration\Client\ShipmentResourceTest::testSuccessfulDispatchOrderFlow

4.9. 地址簿

4.9.1. 地址簿中的地址列表

文档：链接

方法：\MB\ShipXSDK\Method\AddressBook\GetList

集成测试：\MB\ShipXSDK\Test\Integration\Client\AddressBookResourceTest::testSuccessfulCrudFlow

4.9.2. 收集地址信息

文档：链接

方法：\MB\ShipXSDK\Method\AddressBook\Read

集成测试：\MB\ShipXSDK\Test\Integration\Client\AddressBookResourceTest::testSuccessfulCrudFlow

4.9.3. 添加新地址

文档：链接

方法：\MB\ShipXSDK\Method\AddressBook\Create

集成测试：\MB\ShipXSDK\Test\Integration\Client\AddressBookResourceTest::testSuccessfulCrudFlow

4.9.4. 更新地址

文档：链接

方法：\MB\ShipXSDK\Method\AddressBook\Update

集成测试：\MB\ShipXSDK\Test\Integration\Client\AddressBookResourceTest::testSuccessfulCrudFlow

4.9.4. 删除地址

文档：链接

方法：\MB\ShipXSDK\Method\AddressBook\Delete

集成测试：\MB\ShipXSDK\Test\Integration\Client\AddressBookResourceTest::testSuccessfulCrudFlow

4.10. 服务

4.10.1. 服务列表

文档：链接

方法：\MB\ShipXSDK\Method\Service\GetList

集成测试：\MB\ShipXSDK\Test\Integration\Client\ServiceResourceTest::testGetListSuccessfulCall

4.11. 映射文件

4.11.1. 映射列表

文档：链接

方法：无

集成测试：无

4.11.2. 导出映射到xfile

文档：链接

方法：无

集成测试：无

4.11.3. 导出视图

文档：链接

方法：无

集成测试：无

4.12. 发送方法

4.12.1. 发送方法列表

文档：链接

方法：\MB\ShipXSDK\Method\SendingMethod\GetList

集成测试：\MB\ShipXSDK\Test\Integration\Client\SendingMethodResourceTest::testGetListSuccessfulCall

4.13. 成本中心 MPK

4.13.1. 下载成本中心集合

文档：链接

方法：\MB\ShipXSDK\Method\Mpk\GetList

集成测试：\MB\ShipXSDK\Test\Integration\Client\MpkResourceTest::testSuccessfulCruFlow

4.13.2. 创建成本中心

文档：链接

方法：\MB\ShipXSDK\Method\Mpk\Create

集成测试：\MB\ShipXSDK\Test\Integration\Client\MpkResourceTest::testSuccessfulCruFlow

4.13.3. 更新成本中心

文档：链接

方法：\MB\ShipXSDK\Method\Mpk\Update

集成测试：\MB\ShipXSDK\Test\Integration\Client\MpkResourceTest::testSuccessfulCruFlow

4.13.4. 下载单个对象

文档：链接

方法：\MB\ShipXSDK\Method\Mpk\Read

集成测试：\MB\ShipXSDK\Test\Integration\Client\MpkResourceTest::testSuccessfulCruFlow

4.14. 报告

4.14.1. 收集COD报告

文档：链接

方法：\MB\ShipXSDK\Method\Report\GetCod

集成测试：\MB\ShipXSDK\Test\Integration\Client\ReportResourceTest::testGetCodSuccessfulCall

4.15. 资源点

4.15.1. 点列表

文档：链接

方法：\MB\ShipXSDK\Method\Point\GetList

集成测试：\MB\ShipXSDK\Test\Integration\Client\PointResourceTest::testGetListSuccessfulCall

4.15.2. 点详情

文档：链接

方法：\MB\ShipXSDK\Method\Point\Read

集成测试：\MB\ShipXSDK\Test\Integration\Client\PointResourceTest::testReadSuccessfulCall

5. 已知问题

主要已知问题是沙箱API的不稳定性。有时新创建的运输处理非常缓慢或最终被取消。因此，集成测试有时会意外失败。我想我们只能接受它...

snapshotpl / shipx-php-sdk

维护者

详细信息

README

1. 简介

2. 安装

3. SDK 的结构

3.1. 创建 API 客户端

3.2. 调用 API 端点

3.3. 示例API调用

4. API端点覆盖范围

4.1. 货物

4.1.1. 以简化模式创建货物

4.1.2. 以报价模式创建货物

4.1.2.1. 为货物付款

4.1.2.2. 批量选择报价

4.1.2.3. 选择报价

4.1.2.4. 批量支付货物

4.1.3. 创建和查看多个货物

4.1.3.1. 创建多个货物

4.1.3.2. 查看多个货物

4.1.4. 取消货物

4.1.5. 更新货物

4.1.6. 重新计算货物价格

4.1.7. 收集货物标签

4.1.8. 收集多个标签

4.1.9. 收集退货标签

4.1.10. 搜索货物

4.2. 状态

4.2.1. 状态列表

4.3. 跟踪发货

4.3.1. 发货历史

4.3.2. 发货服务历史

4.4. 用户

4.4.1. 用户列表

4.5. 组织

4.5.1. 获取组织信息

4.5.2. 列出所有组织

4.5.3. 组织统计

4.6. 发货模板

4.6.1. 下载模板

4.6.2. 模板列表

4.6.3. 添加模板

4.6.4. 删除模板

4.6.5. 编辑模板

4.6.6. 搜索发货模板

4.7. 发货点

4.7.1. 收集点的信息

4.7.2. 发货点列表

4.8. 发货订单

4.8.1. 创建新的收集订单

4.8.2. 收集关于收集订单的信息

4.8.3. 删除收集订单

4.8.4. 收集订单列表

4.8.5. 为收集订单创建评论

4.8.6. 更新收集订单的评论

4.8.7. 删除派送订单的评论

4.8.8. 计算派送订单的价格

4.8.9. 打印派送订单

4.8.9.1. 收集订单

4.8.9.2. 指定的包裹编号

4.9. 地址簿

4.9.1. 地址簿中的地址列表

4.9.2. 收集地址信息

4.9.3. 添加新地址

4.9.4. 更新地址

4.9.4. 删除地址

4.10. 服务

4.10.1. 服务列表

4.11. 映射文件

4.11.1. 映射列表

4.11.2. 导出映射到xfile

4.11.3. 导出视图

4.12. 发送方法

4.12.1. 发送方法列表

4.13. 成本中心 MPK

4.13.1. 下载成本中心集合

4.13.2. 创建成本中心

4.13.3. 更新成本中心

4.13.4. 下载单个对象