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.chTarget not accessible | Continually extended test environment for new WebStamp releases. |
| https://wsredesignint2.post.chTarget not accessible | 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:
- Production:
https://webstamp.post.ch/ - Integration 1:
https://wsredesignint1.post.ch/Target not accessible - Integration 2:
https://wsredesignint2.post.ch/Target not accessible
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:
https://www.w3.org/Protocols/HTTP/1.0/spec#Code304Target not accessible
https://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
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.