Examples
All these examples assume that you have an instance of \baltpeter\Internetmarke\Service called $service which can be created like this:
// The `PartnerInformation` object is used to authenticate you as a partner with DPAG.
$partner_info = new \baltpeter\Internetmarke\PartnerInformation('ABCDEF', 1, 'secretkey');
// The `Service` object provides an interface for all actions in the web service
$service = new \baltpeter\Internetmarke\Service($partner_info);To authenticate a user, you need their username (which is their email address) and (plaintext) password for the Portokasse:
$user = $service->authenticateUser('portokasse@yourserver.tld', 'yourpassword');This will return a user object like this:
object(baltpeter\Internetmarke\User)#9 (4) {
["userToken":protected]=>
string(44) "secretkey"
["walletBalance":protected]=>
int(236725)
["showTermsAndConditions":protected]=>
bool(false)
["info_message":protected]=>
NULL
}To order a PDF stamp, you need to specify a page format ID. You can get a list of all available page formats by running the retrievePageFormats() function.
$formats = $service->retrievePageFormats();You will then get a long list of the valid page formats:
array(108) {
[0]=>
object(baltpeter\Internetmarke\PageFormat)#657 (7) {
["id":protected]=>
int(7)
["isAddressPossible":protected]=>
bool(true)
["isImagePossible":protected]=>
bool(false)
["name":protected]=>
string(31) "Herma 8748 CompactLine 105 x 74"
["description":protected]=>
string(31) "Herma 8748 CompactLine 105 x 74"
["pageType":protected]=>
string(9) "LABELPAGE"
["pageLayout":protected]=>
object(baltpeter\Internetmarke\PageLayout)#658 (5) {
["size":protected]=>
object(baltpeter\Internetmarke\Size)#659 (2) {
["x":protected]=>
float(148)
["y":protected]=>
float(210)
}
["orientation":protected]=>
string(9) "LANDSCAPE"
["labelSpacing":protected]=>
object(baltpeter\Internetmarke\LabelSpacing)#660 (2) {
["x":protected]=>
float(0)
["y":protected]=>
float(0)
}
["labelCount":protected]=>
object(baltpeter\Internetmarke\LabelCount)#661 (2) {
["labelX":protected]=>
int(2)
["labelY":protected]=>
int(2)
}
["margin":protected]=>
object(baltpeter\Internetmarke\Margin)#662 (4) {
["top":protected]=>
float(0)
["bottom":protected]=>
float(0)
["left":protected]=>
float(0)
["right":protected]=>
float(0)
}
}
}
[1]=>…
}The web service also allows you to generate a shop order ID. According to the documentation, this is meant for systems which cannot generate their own order IDs.
While you don't need to pass an order ID to the checkoutShoppingCart(Pdf|Png)() functions, it can still be useful to generate the ID in advance in case something goes wrong when receiving the response and you still want to access the order info (and most importantly, stamps).
To generate an order ID, you just need a userToken which you can get from authenticateUser().
$order_id = $service->createShopOrderId('secretkey');The function will return a string containing the order ID.
Deutsche Post provide a number of images that can be included in the stamp. In order to do so, you need an image ID. You can get a list of all available public images by running:
$public_gallery = $service->retrievePublicGallery();The function will return a long list of images:
array(359) {
[0]=>
object(baltpeter\Internetmarke\PublicGalleryItem)#1334 (4) {
["category":protected]=>
string(5) "Tiere"
["categoryDescription":protected]=>
string(5) "Tiere"
["categoryId":protected]=>
int(16)
["images":protected]=>
array(1) {
[0]=>
object(stdClass)#754 (4) {
["imageID"]=>
int(880956882)
["imageDescription"]=>
string(0) ""
["imageSlogan"]=>
string(0) ""
["links"]=>
object(stdClass)#755 (2) {
["link"]=>
string(69) "https://internetmarke.deutschepost.de/PcfExtensionWeb/image/880956882"
["linkThumbnail"]=>
string(75) "https://internetmarke.deutschepost.de/PcfExtensionWeb/image/thumb/880956882"
}
}
}
}
[1]=>…
}Similarly, users can also have their own private gallery, which can be accessed by running the retrievePrivateGallery() function.
Once again, you need a userToken from the authenticateUser() function:
$private_gallery = $service->retrievePrivateGallery('secretkey');You can request (invalid) preview stamps for free. The functions for PDF and PNG are very similar, the only difference is that retrievePreviewVoucherPdf() requires the page format ID as an additional parameter. In this example, we will be generating PNG previews.
The function retrievePreviewVoucherPng() takes the following parameters:
-
$product_code: A product code for the type of stamp (a list of products is only available via the separate ProdWS service) -
$voucher_layout: The layout of the stamp (possible values: 'FrankingZone' and 'AddressZone') -
$image_id(optional): An image ID to include in the stamp (gotten fromretrievePublicGallery()orretrievePrivateGallery())
Running:
$preview_url = $service->retrievePreviewVoucherPng(11, 'FrankingZone', 255);…would get you a link to the following image:
As to be expected, this is the most complicated example. There are many different options available. To get a full overview of which options you can use, what to input to them and which ones are optional, please refer to the documentation supplied by DPAG.
As usual, the only difference between checkoutShoppingCartPdf() and checkoutShoppingCartPng() is the additional page_format_id argument the PDF function takes.
The following example should demonstrate most options that are available. Please note that running this function will actually deduct money from your Portokasse account.
Note: The $shop_order_id passed to checkoutShoppingCartPdf() ('12345678' in this example) has to be unique. Unless you absolutely need to, it is therefore not recommended to generate that yourself. Instead, either pass null or generate a value beforehand as explained under Generating a shop order ID.
$sender = new \baltpeter\Internetmarke\NamedAddress(
new \baltpeter\Internetmarke\Name(null, new \baltpeter\Internetmarke\CompanyName('Company', new \baltpeter\Internetmarke\PersonName('Salutation', 'Title', 'First', 'Last'))),
new \baltpeter\Internetmarke\Address('Additional', 'Street', 'House No', 'ZIP', 'City', 'Country')
);
$receiver = new \baltpeter\Internetmarke\NamedAddress(
new \baltpeter\Internetmarke\Name(new \baltpeter\Internetmarke\PersonName('Salutation', 'Title', 'First', 'Last'), null),
new \baltpeter\Internetmarke\Address('Additional', 'Street', 'House No', 'ZIP', 'City', 'Country')
);
$address_binding = new \baltpeter\Internetmarke\AddressBinding($sender, $receiver);
$order_item = new \baltpeter\Internetmarke\OrderItem(21, null, $address_binding, new \baltpeter\Internetmarke\Position(1, 1, 1), 'AddressZone');
$stamp = $service->checkoutShoppingCartPdf('secretusertoken', 1, array($order_item), 145, '12345678', null, true, 2);After running this, $stamp will be an object similar to this:
object(stdClass)#20 (4) {
["link"]=>
string(115) "https://internetmarke.deutschepost.de/PcfExtensionWeb/document?keyphase=0&data=abcdefghijklmonpqrstuvwxyz"
["manifestLink"]=>
string(111) "https://internetmarke.deutschepost.de/PcfExtensionWeb/document?keyphase=0&data=31415926535897932384626433"
["walletBallance"]=>
int(236510)
["shoppingCart"]=>
object(stdClass)#21 (2) {
["shopOrderId"]=>
string(8) "12345678"
["voucherList"]=>
object(stdClass)#22 (1) {
["voucher"]=>
array(1) {
[0]=>
object(stdClass)#23 (1) {
["voucherId"]=>
string(20) "A0011E78E1000001234D"
}
}
}
}
}Meanwhile, the generated stamp will look something like this:
You can retrieve the data (including the URL to the stamp) from a previous order if you have the order ID. You will also need a token for the user.
$order = $service->retrieveOrder('secretusertoken', '12345678');The result will be the same data as returned by the checkoutShoppingCart(Pdf|Png)() function.
You can also charge the Portokasse from your own application. We will create an HTML form that submits to the page where you can top-up the Portokasse. Thanks to @iwasherefirst2 for implementing this feature!
First, create an instance of the PortokasseCharge helper class. $success_url and $cancel_url are the URLs where the user will be redirected when the payment is done or cancelled respectively.
The $balance is the amount of money (in euro cents) that should be on the Portokasse after the payment. So for example, if there is currently 5.00 € on the Portokasse and we submit a balance of 2500, we will be asked to pay 20.00 €. Note that there is a minimum amount of 10.00 €.
$success_url = 'https://mydomain.tld/success.php';
$cancel_url = 'https://mydomain.tld/cancel.php';
$balance = 1000;
$pc = new \baltpeter\Internetmarke\PortokasseCharge($partner_info, $user_token, $success_url, $cancel_url, $balance);Using this helper, we can then create the form.
<form method="POST" action="https://portokasse.deutschepost.de/portokasse/marketplace/enter-app-payment">
<input type="hidden" name="PARTNER_ID" value="<?php echo $partner_info->getPartnerId(); ?>">
<input type="hidden" name="PARTNER_SIGNATURE" value="<?php echo $pc->getSignature(); ?>">
<input type="hidden" name="REQUEST_TIMESTAMP" value="<?php echo $pc->getRequestTimestamp(); ?>">
<input type="hidden" name="KEY_PHASE" value="<?php echo $partner_info->getKeyPhase(); ?>">
<input type="hidden" name="SUCCESS_URL" value="<?php echo $pc->getSuccessUrl(); ?>">
<input type="hidden" name="CANCEL_URL" value="<?php echo $pc->getCancelUrl(); ?>">
<input type="hidden" name="USER_TOKEN" value="<?php echo $pc->getUserToken(); ?>">
<input type="hidden" name="BALANCE" value="<?php echo $pc->getBalance(); ?>">
<input type="submit">
</form>Upon submitting, the user will be redirected to a page where they can submit the payment. Afterwards, they will either be redirected to the $success_url or $cancel_url.
Note: The request included the secret user token, so this form should not be exposed to end users.
