README

DP OneClickForApp API SDK 包提供以下网络服务的接口

• OneClickForApp V3

需求

系统需求

• PHP 8.1+ 与 SOAP 扩展

包需求

• psr/log：PSR-3 日志接口

建议的库

• zf1s/zend-pdf：用于从多标签响应中提取单独的代金券 PDF 文档的 PDF 库

开发包需求

• phpunit/phpunit：测试框架

安装

$ composer require deutschepost/sdk-api-oneclickforapp

卸载

$ composer remove deutschepost/sdk-api-oneclickforapp

测试

$ ./vendor/bin/phpunit -c test/phpunit.xml

特性

DP OneClickForApp API SDK 支持以下特性

• 检索页面格式
• 检索合同产品
• 创建 PDF 格式的 Internetmarke 邮政邮票

主要功能是通过德国邮政 AG OneClickForApplication 网络服务接口订购 Internetmarke 代金券。网络服务请求需要订购的邮寄产品的详细信息以及结果 PDF 文档的页面尺寸。

整个过程概述如下

• 从单独的产品网络服务（deutschepost/sdk-api-prodws）检索可用的邮寄产品
• 通过（检索合同产品）用个别合同价格替换一般产品价格
• 检索可用的打印格式（检索页面格式）
• 为页面格式之一订购代金券，指定每个订单位置的邮寄产品（标识符和价格）

网络服务需要对某些操作进行身份验证令牌。库检索一个令牌，但在进程结束后将其丢弃。为了重用令牌，可以传递一个持久存储（持久身份验证令牌）。

检索页面格式

加载可以打印 Internetmarke 代金券的页面格式列表。打印格式在布局特性上有所不同，并具有不同的功能。

公共 API

适合消费的库组件包括

• 服务
  • 应用程序令牌存储
  • 服务工厂
  • 账户信息服务
• 数据传输对象
  • 凭证
  • 页面格式

使用方法

$logger = new \Psr\Log\Test\TestLogger();
$tokenStorage = new \DeutschePost\Sdk\OneClickForApp\Auth\TokenStorage();
$credentials = new \DeutschePost\Sdk\OneClickForApp\Auth\Credentials(
    $username = '', // page formats are public, no user auth needed
    $password = '',
    $partnerId = 'PARTNER_ID',
    $partnerKey = 'SCHLUESSEL_DPWN_MEINMARKTPLATZ',
    $keyPhase = 1,
    $tokenStorage
);

$serviceFactory = new \DeutschePost\Sdk\OneClickForApp\Service\ServiceFactory();
$service = $serviceFactory->createAccountInformationService($credentials, $logger);
$pageFormats = $service->getPageFormats();

// work with the web service response, e.g. drop page formats that cannot print addresses
$pageFormatsWithAddress = array_filter(
    $pageFormats,
    static function (\DeutschePost\Sdk\OneClickForApp\Api\Data\PageFormatInterface $pageFormat) {
        return $pageFormat->isAddressPossible();
    }
);

检索合同产品

订购 Internetmarke 代金券时，必须在请求中包含所选邮寄产品的价格。如果提交的产品价格与价格表不匹配，则网络服务将拒绝请求。

正确价格可以从官方的 "Produkte- und Preisliste" (PPL) 通过 ProdWS API SDK 获取，或者如果可用，从用户的合同中获取。

公共 API

适合消费的库组件包括

• 服务
  • 应用程序令牌存储
  • 服务工厂
  • 账户信息服务
• 数据传输对象
  • 凭证
  • 合同产品

使用方法

$logger = new \Psr\Log\Test\TestLogger();
$tokenStorage = new \DeutschePost\Sdk\OneClickForApp\Auth\TokenStorage();
$credentials = new \DeutschePost\Sdk\OneClickForApp\Auth\Credentials(
    $username = 'max.mustermann@example.com',
    $password = 'portokasse321',
    $partnerId = 'PARTNER_ID',
    $partnerKey = 'SCHLUESSEL_DPWN_MEINMARKTPLATZ',
    $keyPhase = 1,
    $tokenStorage
);

