WebStamp light

User navigation



Language navigation

WebStamp light

Close

    WebStamp light

    Version V04.00 – November 2019

    Change control

    This page shows the change status of this document. A new version is issued after each change.

    Version Revision Author Date
    V03.00 Company suffix added, as well as fundamental change to Options interface cleuenberger 03.03.11
    X03.01 Expanded GUI parameters and product information including hash pbieri 28.08.12
    V03.02 Final version imsengr 18.09.12
    V03.03 Adjustment on page 13 Gascher 24.10.13
    V03.04 Adjustment after integration into new KLP login Gascher 26.06.15
    V03.06 Redesign adjustments pbieri May 2017
    V04.00 WS Release 11/19 GascheR 28.11.19

    1. Introduction

    WebStamp offers a number of different access options (interfaces) for integrators. These access options allow you to query data and transfer orders. The following access options are available:

    • WebStamp light:
      this simple connection can be used to transfer order data. Order completion remains within WebStamp.
    • “WebStamp” web service:
      this more complex connection allows you to fully integrate WebStamp into another application.

    1.1 Purpose of this document

    This document explains how to operate a connection to WebStamp. It contains all the information relevant to testing the interface. For productive use, the access data is also required.

    1.2 Target audience

    This guide is intended for people with technical knowledge who want to connect WebStamp to an existing platform. A basic knowledge of XML (Extensible Markup Language) and the HTTP protocol is recommended.

    1.3 Notation

    Default values are shown in italics in property lists.

    1.4 WebStamp server

    Two independent infrastructures are available for the connection.

    Infrastrucure Description
    https://wsredesignint1.post.ch Continually extended test environment for new WebStamp releases.
    https://wsredesignint2.post.ch Stable test environment for new integrators or for test systems (production release level). This is the preferred platform for integrators.
    https://webstamp.post.ch/ Productive system

    1.5 System requirements

    1.5.1 Servers

    Because transmission is based on standard technology, WebStamp imposes no restrictions in terms of operating system and programming language.

    1.5.2 Client (web browser)

    The conditions are the same as for the online service.

    1.6 Requirements for use

    1.6.1 Platform

    Before connecting to WebStamp, you must obtain an application ID from Swiss Post. This is used to uniquely identify your requests. In the event of problems, the platform provider can be contacted at this number.

    1.6.2 Customer

    Customers who want to use WebStamp with an external platform must have a Customer Center Login. To successfully create the digital stamps, the customer must have a sufficient balance on his user account, or increase the balance accordingly during the order process.

    1.7 Settlement

    By default, settlement is by means of the credit available in Swiss Post Customer Center. On request, payment by monthly invoice can be arranged in some cases. This must be requested separately for each Swiss Post Customer Login account.

    1.8 Definition of terms

    Term Description
    Customer A customer is a user of the WebStamp online service who uses the service via the web interface, the “WebStamp” web service or WebStamp light.
    The customer must be registered with Swiss Post in order to use WebStamp. 
    Integrator, platform provider A company, organization or person who has connected WebStamp to their own platform using the “WebStamp” web service or WebStamp light.
    Application ID, provider number (supplier, supplier ID) Each application identifies itself to WebStamp with a unique key:
    - The “WebStamp” web service uses an application ID
    - WebStamp light uses the provider number (supplier)
    Customer Center Login Various online services are grouped under the Swiss Post “Customer Center” and can be accessed with a single username and password.
    Only one registration is required for the Swiss Post “Customer Center”, and this also allows you to use “WebStamp”.
    WS Abbreviations for the “WebStamp” online service
    WSL Abbreviations for “WebStamp light”

    1.9 Adjustments when changing versions

    The information provided here is intended for integrators that perform a version change for the connection

    Version Description
    X0205 With the release, the Member Services were converted to Swiss Post Customer Login. Functionally, posting was not changed. Only the method of posting has changed (see Overview).
    The following adjustments are required:
    - New URLs pointing to WebStamp. If the customer is already logged in (an active Swiss Post Customer Login session), there is no need to log in again every time.
    See 3.2 URL
    - Security parameters can be omitted. It is now possible to manage the language of the WebStamp homepage using parameters. The content of the homepage can be individually tailored to the integrator.
    See 3.3 Parameters
    - If product data is obtained via WSB, it must also be adjusted depending on the connected version.
    See 4 Options
    V0300 New features: franking licences, online delivery note, COD, adjustments to WSI conformity
    For use of the new products introduced with API 3 and the separation of private and business customers, additional information is required.
    X0301 The GUI tag can be used to display the order in WebStamp or WebStamp easy. 
    For display in WebStamp easy, the product name and additional name can also be transmitted. For security reasons, a hash must be created and submitted for the request.
    V0306 Adjustment of the endpoint
    The “gui” parameter, which allowed selection between WebStamp and WebStamp easy, is now omitted
    Product information is no longer shown
    V0400 Process type and target step can now be predefined
    Recording of goods content and customs information via the “goods” parameter
    Transmission of images as part of the XML file

    2. Overview

    2.1 Figure 1 (technical)

    2.2 Figure 2 (functional)

    2.3 Key for Figures 1/2

    Nr Description
    1 The platform provider implements a function that allows the customer to request one or more digital stamps.
    2 The platform provider’s server generates a new WS compliant XML request based on the client request. This must be packaged in a form and transferred to the client for transmission.
    3 The form is sent to WebStamp either directly (onload) or after confirmation by the customer.
    4 When logging in to the Customer Center, it checks whether the user is already logged in. If yes, the GUI page is displayed immediately (step 8).
    5 The customer logs in with an existing account or registers for a new account.
    6 After successfully logging in, the customer receives a Swiss Post Customer Login session.
    7 The customer is returned to WebStamp and logged in.
    8 If all the necessary data is not available, the customer must add the missing data step by step.
    In all cases, the customer lands on the overview page before generation of the digital stamps, where the order must be confirmed. 
    9 The credit balance in the Customer Center must be sufficient for the entire order to be processed. If the balance is not sufficient, the customer must first top up the account.
    10 The digital stamps are available to the customers in PDF format for download.

    3. Order

    3.1 Introduction

    A request of the type “order” initiates an order for the generation of digital stamps.

    3.2 URL

    The request is sent in accordance with the syntax specification to the following URLs:

    3.3 Parameters

    Transmission of the XML data to WebStamp (3) must be initiated by the browser using a client-side Swiss Post form. The query string is as follows:

    XMLPack=<XML encoded>&_lang=<language code>

    The following fields can be transmitted:

    Field Mandatory Description
    XMLPack Yes A Base 64 and URL-encoded XML structure is formulated in the request. 
    base64 encode(<XML>)
    URL encoding is done by the web browser.
    _lang No Language code for the WebStamp homepage
    de German
    fr French
    it Italian
    en English

    3.4 Transfer

    The HTML page with the form is generated by the platform provider’s server and sent to the client. Once the page is fully loaded, the browser sends the form to WebStamp.

    <html>
    	<body onload="ws.submit()">
    		<form name="ws" method="post" 
    		      action="https://webstamp.post.ch/">
    		<input type="hidden" name="XMLPack" value="...">
    		<input type="hidden" name="_lang" value="fr">
    		</form>
    	</body>
    </html>

    3.5 Data structure

    Each of the XML tags and their attributes are described in detail hereinafter. Optional tags and attributes do not have to be sent.

    Supplier

    To check permissions, the request from the platform must be identifiable.

    Day Mandatory Description
    Supplier Yes The application ID is assigned to the platform provider by Swiss Post.

    Process

    Using the optional tag, the order process can be defined and the target step can be predefined in the respective order process.

    Attribute Mandatory Description
    Type No webstamp WebStamp standard process
    sdm WebStamp for mailshots
    Video WebStamp with video
    targetstep No The number which is visible for each order step in the respective order process
    1 Product
    2 Image / PDF / video / customs information
    3 Sender address
    4 Recipient addresses
    5 Print options
    6 Order completion and payment
    The indicated target step is only achieved if all the required information is included in the order.

    Media

    The medium on which the digital stamps will be generated. When the medium is specified, a matching product must always be selected.

    Attribute Mandatory Description
    Editable No Editability of this setting during manual completion for the customer:
    yes ja
    no nein
    Number No Unique media number (can be read via the platform options). If an invalid value is entered, the “editable” property is always set to “yes”. Otherwise, the order cannot be completed.
    If the medium has been replaced in the meantime, WS automatically selects its replacement. A message to that effect is displayed for the user.

    Product

    The product definition is consistent for all digital stamps in an order.

    Attribute Mandatory Description
    Editable No Editability of this setting during manual completion for the customer:
    yes ja
    no nein
    Number No Unique product number (can be read via the platform options). If an invalid value is entered, the “editable” property is always set to “yes”. Otherwise, the order cannot be completed.
    If the product has been replaced in the meantime, WS automatically selects its replacement. A message to that effect is displayed for the user.
    Note:
    “post_number” must be used for product transfer. The use of “number” to transmit products is only available in consultation with Swiss Post.
    post_number No Swiss Post number (level no.). 
    Similar to the number attribute. Unlike the number attribute, the Swiss Post number does not always change when a product is changed.
    Note:
    Unless mutually agreed otherwise, this number must always be used for the transfer of products.
    Quantity No This attribute describes the number of digital stamps to be generated. If addresses are transmitted, the “quantity” attribute is ignored.
    Goods No The optional attribute enables you to define whether an international consignment should be created with the goods content.
    false Consignment only contains documents
    true Consignment with goods content
    Consignments with goods content enable customs information to be entered in step 2 of the order process.

    Image

    If an image is transmitted, it also appears on each digital stamp (where possible). The conventions are identical to those for manual upload.

    The check for whether an image has been modified since the last transfer is carried out in accordance with the HTTP/1.0 standard. ETAGS are also taken into account. The exact specification is available at the following URL:

    http://www.w3.org/Protocols/HTTP/1.0/spec#Code304

    http://www.w3.org/Protocols/HTTP/1.0/spec#If-Modified-Since

    Attribute Mandatory Description
    Editable No Editability of this setting during manual completion for the customer:
    yes ja
    no nein
    Note on transfer to WS:
    This parameter is ignored. 
    URL No If a URL is specified, the image is obtained from the corresponding server. If access to the image is password-protected, the following syntax can be used: http://Username:Password@host.tld/image
    Please inform us of the image path via webservice.webstamp@swisspost.ch so that we can add the corresponding URL to our whitelist, or transfer the image using the data attribute below.
    Data No A base 64-encoded image file in JPEG, PNG or GIF format can also be transmitted in the XML instead of a URL.

    Addresses

    The transfer of recipient addresses is optional. Instead of complete addresses, a quantity can also be defined under “product”.

    Day Type Description
    organization char (30) Company or organization
    company_addition char (35) Company suffix
    title char (30) Salutation
    firstname char (30) First name
    lastname char (30) Last name
    addition char (30) Additional details
    street char (30) Street including number
    pobox char (30) P.O. Box including optional number.
    The P.O. Box number can be appended or the attribute “pobox_nr” can be transmitted.
    pobox_lang char (2) Language code for the P.O. Box:
    de German (Postfach)
    fr French (case postale)
    it Italian (casella postale)
    en English (P.O. Box)
    These values are not case-sensitive.
    The language code is only used if the attribute “pobox” is not specified. When the language code is used, the term P.O. Box is printed in the respective language.
    pobox_nr char (30) P.O. Box number
    The number is only transferred if one of the attributes “pobox” or “pobox_lang” contains a valid value.
    zip char (10) Postcode
    city char (30) Town/city
    country char (100) Country code (default: ch) or name of the country.
    These values are not case-sensitive.

    If values longer than those defined in the type definitions are transmitted, they are truncated to the appropriate length without a suffix. A message to that effect is displayed for the customer after login.

    The sequence is the same as the positions in the XML document. If the quantity exceeds the maximum number, the excess addresses are removed. A message to that effect is displayed for the customer.

    Example

    <?xml version="1.0" encoding="ISO-8859-1"?>
    <wsp:platform-order>
    	<supplier>123456</supplier>
    	<product post_number="735142" />
    	<image url="http://www.nexbyte.com/logos/big.png" />
    	<addresses>
    		<address>
    			<organization>TheCompany AG</organization>
    			<company_addition>Abteilung Finanzen</company_addition>
    			<title>Herr</title>
    			<firstname>Hans</firstname>
    			<lastname>Muster</lastname>
    			<street>Hauptstr. 11b</street>
    			<pobox_nr>postfach 123</pobox_nr>
    			<zip>3600</zip>
    			<city>Thun</city>
    		</address>
    		<address>
    			<title>Frau</title>
    			<firstname>Elisabeth</firstname>
    			<lastname>Meier</lastname>
    			<street>Wieden 35</street>
    			<pobox_lang>DE</pobox_lang>
    			<pobox_nr>522</pobox_nr>
    			<zip>42659</zip>
    			<city>Solingen</city>
    			<country>DE</country>
    		</address>
    	</addresses>
    </wsp:platform-order>

    4. Options

    The Options interface returns all supported product information and its configuration. This makes it easy to integrate new WebStamp products into a third party application and to query changes to products (e.g. price changes). If the products are not kept up to date, problems can arise when products are changed (for example a message to the customer that a requested product is no longer available).

    All functions in the Options interface can also be queried without a username and password. The application ID/provider number are sufficient.

    The Options interface is described in the interface descriptions for the “WebStamp” web service. The interface is available as SOAP. Please request any documentation you may still require.