atix-internetmarke

internetmarke

A node wrapper for the Internetmarke web service of the Deutsche Post

Installation

npm i internetmarke

Required accounts

To use the module you have to request a partner account from Deutsche Post for every web service you want to use and your payment account:

• 1C4A (One Click For Application, required!) is used to order vouchers.

  You can get the partner account from the website of Deutsche Post or via mail: [e-mail]

• Prod WS (Product List Web Service) is used to retrieve the list of available products (the distinct types of stamps for different dimensions etc.). This is optional if you know the ids and prices of the vouchers you want to order.

  The client account can be requested via mail (see above) only.

• Further you need your personal Portokasse account with payment info that is used on checkout. If you do not have one please create one at the web portal of Deutsche Post

Basic usage

Declare partner

Init the internetmarke object with your partner credentials. You can request them on the page of the Deutsche Post.

const factory = require('internetmarke').factory;
 
const partner = factory.createPartner({
  id: 'PARTNER_ID',
  secret: 'SCHLUESSEL_DPWN_MARKTPLATZ'
});

If your keyPhase is different that 1 please add it to the factory method.

Create internetmarke instance

You can do so by handing the created partner to the Internetmarke constructor. This will connect you to the 1C4A service.

const Internetmarke = require('internetmarke');
 
const internermarke = new Internetmarke(partner);

Authenticate user

Once the partner credentials have been set, you can login with your user account that should be used for the payment.

const user = factory.createUser({
  username: '[e-mail]',
  password: '*****'
});
internetmarke.authenticateUser(user)
  .then(success => {
    // user is authenticated
  });

The user holds all the information about your account including your wallet balance, which you can retrieve with user.getBalance() as soon as you authenticated the user. The user is passed by reference along the process so you can keep track of the balance with your instance after every checkout.

In addition you can retrieve the order id of the latest order in this session with user.getOrderId().

Product list

The product list contains all available vouchers that can be ordered. They are cached and are get updated once a day. To access the product service (Prod WS) a dedicated client account is necessary!

const client = factory.createClient({
  username: 'USERNAME',
  password: '********'
});

If your id (Mandant-ID) differs from the upper case version of the username you can add it to the factory method.

To enable the product service hand your client account to the internetmarke instance.

internetmarke.enableProductService({ client })
  .then(success => {
    // you can now access the product list
  });

Once the product service is enable you can retrieve the whole product list or a single product.

internetmarke.getProductList()
  .then(productList => {
    // array of products
  });
 
internetmarke.findProduct({ id: 1})
  .then(product => {
    // product.getId() contains the id used to order a voucher
    // product.getName() is the readable name of the product
    // product.getPrice() contains the price in Euro Cents
  });

You can get the minimal and maximal dimensions and weight informations of every product with the properties _dimensions and _weight. This will be used to match a product with given packet information to retrieve the best fitting product.

Order vouchers

As soon as the user has been authenticated you can start ordering vouchers. You can set the productCode and the voucherLayout (Default is Address Zone) for every single voucher.

To determine the right voucher, you can use the product list.

internetmarke.orderVoucher({ product });

If you do not have a product from the product service you can use productCode and price instead to order a voucher.

Voucher preview

You can create a preview voucher before checkout.

internetmarke.getVoucherPreview({ product })
  .then({ link } => {
    // link to the deutsche post service that contains the preview image for the product
  });

Of course you can also use productCode instead of the product here.

Checkout

Once done, you can proceed with the checkout which will buy the vouchers and return the information including a link to the zip file.

internetmarke.checkout()
  .then(shoppingcart => {
    // shoppingcart.orderId
    // shoppingcart.link - contains the link to the zip archive
    // shoppingcart.vouchers[].id - used to regenerate the voucher
    // shoppingcart.vouchers[].trackingCode (depending on product)
  });

Retrieve older orders

Every order can be re-downloaded with their order id.

internetmarke.retrieveOrder({ orderId: 1234 })
  .then(shoppingcart => {
    // same structure as checkout
  });

Retrieve older orders

Every order can be re-downloaded with the order id.

internetmarke.retrieveOrder({ orderId: 1234 })
  .then(shoppingcart => {
 
  });

Add addresses to a voucher

Vouchers that are in AddressZone Layout can handle addresses. You can add a pair of sender / receiver addresses with the AddressFactory.

const sender = factory.createAddress({
  firstname: 'Max',
  lastname: 'Mustermann',
  street: 'Marienplatz',
  houseNo: 1,
  zip: 80331,
  city: 'München'
});
const receiver = factory.createAddress({
  company: 'Studio 42',
  firstname: 'John',
  lastname: 'Doe',
  street: 'Morningside Road',
  houseNo: 44,
  zip: 'EH10 4BF'
  city: 'Edinburgh'
  country: 'GBR'
});
const addressBinding = factory.bindAddresses({ receiver, sender});
 
internetmarke.orderVoucher({
  addressBinding
  /** further voucher info ... **/
});