richardhj / epost-api
E-POSTBUSINESS API PHP integration
Installs: 7 860
Dependents: 2
Suggesters: 0
Security: 0
Stars: 9
Watchers: 1
Forks: 4
Open Issues: 2
Requires
- php: ^7.0
- guzzlehttp/guzzle: ^6.0
- richardhj/oauth2-epost: *
Requires (Dev)
- phpunit/phpunit: ^6.3
This package is auto-updated.
Last update: 2020-09-10 11:22:05 UTC
README
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.