WEBSTAMP WEB SERVICE: SOAP - INTERFACE DESCRIPTION - Die Post
←
→
Page content transcription
If your browser does not render page correctly, please read the page content below
WEBSTAMP WEB SERVICE: SOAP INTERFACE DESCRIPTION Version V06.03 June 2019 1 WebStamp web service: SOAP
TABLE OF CONTENTS
1 Introduction 5
1.1 SOAP specification 5
1.2 Definition of terms 5
2 General 6
2.1 Encoding 6
2.2 Versions 6
2.3 Currently available versions 6
2.4 Adjustments when changing versions 6
2.5 Detailed description 7
2.6 WebStamp server 7
2.7 Access data 7
2.7.1 Application identification 7
2.7.2 User ID 7
2.7.3 Signed connection 8
3 Authentication 9
3.1 wsws_identification 9
4 Options 10
4.1 wsws_category 10
4.2 wsws_product 10
4.3 wsws_addition 11
4.4 wsws_media_type 11
4.5 wsws_media 12
4.6 wsws_zone 12
4.7 wsws_country 12
4.8 wsws_license 12
4.9 wsws_product_list 13
4.10 wsws_customer_data 13
2 WebStamp web service: SOAP5 Order 14
5.1 wsws_address 14
5.2 wsws_order 15
5.3 wsws_stamp 15
5.4 wsws_message 16
5.5 wsws_cash_on_delivery 16
5.6 wsws_custom_media 17
5.7 wsws_order_item 18
5.8 wsws_price_detail 18
5.9 wsws_consignments 18
6 Info 19
6.1 wsws_receipt 19
6.2 wsws_receipt_info 19
6.3 wsws_delivery_receipt 19
6.4 wsws_journals 20
6.5 wsws_journal 20
7 SOAP methods 21
7.1 Options 21
7.1.1 get_categories 21
7.1.2 get_products 21
7.1.3 get_media_types 22
7.1.4 get_medias 22
7.1.5 get_zones 22
7.1.6 get_countries 23
7.1.7 get_licenses 23
7.1.8 get_product_lists 24
7.1.9 get_customer_data 24
7.2 Order 25
7.2.1 new_order_preview 25
7.2.2 new_order 27
7.2.3 copy_order_by_id 29
7.2.4 previous_order 29
WebStamp web service: SOAP 37.3 Info 30
7.3.1 get_info_receipt 30
7.3.2 get_info_delivery_receipt 30
7.3.3 get_info_journal 30
8 Error handling 31
8.1 System error messages 31
8.2 Example response 36
9 Attachments 37
9.1 WSDL 37
9.2 Example call 37
9.2.1 Request 37
9.2.2 Response 38
10 Information for integrators 39
4 WebStamp web service: SOAP1 Introduction
The Web service WebStamp allows you to fully integrate WebStamp into another application.
The interface is available in the variant: SOAP.
1.1 SOAP specification
Detailed descriptions of each SOAP method, such as field data type, can be found in the WSWL and are not repeated in this document.
1.2 Definition of terms
Term Description
Customer A customer is a user of the WebStamp online service via the WebStamp web service or Webstamp light interfaces.
The customer must be registered with Swiss Post in order to use WebStamp.
Integrator, A company, organization or person who has connected WebStamp to their own platform using WebStamp web service
platform provider or Webstamp light.
Application ID, Each application identifies itself to WebStamp with a unique key:
provider number – WebStamp web service access uses the application ID
Customer Centre Log-in Various online services are grouped under the Swiss Post “Customer Center” and can be accessed with a single
username and password.
Only one centralized registration is required for the Swiss Post “Customer Center”, and this also allows you to use
“WebStamp”.
WS Abbreviations for “WebStamp”
WSWS Abbreviations for “WebStamp web service”
WebStamp web service: SOAP 52 General
2.1 Encoding
The character coding for SOAP communication is always UTF-8.
2.2 Versions
The interface is available in a range of versions. This allows for better delimitation of existing and older interface versions as the product
is developed. Over time, older versions will be discontinued by Swiss Post following prior notification of the end date.
Please ask for exact details of the versions when managing the WebStamp application.
The respective version numbers of the data fields are indicated in the tables. If there is no version number, they apply to all versions.
Where a version number is specified, it applies to the specified version and all subsequent versions. If multiple versions are specified,
the data field applies to the specified versions only.
Attempting to call a version that is no longer valid returns HTTP status code 410.
2.3 Currently available versions
V6 Current and maintained version.
V5 Available previous version. We recommend migrating to the latest version.
2.4 Adjustments when changing versions
Each time you update to a newer version, the URL must be adapted to the new version (see 2.7 Access data). New functions offered
as a part of an audit can be activated by updating the WSDL.
If the adjustment is not marked as mandatory, it provides additional functionality but is not necessarily required.
Version Audit Mandatory Description
V6 03 NO – Additional creation of labels in ZPL2 format
– Optional specification of resolution for receiving the labels (dpi)
– Ordering of WebStamp using printing service
– Processing of individual letters and mailshots
V6 02 NO – Checking and redeeming discount codes
– Detailed price information
V6 01 NO – International recipient addresses can now be submitted without a postcode (zip).
– Receipts can be obtained as XMLs
V5 Yes – Transition to new endpoints
– Review of all implemented SOAP methods
– Removal/migration of disabled WSWS functions (e.g. for parcels)
– Adjustment of SOAP fault handling
– Review of data structure names, which sometimes contained the API version
6 WebStamp web service: SOAP2.5 Detailed description
Default values are shown in italics in property lists.
2.6 WebStamp server
Two independent infrastructures are available for the connection.
https://wsredesignint1.post.ch Continuously expanded test environment for new releases of WebStamp.
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
2.7 Access data
The interface can be accessed using the following URL:
V6
/wsws/soap/v6 Identification with WS customer ID / web service password
V5
/wsws/soap/v5 Identification with WS customer ID / WSWS-Passwort
2.7.1 Application identification
An application ID is required for access by each application you want to connect to. This is assigned by Swiss Post.
2.7.2 User ID
The user must also be authenticated with a customer ID / WSWS-Passwort. The WS customer ID can be found on the WebStamp
homepage under WebStamp Settings / WebStamp web service. This page can also be used to store the WSWS password.
The identification using WS customer ID and WSB password must be transmitted with each request (except for the Options
interface).
Please note
For an order (request), the following three attributes must be transferred to WebStamp:
– Application ID
– WS customer ID
– WSWS password
WebStamp web service: SOAP 72.7.3 Signed connection In special cases, access can be implemented using signatures. In this case, Swiss Post issues a certificate to the integrator, which must be used to sign the connection (TLS) to WebStamp WebService. When using signed access, WebStamp only allows calls with a valid signature. Invalid or unknown signatures are rejected. For the connection, the host name for the WebStamp server is preceded by “cert.”. The following is an example of a signed call from a command line: curl https://cert.webstamp.post.ch/wsws/soap/v6 --cert certificate.pem:”*******” --data @soap-request.xml Please note The default method is identification of the user with WS customer ID and WSWS password without signing. Implementation with signing must always be agreed in advance with those responsible. If this method of identification is chosen, the system can be set so that the WSWS password does not have to be transmitted. 8 WebStamp web service: SOAP
3 Authentication
Each request to WebStamp must contain an identification container, which is used to authenticate the user.
The customer ID and WSWS password must be used to verify the user’s identity.
3.1 wsws_identification
Name Data type Description
application string Identification hash of the calling application.
language token Two-character language code. Determines the response language of the interface when texts are returned.
Possible values:
– de
– fr
– it
– en
[userid] string WS customer ID.
[password] string WSWS password.
[encryption_type] token Encryption of the WSWS-Passwort: md5 or sha1. If encryption_type is left empty or the attribute is not available,
the WSWS-Passwort is transmitted as plain text.
– md5
– sha1
– (Empty)
Empty or attribute hash type not available (WSWS-Passwort is transmitted in plain text)
WebStamp web service: SOAP 94 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).
Unless otherwise noted, all functions in the Options interface can also be queried without a username and WSWS-Passwort.
The application ID /provider number are sufficient.
4.1 wsws_category
Swiss Post products are grouped into product categories (e.g. domestic letters). The object wsws_category displays a product category
with the relevant details.
Name Data type Description
number int Unique product category ID.
name string Name of the product category.
recipient_mandatory boolean Determines whether the recipient’s address is mandatory or not.
valid_days int Product validity in days.
4.2 wsws_product
The object wsws_product contains a Swiss Post product with the relevant details.
Please note
–– Swiss Post recommends the use of “post_product_number” for product identification. This changes less often than “number”.
Regardless of which number is used, the integrator must recognize changed numbers in the application. The valid numbers are
available from the Options interface. It is recommended to check this from time to time and react accordingly in the event of
changes.
–– If a subsystem or subsystem/segment is specified for a product, a franking licence is required for the order (see section 4.8).
–– Product queries in the past are not supported.
10 WebStamp web service: SOAPName Data type Description
number int Unique ID for the product. Changes each time the product is changed.
category string Alias for the product category.
category_number int Unique category number. For the values allowed, see 4.1. wsws_category
post_product_number int Swiss Post number (level number for Swiss Post’s own applications).
Similar to the number attribute. Unlike the number attribute, the Swiss Post number does not always
change when a product is changed.
price float Price of the product, including VAT.
name string Name of the product.
additions array Array with wsws_addition objects.
delivery string Delivery type (e.g. A Mail, B Mail).
format string Format (e.g. standard letter, midi letter).
size_din string DIN ISO format (e.g. A4).
max_size_length int Maximum length in mm.
max_size_height int Maximum height in mm.
max_edge_length int Maximum total dimensions.
max_scale int Maximum scale (for bulky goods).
max_weight int Maximum weight in grams.
zone int Country zone
For the values allowed, see 4.6 wsws_zone
product_list string Name of the product range in the user’s language.
product_list_number int Number of the product range.
subsystem int Subsystem from which a franking licence is required.
segment int Segment that describes a franking licence uniquely in conjunction with the subsystem.
barcode boolean Indicates whether this is a letter with barcode (BMB) product. This information can be used to determine
the print medium.
4.3 wsws_addition
The object wsws_addition displays all supported value-added services for a product.
Name Data type Description
code string Optional addition code.
short_name string Addition short name.
4.4 wsws_media_type
The object wsws_media_type contains a print media type (e.g. labels, envelopes, etc.).
Name Data type Description
number int Unique ID of the media type.
name string Name of the media type.
image_possible boolean Indicates whether or not an image is allowed.
printservice_possible boolean Indicates whether the medium type for the WebStamp printing service can be used.
categories array An array with wsws_category objects. Specifies the category for which this media type is available.
WebStamp web service: SOAP 114.5 wsws_media
The object wsws_media contains a print medium (e.g. Zweckform 3659 label, C5 envelope, etc.).
Name Data type Description
number int Unique medium number.
name string Name of the medium.
type int Medium type. For the values allowed, see 4.4 wsws_media_type
4.6 wsws_zone
Swiss Post groups countries into a range of different zones. The object wsws_zone contains one of these zones.
Name Data type Description
number int Unique zone ID.
name string Name of the zone.
zone int 1: Zone 1 (Europe)
2: Zone 2 (remaining countries)
3: In Switzerland
4.7 wsws_country
The object wsws_country contains a country and its details. Countries return all known country codes and their names. The zone is
also included. The country name is used with a table of countries to evaluate the relevant zone.
Name Data type Description
alias string International country alias.
zone int Number of the corresponding zone. For the values allowed, see 4.6 wsws_zone
name string Country name (in full).
4.8 wsws_license
The object wsws_license displays the franking licence and the customer comments associated with it. Customers can identify their
franking licence using the combination of “number” and “comment” displayed to them. The “number” attribute is used for the
handover to the “new_order” method.
Please note
–– The WS customer ID and WSWS password are required to query the franking licence.
(If working with signing, see 2.7.3).
–– If a subsystem or subsystem/segment is specified for a product (see section 4.2), a franking licence is required for the order.
Name Data type Description
number string Customer’s franking licence (franking licence assigned by Swiss Post to the customer).
comment string Customer’s comments on the franking licence (can be left empty).
subsystem int Subsystem for mapping to products.
segment int The segment is used in conjunction with the subsystem.
12 WebStamp web service: SOAP4.9 wsws_product_list
Describes a queried product range.
Name Data type Description
number int ID of the product range.
name string Description of the product range.
customer_type token Customer type of the product range. (bc = business customers, pc = private customers)
4.10 wsws_customer_data
Describes basic billing data and the product range for a customer.
Name Data type Description
license_state string Status of the customer’s franking licence (FrL):
none Does not have own FrL
pending FrL application open
rejected FrL application rejected
ok Valid FrL
payment_type string Customer’s billing method:
prepaid In advance
kurepo Invoice customer
product_lists array Array of IDs of the customer’s product ranges.
WebStamp web service: SOAP 135 Order
All complex data types listed below belong to the actual order itself. They group together all the information required for an order or
define the response structure for an order.
5.1 wsws_address
The object wsws_address represents an address.
Name Data type Description
[organization] string Company or organization.
[company_addition] string Company suffix
[title] string Salutation
[firstname] string First name
[lastname] string Last name
[addition] string Additional details
[street] string Street, including number.
[pobox] string P.O. Box including optional number.
The P.O. Box number can be appended or the attribute “pobox_nr” can be transmitted.
[pobox_lang] string Language code for the P.O. Box:
de German (Postfach)
fr French (case postale)
it Italian (casella postale)
en English (P.O. Box)
The language code is only used if the attribute “pobox” is not specified.
[pobox_nr] string P.O. Box number
The number is only transferred if one of the attributes “pobox” or “pobox_lang” contains a valid value.
[zip] string Postcode
city string Town
[country] string Country code (default: ch) or name of the country.
These values are not case-sensitive.
[reference] string The reference transmitted here refers to the order and is returned in the order result.
It is used as the implementer’s own order reference. The value transmitted has no other function on the
WebStamp site. It is transmitted only by the request to the response.
[company_addition] string Additional details for companies and organizations.
[cash_on_delivery_amount] float COD charge for each recipient address for cash on delivery.
For floating point numbers, the amount must be rounded off for accounting purposes.
[cash_on_delivery_esr] string ISR reference number for each recipient address for cash on delivery with ISR.
[print_address] string Multiple line address for the recipient overprint. If transmitted, it is used instead of the individual fields.
14 WebStamp web service: SOAP5.2 wsws_order
The object wsws_order contains the order with the relevant details.
Name Data type Description
order_id int Unique order number.
print_data base64 If the order is a PDF or ZPL, which is ordered by specifying a print medium and with the attribute single
TRUE, the print data is outputted at order level. Otherwise, the individual print data is held in the stamps
container.
stamps array Array with wsws_stamp objects.
consignments array Array with wsws_consignments objects.
messages array Array with wsws_message objects.
reference string Reference value transmitted for the order. Used to identify the order to the integration software.
Has no other function in WebStamp, simply transmitted.
price float Total order price including VAT.
price_details array Array with wsws_price_detail objects.
item_price float Item price per product including VAT.
valid_days int Number of days until the postal prepayment impressions for the order become invalid.
valid_until dateTime Expiry date for the postal prepayment impressions in this order.
delivery_receipt base64 Delivery note as a PDF (if available).
product_number int Internal WebStamp product ID for this order that is effectively used.
post_product_number int Swiss Post product number for this order that is effectively used.
5.3 wsws_stamp
This object represents the actual postal prepayment impression with the relevant details.
Name Data type Description
stamp_id int Unique postal prepayment impression number.
tracking_number string For letters with barcode, the consignment number is returned for the Track & Trace system.
print_data base64 Individual postage paid impression per stamp. Is empty if the query was made by specifying a print
medium and using the single TRUE attribute.
compression token Image compression (gzip or empty).
mime_type string Mime type for franking.
image_width_mm int Width of the image in millimetres.
image_height_mm int Height of the image in millimetres.
image_width_px int Width of the image in pixels.
image_height_px int Height of the image in pixels.
reference string Reference value transmitted for the recipient’s address.
WebStamp web service: SOAP 155.4 wsws_message
wsws_message is used to send messages to the customer (for example new General Terms and Conditions).
Name Data type Description
message_type string The type indicates the type of message:
– announcement
– error
– confirm
customer_message string Message to be displayed to the user.
system_message string Technical message for the integrator.
system_message_code int Number of system_message.
url string Additional link if the message must be confirmed, for example in a web GUI.
confirm_until dateTime Date by which a message of the type “confirm” must be confirmed.
Messages of the type “confirm” contain important information and must be confirmed by the customer within a specified period
(for example new General Terms and Conditions). If the deadline expires, the customer cannot place any further orders until the
message is confirmed. The integrator must be capable of handling this functionality.
Messages of the type “announcement” do not need to be confirmed. This type is used to send important information for end
customers.
5.5 wsws_cash_on_delivery
This object contains the information for a COD order.
Name Data type Description
transaction_type token Account type for the beneficiary. ’post_bank’ or ’esr’ are supported.
esr_customer_ number int ISR participant number of the beneficiary for transaction_type ’esr’.
iban string IBAN of the beneficiary for transaction_type ’post_bank’.
beneficiary wsws_address Address information for the beneficiary for transaction_type ’post_bank’.
16 WebStamp web service: SOAP5.6 wsws_custom_media
This object is required to transmit a custom print medium. All dimensions are in mm.
Please note
–– The print area required for a label depends on a range of components (e.g. product selection, use of recipient addresses, use
of images, etc.). The minimum dimensions for the print area depend on how the various components are used.
For custom formats, a check is made to ensure that the minimum dimensions are available. If they are not, the print area is too
small and a message is output.
Name Data type Description
type enum – label
– envelope
– letter
– paper
page_width int Page width
page_height int Page height
[margin_top] int Top margin
[margin_bottom] int Bottom margin
[margin left] int Left margin
[margin right] int Right margin
[cols] int Labels per row (only for type=label)
[rows] int Labels per column (only for type=label)
[colspacing] int Bar width (only for type=label)
[rowspacing] int Bar height (only for type=label)
[recipient_orientation] enum Recipient orientation to one of the following points
– top/left
– top/right
– bottom/left
– bottom/right
[recipient_x] int Recipient position horizontal (only if type!=label)
[recipient_y] int Recipient position vertical (only if type!=label)
[sender_orientation] enum Sender orientation to one of the following points
– top/left
– top/right
– bottom/left
– bottom/right
[sender_x] int Sender position horizontal (only for type!=label)
[sender_y] int Sender position vertical (only for type!=label)
[franking_orientation] enum Franking orientation to one of the following points
– top/left
– top/right
– bottom/left
– bottom/right
[franking_x] int Franking position horizontal (only for type!=label)
[franking_y] int Franking position vertical (only for type!=label)
WebStamp web service: SOAP 175.7 wsws_order_item
The object contains the relevant information for a single postal prepayment impression.
Name Version Data type Description
stamp_id V6 int Unique ID of the postal prepayment impression.
label_number V6 int Serial number, which is printed on the postal prepayment impression.
tracking_number V6 string For letters with barcode, the consignment number is returned for the Track & Trace system.
5.8 wsws_price_detail
The object contains the price details per order. The sum of all amounts equals the total order amount.
This information is required if discount codes or additional services are offered.
Name Version Data type Description
type V6 enum The type of order item. The following values are possible:
–– webstamp: the order item of the WebStamp labels at list price (postage amount)
–– discount: the reduction granted when a discount code is redeemed
–– charge: a value-added service on the order which is not included on the price list
(e.g. printing service charges)
quantity V6 int The quantity of the order item.
amount V6 float The amount of the order item. When a discount code is used, a negative amount
will be returned.
description V6 string The description of the order item, e.g. the product name or the name of the
discount group.
5.9 wsws_consignments
Within an order of individual letters and mailshots, the object supplies information concerning the consignments found in the docu-
ment and their pages, and shows the allocation of consignments to stamps.
Name Version Data type Description
stamp_id V6 int Assigned label ID from the wsws_stamps objects
number V6 int Serial number per consignment
pages V6 array Array with page objects in which the pages of the consignment are present with a
serial page number.
window V6 string Position of the located recipient address in the transparent window:
left On the left-hand side of the window area
right On the right-hand side of the window area
state V6 string Consignment status:
valid The consignment is compatible with the used
product
invalid The consignment cannot be processed
reason V6 string If the status of a consignment is invalid, the reason for non-processing is returned.
18 WebStamp web service: SOAP6 Info
Information about past order processes can be obtained using the following complex data types.
6.1 wsws_receipt
This object contains the information for single or batch receipts. The data is returned by default in PDF format in the receipt
container. Alternatively, the data can be requested in a structured form using the get_info_receipt method and returned in the
receipt_info container.
Name Version Data type Description
order_id int Unique ID for the order.
receipt base64 Receipt as PDF. Returned empty if the output for the request is requested in xml format.
receipt_info V6 array Array of wsws_receipt_info objects, hence receipt data for the order. Returned empty
if the output for the request is requested in xml format.
6.2 wsws_receipt_info
This object contains the detailed information including the order items for a receipt..
Name Version Data type Description
address V6 wsws_address The billing address for the receipt.
journal V6 wsws_journal Summary order data.
product V6 wsws_product The product used for the order.
order_items V6 array Array of wsws_order_item objects.
6.3 wsws_delivery_receipt
This object contains the online delivery note.
Name Data type Description
order_id int Unique ID for the order.
delivery_receipt base64 Delivery note as PDF.
WebStamp web service: SOAP 196.4 wsws_journals The journal contains the details of past orders. It can be ordered with restrictions on type (order via interface, order via GUI) and using a date horizon. Name Data type Description journals array Array with wsws_journal objects. Returned empty if the output for the request is requested in url format. messages int Array with wsws_message objects if the journal is requested in url format. 6.5 wsws_journal In this object, the summary information for a previous order is returned. Name Data type Description date dateTime Date of order. order_id int Unique ID for the order. quantity int Number of postal prepayment impressions. price float Item price including VAT. total_price float Total price including VAT. valid_until dateTime Date up to which the order is valid. order_comment string The order note saved with the order. 20 WebStamp web service: SOAP
7 SOAP methods
7.1 Options
The options request can be used to query all options available in WebStamp web service. A separate SOAP method is available for
each option group. To query all options, all SOAP methods must be called up. It is recommended to store the options locally and
query them only occasionally.
The timestamp and categories parameters is always optional. If they are not transmitted, the current time is assumed for timestamp
and all available categories are assumed.
7.1.1 get_categories
Returns all supported categories.
Parameters
Name Data type Description
identification wsws_identification Identification object.
Return
Name Level Description
categories array Array with wsws_category objects.
7.1.2 get_products
Returns the available products. The data returned can be limited by product category and timestamp.
Parameters
Name Data type Description
identification wsws_identification Identification object.
[timestamp] dateTime Time of validity of the requested data. This can be used for example to query data in the future.
post_product_number int Internal Swiss Post product number.
customer_type token Customer type of the product range. (bc = business customers, pc = private customers)
product_lists array One or more product range numbers to limit the product search.
Return
Name Data type Description
products array Array with wsws_product objects.
WebStamp web service: SOAP 217.1.3 get_media_types
Returns the available media types. The data returned can be limited by product category and timestamp.
Parameters
Name Data type Description
identification wsws_identification Identification object.
[timestamp] dateTime Time of validity of the requested data. This can be used for example to query data in the future.
Return
Name Data type Description
media_types array Array with wsws_media_type objects.
7.1.4 get_medias
Returns the available media. The data returned can be limited by timestamp.
Parameters
Name Data type Description
identification wsws_identification Identification object.
[timestamp] dateTime Time of validity of the requested data. This can be used for example to query data in the future.
[type] int Restriction of the print media to one media type. The number of the media type is queried using
the get_media_types method.
Return
Name Data type Description
medias array Array with wsws_media objects.
7.1.5 get_zones
Returns the available country zones.
Parameters
Name Data type Description
identification wsws_identification Identification object.
Return
Name Data type Description
zones array An array with wsws_zone objects.
22 WebStamp web service: SOAP7.1.6 get_countries
Returns the available countries. The zone is also included. The country name is used with a table of countries to evaluate the relevant
zone.
Parameters
Name Data type Description
identification wsws_identification Identification object.
Return
Name Data type Description
countries array Array with wsws_country objects.
7.1.7 get_licenses
Business customers can now specify a personal franking licence for certain products. Franking licences allow the customer to order
certain additional products, and are also used for billing the order. Each franking licence can be used for one product type only.
It is not possible for the integrator to make this distinction – customers must select the appropriate franking licence themselves. Alter-
natively, a product number (type: post_product_number) can be specified in the franking licence query to limit the selection of
licences. Theoretically, a customer’s franking licences can change with every order, so they should be stored with care.
Parameters
Name Data type Description
identification wsws_identification Identification object.
[post_product_number] int Internal Swiss Post product number (level number)
Return
Name Data type Description
licenses array Array with wsws_license objects.
WebStamp web service: SOAP 237.1.8 get_product_lists Returns the various product ranges. The product ranges are divided into two main categories in WebStamp: “pk” (private customers – pc) and “gk”(business customers – bc), and there are further subdivisions in each category. A customer can be assigned to multiple product ranges, but only to one main category (pc or bc). By specifying customer_type, you can query the product ranges relevant for your users. If the parameter is transmitted empty, all product ranges are returned. If a valid user login is specified in the identification object, customer_type is ignored and the product ranges assigned to the cus- tomer are returned instead. Queried product range numbers can be included with get_products to limit the product query by range(s). All queries are limited to currently valid product ranges. Parameters Name Data type Description identification wsws_identification Identification object. [customer_type] token Customer type of the product range. (bc = business customers, pc = private customers) Return Name Data type Description product_lists array Array with wsws_product_list objects. 7.1.9 get_customer_data Provides basic information about a customer’s billing method and product ranges. This data is not confidential, so no customer pass- word is required. Parameters Name Data type Description identification wsws_identification Identification object. Here, the WS customer ID is mandatory, but the WSWS password is optional. Return Name Data type Description customer_data wsws_customer_data Customer data object. 24 WebStamp web service: SOAP
7.2 Order
Messages of the type «confirm» contain important information and must be confirmed by the customer within a specified period
(for example new General Terms and Conditions). If the deadline expires, the customer cannot place any further orders until the mes-
sage is confirmed. The integrator must be capable of handling this functionality.
7.2.1 new_order_preview
Returns a new order as a free preview.
Parameters
Name Data type Description
identification wsws_identification Identification object.
product int Number of the required product.
single boolean default: FALSE Determines whether the output is as a single file.
TRUE All postage paid impressions outputted to one file (single)
It is mandatory to specify a medium.
Only the file formats PDF and ZPL are supported.
The data is returned on the order level.
FALSE The postage paid impressions are outputted in
individual files (multiple)
The data is returned on the stamp level.
file_type token The parameter defines the desired file format for outputting the postage paid impressions:
- png
- gif
- bmp
- pdf
- zpl
[dpi] int Defines the resolution in dots per inch for the postage paid impressions. Values between 72 and
600 are permitted. If no resolution is specified, the labels will be generated with a resolution of
300 dpi.
[print_zone] token Defines where the postal prepayment impression is used, thereby determining the correct display.
1 Franking zone (as for stamp)
2 Address zone (for recipient’s address)
Specification allowed only for single=FALSE. If not specified, the appropriate print zone is selected
automatically.
[media] int ID of the required print medium.
[quantity] int Number of postal prepayment impressions to be created. If an address is transmitted, this parameter
is ignored.
[a_addresses] array Array with one or more wsws_address objects.
[sender] wsws_address A wsws_address object with the sender’s address.
[media_startpos] int default: 1 The start_pos attribute can be set if the medium is a label format and defines the start label.
Ignored for all other media.
[image] base64 Base64 (RFC 2045) embedded image for the postal prepayment impression.
The following formats are supported: GIF, PNG and JPG.
[document] base64 Base64 (RFC 2045) embedded PDF file with an individual letter or mailshot. The file must have at
least one recipient address in the window area of an envelope.
[printservice] boolean Determines whether the output via the printing service is verified for the preview:
Default: FALSE TRUE Calculates the additional costs of the printing service,
verifies the address of individual letters or mailshots.
In contrast to new_order, the preview returns
the documents to the customer for checking
FALSE The data is outputted as before and is processed
by the customer
[printservice_info] wsws_address The delivery address to which the WebStamp postage paid impressions created via the printing
service are sent. May only be used in conjunction with printservice TRUE.
Cannot be used for processing individual letters or mailshots.
WebStamp web service: SOAP 25[post_product] boolean / This parameter defines which product number is specified.
default: FALSE FALSE: WebStamp internal number
TRUE: Swiss Post number (level number, mostly for Swiss Post’s internal applications).
[reference] string The reference transmitted here refers to the order and is returned in the order result. It is used as
the implementer’s own order reference. The value transmitted has no other function on the
WebStamp site. It is transmitted only by the request to the response.
[order_comment] string An order note can be included with the order. This also appears in the WebStamp GUI and in the
journal.
[license_number] string Number of the franking licence.
[discount_code] string The discount code can be checked using the new_order_preview method. In the response, the
prices are returned with the reduction taken into account.
[cash_on_delivery_info] wsws_cash_on_delivery COD object with the relevant COD information.
[custom_media] wsws_custom_media Custom print medium.
Return
Name Data type Description
order wsws_order Order object.
WebStamp web service: SOAP 267.2.2 new_order
new_order can be used to make an order in WebStamp. Returns a new order.
Parameters
Name Data type Description
identification wsws_identification Identification object.
product int Number of the required product.
single boolean default: FALSE Determines whether the query result is a single file.
TRUE All postage paid impressions outputted to one file (single)
It is mandatory to specify a medium.
Only the file formats PDF and ZPL are supported.
The data is returned on the order level.
FALSE The postage paid impressions are outputted in
individual files (multiple)
The data is returned on the stamp level.
file_type token The parameter defines the desired file format for outputting the postage paid impressions:
- png
- gif
- bmp
- pdf
- zpl
[dpi] int Defines the resolution in dots per inch for the postage paid impressions. Values between 72 and
600 are permitted. If no resolution is specified, the labels will be generated with a resolution of
300 dpi.
[print_zone] int (1/2) Defines where the postal prepayment impression is used, thereby determining the correct display.
1 Franking zone (as for stamp)
2 Address zone (for recipient’s address)
Specification allowed only for single=FALSE. If not specified, the appropriate print zone is selected
automatically.
[media] int ID of the required print medium.
[quantity] int Number of postal prepayment impressions to be created. If an address is transmitted, this parameter
is ignored.
[a_addresses] array Array with the wsws_address object.
[sender] wsws_address Address object with the sender’s address.
[media_startpos] int default: 1 Position of the first label.
[image] base64 Base64 (RFC 2045) embedded image for the postal prepayment impression.
The following formats are supported: GIF, PNG and JPG.
[document] base64 Base64 (RFC 2045) embedded PDF file with an individual letter or mailshot. The file must have at
least one recipient address in the window area of an envelope.
[printservice] boolean default: FALSE Determines whether the output via the printing service is processed:
TRUE The WebStamp postage paid impressions or individual letters/
mailshots are forwarded to a print shop
and delivered in printed form.
FALSE The data is outputted as before and is processed
by the customer
[printservice_info] wsws_address The delivery address to which the WebStamp postage paid impressions created via the printing
service are sent. May only be used in conjunction with printservice TRUE.
Cannot be used for processing individual letters or mailshots.
[post_product] boolean / This parameter defines which product number is specified.
default: FALSE FALSE: WebStamp internal number
TRUE: Swiss Post number (level number, mostly for Swiss Post’s internal applications).
27 WebStamp web service: SOAP[reference] string The reference transmitted here refers to the order and is returned in the order result. It is used as
the implementer’s own order reference. The value transmitted has no other function on the
WebStamp site. It is transmitted only by the request to the response.
[order_comment] string An order note can be included with the order. This also appears in the WebStamp GUI and in the
journal.
[license_number] string Number of the franking licence.
[discount_code] string Discount code to use for this order.
[cash_on_delivery_info] wsws_cash_on_delivery COD object with the relevant COD information.
[custom_media] wsws_custom_media Custom print medium.
Return
Name Data type Description
order wsws_order Order object.
28 WebStamp web service: SOAP7.2.3 copy_order_by_id
Creates a new order with identical settings from a previous order ID. The method cannot be used if the last order concerned an indi-
vidual letter or mailshot.
Parameters
Name Data type Description
identification wsws_identification Identification object.
order_id int ID of a previous order.
[reference] string The reference transmitted here refers to the order and is returned in the order result. It is used as
the implementer’s own order reference. The value transmitted has no other function on the
WebStamp site. It is transmitted only by the request to the response.
[quantity] int The number of stamps to be created if different from the original order.
[order_comment] string The order note if different from the original order.
[file_type] token This parameter defines the output format:
- png
- gif
- bmp
- pdf
- zpl
Return
Name Data type Description
order wsws_order Order object.
7.2.4 previous_order
Returns the data from a previous order for reprinting.
Parameters
Name Data type Description
identification wsws_identification Identification object.
order_id int ID of a previous order.
stamp_id int ID of a postal prepayment impression from a previous order. Used to re-order an order (the entire
order) in which this postal prepayment impression was used.
Return
Name Data type Description
order wsws_order Order object.
WebStamp web service: SOAP 297.3 Info
7.3.1 get_info_receipt
Returns a single receipt for an order if an Order_ID was transmitted or a batch receipt for multiple orders if the start and end dates
were transmitted.
You can choose whether the information is returned as a PDF document or as XML.
Name Version Data type Description
[output] V6 token Specifies whether the output is returned as an XML response or as a PDF
document.
Possible values::
– pdf (default)
– xml
[label_number] V6 int Creates a receipt for an order which contains the corresponding postal prepayment
impression.
Return
Name Data type Description
information wsws_receipt Returns the receipt for a transmitted order ID or a batch receipt for the period entered.
7.3.2 get_info_delivery_receipt
Return
Name Data type Description
information wsws_delivery_receipt Returns the online delivery note for the order ID transmitted.
7.3.3 get_info_journal
Note
This method is no longer available in later versions of the API because the same data can be obtained in more detail using
the get_info_receipt method.
Return
Name Data type Description
information wsws_journals Returns a container with the journals as specified in the filter criteria in the request.
30 WebStamp web service: SOAP8 Error handling
Errors are returned as SoapFaults. The “get_error_codes” method can be used to query all supported error codes.
The error messages are as follows:
8.1 System error messages
Code Notification
2000 de: Die XML-Anfrage ist fehlerhaft.
fr: La requête XML est erronée.
it: La richiesta XML è errata.
en: The XML request contains errors.
2003 de: Die Empfängeradresse %address_nr% ist nicht vollständig oder zu lang.
fr: L’adresse du destinataire %address_nr% est incomplète ou trop longue.
it: : Indirizzo del destinatario %address_nr% è incompleto o troppo lungo.
en: The recipient address %address_nr% is incomplete or too long.
2004 de: Es können nur %max_stamps% Frankiervermerke pro Bestellung generiert werden.
fr: Seuls %max_stamps% timbres peuvent être générés par commande.
it: : È possibile generare solo %max_stamps% segni di affrancatura per ogni ordine.
en: A maximum of %max_stamps% postal prepayment impressions may be generated per order.
2006 de: Das ausgewählte Produkt ist nicht mehr verfügbar und wurde ersetzt.
fr: Le produit sélectionné n’est plus disponible et a été remplacé.
it: Il prodotto selezionato non è più disponibile ed è stato sostituito.
en: The selected product is no longer available and has been replaced.
2007 de: Bitte wählen Sie ein Druckmedium.
fr: Veuillez sélectionner un support d’impression.
it: Scegliere un supporto di stampa.
en: Please select a print medium.
2008 de: Das ausgewählte Druckmedium ist nicht mehr verfügbar und wurde ersetzt.
fr: Le support d’impression sélectionné n’est plus disponible et a été remplacé.
it: : Il supporto di stampa selezionato non è più disponibile ed è stato sostituito.
en: The print medium selected is no longer available and has been replaced.
2009 de: Bitte geben Sie die Anzahl ein.
fr: Veuillez indiquer la quantité.
it: : Indicare la quantità.
en: Please enter the quantity.
2012 de: Die maximale Bildgrösse von %bytes% Bytes wurde überschritten.
fr: La taille maximale de l’image (%bytes% octets) a été dépassée.
it: Le dimensioni massime dell’immagine (%bytes% Bytes) sono state superate.
en: The maximum image size of %bytes% bytes has been exceeded.
2015 de: Das Druckmedium wird mit den gewählten Optionen nicht unterstützt. Wählen Sie ein anderes Druckmedium oder ändern Sie die Auswahl.
fr: Le support d’impression n’est pas pris en charge avec les options sélectionnées. Veuillez choisir un support différent ou changer la sélection.
it: Il supporto di stampa non è supportato con le opzioni selezionate. Scegliere un supporto diverso o modificare la selezione.
en: The print medium is not supported with the selected options. Select another print medium or make a different selection.
2016 de: Eine Adresse kann mit dem ausgewählten Produkt nicht verwendet werden.
fr: Une adresse ne peut pas être utilisée avec le produit sélectionné.
it: Un indirizzo non può essere utilizzato con il prodotto selezionato.
en: An address cannot be used with the product selected.
2017 de: Für das gewählte Produkt sind Empfängeradressen erforderlich. Bitte erfassen Sie Ihre Adressen.
fr: Des adresses de destinataires sont requises pour le produit sélectionné. Veuillez saisir vos adresses.
it: Per il prodotto selezionato sono necessari degli indirizzi di destinatari. Inserire i vostri indirizzi.
en: Recipient addresses are required for the product selected. Please enter your addresses.
2022 de: Für dieses Produkt ist eine Absenderadresse erforderlich.
fr: Une adresse d’expéditeur est nécessaire pour ce produit.
it: Per questo prodotto è necessario l’indirizzo del mittente.
en: A sender’s address is required for this product.
WebStamp web service: SOAP 31Code Notification
2025 de: Bestehende Bestellungen mit belegloser Nachnahme und ESR-Referenznummern können nicht als Grundlage für weitere Bestellungen
verwendet werden. Bitte beginnen Sie eine neue Bestellung und erfassen Sie neue ESR-Referenznummern.
fr: Des commandes existantes avec des remboursements sans titre et numéro référence BVR sans document ne peuvent pas être utilisées
comme base pour d’autres commandes. Veuillez commencer une nouvelle commande et saisir un nouveau numéro de référence BVR.
it: Gli ordini esistenti con rimborso senza giustificato e numero di riferimento PVR non possono essere utilizzati come base per ulteriori
ordini. Iniziare un nuovo ordine e immettere un nuovo numero di riferimento PVR.
en: Existing orders with electronic cash on delivery and ISR reference numbers cannot be used as a basis for further orders. Please start a
new order and enter new ISR reference numbers.
2029 de: Die Frankierlizenz im verwendeten Auftrag ist nicht mehr verfügbar.
fr: La licence d’affranchissement correspondant à cet ordre n’est plus disponible.
it: La licenza di affrancatura relativa a questo ordine non è più disponibile.
en: The franking licence in the order used is no longer available.
2200 de: Der Auftrag wurde nicht gefunden.
fr: L’ordre n’a pas été trouvé.
it: L’ordine non è stato trovato.
en: The order has not been not found.
2202 de: WS-Kunden-ID, Passwort oder Applikations-ID sind ungültig.
fr: L’ID de client WS, le mot de passe ou l’ID de l’application ne sont pas valables.
it: L’ID del cliente WS, la password e l’ID dell’applicazione non sono validi.
en: WS customer ID, password or application ID are invalid.
2208 de: Das Dateiformat ist unbekannt und kann nicht verwendet werden.
fr: Le format de fichier est inconnu et ne peut pas être utilisé.
it: Il formato del file è sconosciuto e non può essere usato.
En: The file format is unknown and cannot be used.
2210 de: Adressen können nicht in die Frankierzone gedruckt werden.
fr: Les adresses ne peuvent pas être affranchies dans la zone d’affranchissement.
it: Gli indirizzi non possono essere stampati nello spazio per l’affrancatura.
en: Addresses cannot be printed in the franking area.
2211 de: Die Verwendung von Bildern in der Adresszone ist nicht möglich.
fr: L’utilisation d’images dans la zone d’adresse est impossible.
it: Utilizzo di immagini non è possibile nello spazio per l’indirizzo.
en: : The use of images in the address area is not supported.
2212 de: Der Ausgabetyp «Single» ist nur für Bestellungen mit PDF zulässig.
fr: Le type d’émission «Single» est autorisé seulement pour des commandes avec PDF.
it: Il tipo di emissione «Single» è consentito solo per ordini con PDF.
en: The “Single” issue type is only permitted for orders with PDF.
2216 de: Die Transaktion ist fehlgeschlagen. Die Bestellung wurde nicht ausgeführt.
Verwendung von Guthaben: Laden Sie Ihr Konto.
Verwendung von Rechnung: Versuchen Sie es bitte später noch einmal. Bei weiteren Problemen melden Sie sich beim Kundendienst.
fr: La transaction a échoué. La commande n’a pas été exécutée.
Utilisation d’avoirs: veuillez charger votre compte.
Utilisation de facture: veuillez essayer une nouvelle fois ultérieurement. Si les problèmes persistent, veuillez vous adresser au Service à la
clientèle.
it: La transazione non è riuscita. L’ordine non è stato eseguito.
Utilizzo del credito: caricare il conto.
Utilizzo della fattura: riprovare più tardi. In caso il problema persista, contattare il Servizio Clienti.
en: The transaction has failed. The order was not executed.
Use of credit balance: Top up your account.
Use of invoice: Please try again later. If you encounter further problems, please contact Customer Service.
2221 de: Das Feld «%field%» in der «%address%» ist ungültig.
fr: L’adresse de l’expéditeur n’est pas valable.
it: L’indirizzo del mittente non è valido.
en: : The “%field%” field in the “%address%” is invalid.
2223 de: Die Angabe eines Druckmediums ist im Ausgabetyp «Multiple» nicht möglich.
fr: L’indication d’un support d’impression est impossible dans le type de sortie «Multiple».
it: Nel tipo di emissione «Multiple» non è possibile indicare il supporto di stampa
en: Entering a print medium is not possible for the “Multiple” issue type.
2224 de: Das Produkt wurde nicht gefunden.
fr: Le produit n’a pas été trouvé.
it: Il prodotto non è stato trovato.
en: The product was not found.
32 WebStamp web service: SOAPCode Notification
2242 de: Ihre Angaben sind nicht bestätigt. Bitte führen Sie ein Login bei der Post durch (http://webstamp.post.ch/) und geben Sie die erhaltenen
Verifikationscodes ein.
fr: Vos données ne sont pas confirmées. Veuillez effectuer un login à la Poste (http://webstamp.post.ch/) et saisir le code de vérification que
vous avez reçu.
it: I vostri dati non sono confermati. Vi invitiamo a effettuare il login presso la Posta (http://webstamp.posta.ch/) e immettere i codici di verifica
ricevuti.
en: Your details are not confirmed. Please log in to Swiss Post (http://webstamp.post.ch/) and enter your verification code.
2243 de: Der Zugriff auf WebStamp ist nur für Benutzer mit Wohnsitz Schweiz oder Liechtenstein möglich.
fr: L’accès à WebStamp n’est possible qu’aux utilisateurs domiciliés en Suisse ou au Liechtenstein.
it: L’accesso a WebStamp è possibile solo per gli utenti residenti in Svizzera o nel Principato del Liechtenstein.
en: : Access to WebStamp is only possible for users resident in Switzerland or Liechtenstein.
2244 de: Für diese Bestellung wurde kein Lieferschein generiert. Lieferscheine werden nur für Produkte generiert, die einen Lieferschein erfordern.
fr: Aucun bulletin de livraison n’a été généré pour cette commande. Un bulletin de livraison n’est généré que pour les produits nécessitant un
bulletin de livraison.
it: Per questa ordinazione non è stato generato alcun bollettino di consegna. I bollettini di consegna vengono generati unicamente per i prodotti
che lo richiedono.
en: A delivery note has not been created for this order. Delivery notes are only generated for products that require a delivery note.
2247 de: Der Lieferschein für dieses Produkt ist nicht mehr verfügbar. Kontaktieren Sie bitte den Kundendienst.
fr: Le bulletin de livraison de ce produit n’est plus disponible. Veuillez prendre contact avec le Service à la clientèle.
it: Il bollettino di consegna per questo prodotto non è più disponibile. Si prega di contattare il Servizio clienti.
en: The delivery note for this product is no longer available. Please contact Customer Service.
2248 de: Der maximale Nachnahmebetrag für %country% ist CHF %max_value% (Mindestbetrag CHF 0.05).
fr: Le montant maximal du remboursement pour %country% est de %max_value% CHF (montant minimal 0.05 CHF).
it: L’importo massimo del rimborso per %country% è di CHF %max_value% (importo minimo CHF 0.05).
en: The maximum amount to be collected on delivery for %country% is CHF %max_value% (minimum amount: CHF 0.05).
2249 de: Die ESR-Referenznummer «%esr%» ist ungültig.
fr: Le numéro de référence «%esr%» n’est pas valable.
it: Il numero di riferimento PVR «%esr%» non è valido.
en: The ISR reference number “%esr%” is invalid.
2250 de: Der Nachnahmebetrag ist nicht korrekt.
Nachnahmebeträge müssen auf fünf Rappen genau erfasst werden. Verwenden Sie keine Sonderzeichen.
Korrigieren Sie den eingegebenen Betrag.
fr: Le montant du remboursement est incorrect.
Les montants des remboursements doivent être enregistrés à cinq centimes près. N’utilisez pas de signes spéciaux.
Veuillez corriger le montant indiqué.
it: L’importo del rimborso non è corretto.
Gli importi dei rimborsi devono essere arrotondati e registrati a cinque centesimi. Non utilizzare caratteri speciali.
Correggere l’importo inserito.
en: The amount to be collected on delivery is incorrect.
COD charges must be rounded off to five centimes. Do not use special characters.
Please correct the amount entered.
2251 de: Die IBAN-Nummer fehlt oder die Angaben zum Endbegünstigten sind nicht vollständig (Endbegünstigter und PLZ/Ort).
fr: Le numéro IBAN fait défaut ou les indications relatives au bénéficiaire final sont incomplètes (les coordonnées du bénéficiaire final,
le NPA et la localité).
it: Il numero IBAN manca o i dati relativi al beneficiario finale sono incompleti (beneficiario finale e NPA/località).
en: The IBAN number is missing or the information for the end beneficiaries is incomplete (end beneficiary and postcode/location).
2252 de: ESR-Teilnehmernummer fehlt oder ist ungültig.
fr: Le numéro d’adhérent BVR fait défaut ou n’est pas valable.
it: Il numero di aderente PVR manca o non è valido.
en: : ISR participant number is missing or invalid.
2253 de: Die IBAN-Nummer ist ungültig.
fr: Le numéro IBAN n’est pas valable.
it: Il numero IBAN non è valido.
En: The IBAN number is invalid.
2256 de: Der Nachnahmebetrag fehlt oder ist nicht möglich.
fr: Montant du remboursement absent ou impossible.
it: : L’mporto del rimborso manca o non è ammesso.
en: The amount to be collected on delivery is missing or not possible.
2257 de: Eine gültige Frankierlizenz ist erforderlich.
fr: Une licence valable d’affranchissement est requise.
it: È necessaria una licenza di affrancatura valida.
en: A valid franking licence is required.
WebStamp web service: SOAP 33You can also read
