E-POSTBUSINESS API PHP integration

This package provides an PHP integration of the E-POSTBUSINESS API.

Install

Via Composer

$ composer require richardhj/epost-api

Usage

Authenticate user

First of all you have to fetch an AccessToken instance by authenticating the user. I recommend to use this OAuth2 Provider for fetching the access token.

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

Provide metadata

Envelope

We're going big steps forward and create a Letter instance. The Letter collects all metadata (envelope, delivery options…), creates a letter draft on the E-POST portal and finally sends the letter.

// 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');

Recipients

We created our envelope and we need to add the recipients. This is how for an electronic letter.

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

$envelope->addRecipientNormal($recipient);

And this is how for a printed letter. For printed letters, only one recipient is valid!

// 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);

Delivery options

We also define DeliveryOptions as they define whether the letter is going to be colored and so on. This is for printed letters only.

// 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);

Finishing

We're going to start the communication with the E-POST portal.

// 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());
}

Fetch postage info

If you wonder how expensive the letter is going to be.

Case 1: You already defined a letter with envelope and so on:

$priceInformation = $letter->queryPriceInformation();

var_dump($priceInformation);

Case 2: You need to provide 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);

Delete letters

If you already have a Letter instance, deleting is that easy:

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

Otherwise you need to know the letterId.

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

delete() will delete the letter irrecoverably on the E-POST portal. You have to possibility to use moveToTrash() otherwise.

License

The GNU Lesser General Public License (LGPL).

Contributing

Please follow the Symfony Coding Standards.

Beispiel-Konzept

Dieses Konzept erklärt die verschiedenen Komponenten, die im Rahmen einer E-POSTBUSINESS-Integration für das CMS Contao genutzt wurden.