README

此包提供E-POSTBUSINESS API的PHP集成。

安装

通过Composer

$ composer require richardhj/epost-api

使用

用户认证

首先，您需要通过用户认证来获取一个AccessToken实例。我建议使用此OAuth2提供商来获取访问令牌。

// Authenticate
/** @var League\OAuth2\Client\Token\AccessToken $token */
$token = $this->fetchAccessToken();

提供元数据

信封

我们迈出大步，创建一个Letter实例。该实例收集所有元数据（信封、投递选项等），在E-POST门户上创建信件草稿，并最终发送信件。

// Create letter and envelope
$letter = new Richardhj\EPost\Api\Letter();
$envelope = new Richardhj\EPost\Api\Metadata\Envelope();
$envelope
    ->setSystemMessageTypeNormal()  // For sending an electronic letter *OR*
    ->setSystemMessageTypeHybrid()  // For sending a physical letter
    ->setSubject('Example letter');

收件人

我们创建了信封，需要添加收件人。这是电子信件的添加方式。

// Add recipients for normal letter
$recipient = new Richardhj\EPost\Api\Metadata\Envelope\Recipient\Normal::createFromFriendlyEmail('John Doe <doe@example.com>');

$envelope->addRecipientNormal($recipient);

这是打印信件的添加方式。对于打印信件，只有一个收件人有效！

// Set recipients and delivery options for printed letter
$recipient = new Richardhj\EPost\Api\Metadata\Envelope\Recipient\Hybrid();
$recipient
    ->setFirstName('John')
    ->setLastName('Doe')
    ->setStreetName('…')
    ->setZipCode('1234')
    ->setCity('…');

$envelope->addRecipientPrinted($recipient);

投递选项

我们还定义了DeliveryOptions，因为它们定义了信件是否将上色等。这仅适用于打印信件。

// Set delivery options
$deliveryOptions = new Richardhj\EPost\Api\Metadata\DeliveryOptions();
$deliveryOptions
    ->setRegisteredStandard()   // This will make the letter sent as "Einschreiben ohne Optionen"
    ->setColorColored()         // To make it expensive
    ->setCoverLetterIncluded(); // The cover letter (with recipient address block) is included in the attachments

$letter->setDeliveryOptions($deliveryOptions);

完成

我们将开始与E-POST门户的通信。

// Prepare letter
$letter
    ->setTestEnvironment(true)
    ->setAccessToken($token)
    ->setEnvelope($envelope)
    ->setCoverLetter('This is an example');

// Set attachments
$letter->addAttachment('/var/www/test.pdf');

// Create and send letter
try {
    $letter
        ->create()
        ->send();

} catch (GuzzleHttp\Exception\ClientException $e) {
    $errorInformation = \GuzzleHttp\json_decode($e->getResponse()->getBody());
}

获取邮资信息

如果您想知道信件将有多贵。

情况1：您已经定义了一个带有信封等的信件

$priceInformation = $letter->queryPriceInformation();

var_dump($priceInformation);

情况2：您需要提供PostageInfo

$postageInfo = new Richardhj\EPost\Api\Metadata\PostageInfo();
$postageInfo
    ->setLetterTypeHybrid()
    ->setLetterSize(3)
    ->setDeliveryOptions($deliveryOptions);
    
$letter = new Richardhj\EPost\Api\Letter();
$letter->setPostageInfo($postageInfo);
$priceInformation = $letter->queryPriceInformation();

var_dump($priceInformation);

删除信件

如果您已经有一个Letter实例，删除非常简单

$letter
    ->create() // Yeah, it must be created beforehand, so we have a "letterId"
    ->delete();

否则，您需要知道letterId。

$letter = new EPost\Api\Letter();
$letter
    ->setLetterId('asdf-124-asdf')
    ->delete();

delete()将不可恢复地在E-POST门户上删除信件。您可以使用moveToTrash()来替代。

许可

GNU Lesser General Public License (LGPL)。

贡献

请遵循Symfony编码标准。

示例概念

此概念解释了在CMS Contao中用于E-POSTBUSINESS集成的各种组件。