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

Authenticating a user

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
}

Retrieving available page formats

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]=>…
}

Generating a shop order ID

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.

Fetching the public or private image gallery

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, user's 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');

Fetching a preview stamp

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 from retrievePublicGallery or retrievePrivateGallery)

Running:

$preview_url = $service->retrievePreviewVoucherPng(11, 'FrankingZone', 255);

…would get you a link to the following image: