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('[email protected]', '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.