$serviceFactory = new \DeutschePost\Sdk\OneClickForApp\Service\ServiceFactory();
$service = $serviceFactory->createAccountInformationService($credentials, $logger);

// work with the web service response, e.g. replace PPL prices 
foreach ($service->getContractProducts() as $contractProduct) {
    $prodWsProduct = $this->productRepository->get($pplId = $contractProduct->getId());
    $prodWsProduct->setPrice($contractProduct->getPrice());
    $this->productRepository->save($prodWsProduct);
}

创建邮票

为页面格式订购Internetmarke代金券。如果在一个服务调用中请求多个代金券，则网络服务将所有代金券创建在一个PDF文件中。库尝试分割原始文档并返回每个代金券一个标签。这仅适用于某些页面格式，由于技术原因，会导致总文件大小增大。

公共 API

适合消费的库组件包括

• 服务
  • 应用程序令牌存储
  • 服务工厂
  • 订购服务
  • 数据传输对象构建器
• 数据传输对象
  • 凭证
  • 带代金券的订购

使用方法

$logger = new \Psr\Log\Test\TestLogger();
$tokenStorage = new \DeutschePost\Sdk\OneClickForApp\Auth\TokenStorage();
$credentials = new \DeutschePost\Sdk\OneClickForApp\Auth\Credentials(
    $username = 'max.mustermann@example.com',
    $password = 'portokasse321',
    $partnerId = 'PARTNER_ID',
    $partnerKey = 'SCHLUESSEL_DPWN_MEINMARKTPLATZ',
    $keyPhase = 1,
    $tokenStorage
);

// init a new builder for every order
$orderItemBuilder = \DeutschePost\Sdk\OneClickForApp\Model\ShoppingCartPositionBuilder::forPageFormat($pageFormatsWithAddress[0]);

// create as many items as needed per order
$orderItemBuilder->setItemDetails($prodWsProduct->getPPLId(), $prodWsProduct->getPrice());
$orderItemBuilder->setShipperAddress(
    $shipperCompany = 'DHL',
    $shipperCountry = 'DEU',
    $shipperPostalCode = '53113',
    $shipperCity = 'Bonn',
    $shipperStreetName = 'Charles-de-Gaulle-Straße',
    $shipperStreetNumber = '20',
    $shipperLastName = 'Doe',
    $shipperFirstName = 'John'
);

$orderItemBuilder->setRecipientAddress(
    $recipientLastName = 'Doe',
    $recipientFirstName = 'Jane',
    $recipientCountry = 'DEU',
    $recipientPostalCode = '53113',
    $recipientCity = 'Bonn',
    $recipientStreet = 'Sträßchensweg',
    $recipientStreetNumber = '2',
    null,
    null,
    $recipientCompany = 'DP'
);

$serviceFactory = new \DeutschePost\Sdk\OneClickForApp\Service\ServiceFactory();
$orderService = $serviceFactory->createOrderService($credentials, $logger);
$order = $orderService->createOrder(
    [$orderItemBuilder->create()],
    $orderItemBuilder->getTotalAmount(),
    $orderItemBuilder->getPageFormatId()
);

// work with the web service response, e.g. persist label
file_put_contents("/tmp/{$order->getId()}.pdf", $order->getLabel());
foreach ($order->getVouchers() as $voucher) {
    if ($voucher->getLabel()) {
        file_put_contents("/tmp/{$voucher->getVoucherId()}.pdf", $voucher->getLabel());
    }
}

持久认证令牌

为了在令牌的生命周期内重用它，可以创建带有自定义令牌存储的凭据对象。实现访问数据库、缓存或其他任何合适的来源。

使用方法

// PersistentTokenStorage implements \DeutschePost\Sdk\OneClickForApp\Api\TokenStorageInterface
$tokenStorage = new \My\OneClickForApp\Auth\PersistentTokenStorage();
$credentials = new \DeutschePost\Sdk\OneClickForApp\Auth\Credentials(
    $username = 'max.mustermann@example.com',
    $password = 'portokasse321',
    $partnerId = 'PARTNER_ID',
    $partnerKey = 'SCHLUESSEL_DPWN_MEINMARKTPLATZ',
    $keyPhase = 1,
    $tokenStorage
);