README

该 fet/postcard-api 包是瑞士邮政卡片API的PHP实现（见参考文献）。

安装

要安装此包，请使用Composer

composer require fet/postcard-api

在运行此命令之前，请确保您的系统已安装Composer。

配置

使用您的API凭据创建一个新的 Fet\PostcardApi\PostcardCreator 实例

use Fet\PostcardApi\PostcardCreator;

$postcardCreator = PostcardCreator::factory(
    'POSTCARD_API_URL', // The base URL of the postcard API
    'POSTCARD_API_CAMPAIGN_KEY', // Your postcard API campaign key
    'POSTCARD_API_CLIENT_ID', // Your postcard API client ID
    'POSTCARD_API_CLIENT_SECRET', // Your postcard API client secret
);

用法

活动

活动API允许您获取有关您的活动的信息。要与活动API交互，首先从卡片创建器获取活动实例

$campaign = $postcardCreator->getCampaign();

一旦您有了活动实例，您可以使用以下方法访问其信息

// get the unique identifier for the campaign
$campaign->getCampaignKey();

// get the total quota of postcards allowed in the campaign
$campaign->getQuota();

// get the number of postcards already created within the campaign
$campaign->getNumberOfCreatedPostcards();

// get the remaining number of postcards that can be created in the campaign
$campaign->getNumberOfAvailablePostcards();

卡片

要使用卡片API，您需要提供收件人和寄件人地址详情，卡片正面图像的路径以及要打印在卡片上的文本。以下是一个如何做到这一点的示例

use Fet\PostcardApi\PostcardCreator;

// recipient address details
$recipient = [
    'title' => 'Mr.',
    'firstname' => 'John',
    'lastname' => 'Smith',
    'company' => 'ABC Inc.',
    'street' => '123 Main St.',
    'houseNr' => '456',
    'zip' => '12345',
    'city' => 'Anytown',
    'country' => 'United States',
    'poBox' => 'P.O. Box 789',
    'additionalAdrInfo' => 'Apt. 789',
];

// sender address details
$sender = [
    'firstname' => 'Jane',
    'lastname' => 'Doe',
    'company' => 'XYZ Corp.',
    'street' => '456 Elm St.',
    'houseNr' => '789',
    'zip' => '67890',
    'city' => 'Anyville',
];

// path to the front image
$image = 'path-to-image';

// text to be printed on the postcard
$senderText = 'Lorem ipsum dolor sit amet, consectetur adipiscing elit.';

// create the postcard
$postcard = $postcardCreator->create($recipient, $sender, $image, $senderText);

// approve the postcard
$postcard->approve();

$recipient 和 $sender 数组没有必需的键/值对，但如果出现错误，$postcard 实例将返回错误和警告。

高级用法

如果您想，可以进一步操作 $postcard 实例

// add a stamp image to the postcard
$postcard->addStampImage('path-to-stamp-image');

// add branding text to the postcard
$postcard->addBrandingText('branding-text');

// add a branding image to the postcard
$postcard->addBrandingImage('path-to-branding-image');

// add a branding QR tag to the postcard, with an optional side text
$postcard->addBrandingQrTag('qr-tag-text', 'qr-tag-side-text');

// get a base64-encoded preview image of the front of the postcard
$postcard->getFrontPreview()->getImageData();

// get a base64-encoded preview image of the back of the postcard
$postcard->getBackPreview()->getImageData();

addBrandingText()、addBrandingImage() 和 addBrandingQrTag() 方法不能相互组合使用，因为它们将覆盖彼此的内容。请为您的卡片品牌选择一个方法使用。

审批

只有当API没有返回错误时，卡片才能被批准。否则，将抛出 Fet\PostcardApi\Exception\PostcardException.php 异常。

处理警告和错误

如果在创建卡片的处理过程中API返回了警告或错误，您可以按以下方式检索它们

// returns a multidimensional array with warnings
$warnings = $postcard->getWarnings();

// returns a multidimensional array with errors
$errors = $postcard->getErrors();

演示

配置

在运行演示之前，您必须编辑 examples/config.php 文件

return [
    'url' => 'POSTCARD_API_URL',
    'campaign_key' => 'POSTCARD_API_CAMPAIGN_KEY',
    'client_id' => 'POSTCARD_API_CLIENT_ID',
    'client_secret' => 'POSTCARD_API_CLIENT_SECRET',
];

在浏览器中运行演示

要启动演示并查看卡片API的实际工作情况，请按照以下步骤操作

通过运行以下命令启动本地PHP开发服务器

php -S localhost:8888 -t examples

打开您的网页浏览器，并转到以下URL： https://:8888/

测试

使用以下命令运行测试

composer test

参考文献

技术规范

https://developer.post.ch/en/technical-specifications-of-postcard-api

Swagger文档

https://api.post.ch/pcc-doc/doctools/swagger-ui/dist/index.html?url=https://api.post.ch/pcc-doc/doctools/swagger-ui/src/openapi/api.yaml&_ga=2.187366318.709186670.1679047313-1057897365.1677000967

fet / postcard-api

维护者

详细信息