1.1 Who is this manual written for?

This manual is for business customers of Swiss Post who want to use the “Barcode” web service.

The “Barcode” web service can be used for the following basic services:

• Domestic parcel
• Swiss-Express “Moon”
• SameDay afternoon/evening
• VinoLog
• Direct parcel posting
• Letters with barcode (BMB) domestic:
• Registered (R)
• A Mail Plus
• Dispomail
• Dispomail Easy
• GCourt documents (GU)
• Debt collection documents (BU)
• A and B Mail letters with Electronic cash on delivery (BLN)
• Letters with barcode (BMB) international:
• Registered (R) international
• PRIORITY Plus

1.2 How is this manual structured?

• Section 1 “Introduction”: The first section provides an introduction to the “Barcode” web service
• Section 2 “Service specifications”: This section describes the uses and possible applications of the operations as well as the notification services of the “Barcode” web service (WSBC)
• Section 3 “Registration, homologation, support”: The registration procedure for the “Barcode” web service is described here.
• Section 4 “Technical specifications”: This section describes the services in detail (interface specification), the operations and results
• Section 5 “Appendix: ’Barcode’ web service interface”: Some resources for using the “Barcode” web service are described in this section.
• Section 6 “Further publications and useful links”: This section lists further publications and links
• Section 7 “Customer sheet for homologation of Parcel, Express, VinoLog and Direct delivery consignments”: This section provides the customer sheets for homologation of the address label, which is to be submitted together with the address label.

1.3 Validity

For each new version of the “Barcode” web service, a new version of this manual will be issued and made available to customers in electronic form.

These instructions are valid from September 2023. They replace the version dated April 2021. Changes are possible in the event of extension or adaptation of Swiss Post’s service offering.

We have marked all sections with changes to content with a line at the margin.

1.4 Cost

Post CH Ltd’s “Barcode” web service is provided free of charge.

1.5 Conditions of use

The “Barcode” web service is intended solely for generating labels and for obtaining service, additional service and delivery instruction lists.

1.6 Subscriber Conditions

The Subscriber Conditions for the “Barcode” web service form an integral part of the current service manual. You will receive these at the latest when you register for the “Barcode” web service. Section 6 provides a direct link to the Subscriber Conditions.

1.7 Contact point for technical questions / Customer Service

Technical enquiries

Post CHLtd

Digital customer interfaces

Wankdorfallee 4

3030 Bern

digitalintegration@swisspost.ch

www.swisspost.ch/webservice-barcode

General enquiries

Post CH Ltd

Swiss Post Contact Center

Wankdorfallee 4

3030 Bern

Telefon +41 848 888 888

(CHF 0.08/Min. from landline phones within Switzerland)

www.swisspost.ch/contact

1.8 Acronyms and definitions

Examples

The most important functions of the “Barcode” web service at a glance:

• Generation of barcodes for which the user is authorized
• As a label without the recipient’s address
• As a complete shipping label incl. sender’s address (text or logo) and delivery address
• As an address component for a standard envelope with window 100 × 45 mm
• Generation of single barcodes (without address label) for Letters with barcode (BMB) domestic
• Validate access to web service
• Obtain all offered service groups, basic services, additional services and delivery instructions as a list
• Validate the combinations of selected services
• Forward all relevant consignment and delivery data to DataTransfer (with the exception of Letters with barcode [BMB] domestic and international)

Other benefits

Your benefits:

• Pull barcodes directly from your system ➞ you stay in your familiar user environment
• No separate programming of barcodes required ➞ no need to acquire specialist postal knowledge
• Round-the-clock access to latest postal services ➞ no worries about maintaining your barcode database
• High availability, high performance ➞ also suitable for high mailing volumes
• Simplify your dispatch process ➞ save money thanks to optimization of parcel and letter handling process
• Web service is free ➞ only investment is for linking up the “Barcode” web service to your system
• No shipping labels required if integrated in delivery note or as address component for envelope with window ➞ cost savings on labels¹⁾
• Order data can be directly linked to dispatch data ➞ all the information from the order no. through to the consignment no. at your fingertips¹⁾
• Fast consignment tracking, preferably combined with “Track consignments” web service ➞ check the current processing status at any time¹⁾

The “Barcode” web service provides address labels with Swiss Post barcodes in a machine-readable format (XML). You can choose between

• a label with the recipient’s and the customer’s address (or logo)
• a label with only the recipient’s address
• a label without the sender’s and recipient’s address, i.e. only the actual service barcodes and additional service barcodes
• single barcodes for basic and additional services in respect of Letters with barcode (BMB) domestic (for positioning barcodes yourself in documents or on address labels)

1) Not part of “Barcode” web service, must be programmed separately in your system if required

Please note that a separate data transfer link is required for Letters with barcode (BMB). This is because the delivery note for the posting can only be created once the physical mailing (daily closing) has been prepared. Information on this can be found at www.swisspost.ch/post-datatransfer-cug. You also have the option of purchasing barcodes for stock.

2.1 Short description of operations

You can link the consignment information with order data in your system. The “Barcode” web service allows you to purchase all basic services described in section 4.5, additional services and delivery instructions as a product list. The “Barcode” web service will always offer you the most up-to-date basic services and the associated additional services and delivery instructions. This service is described under the read operations in sections 5.6 to 5.10.

We also offer a service which validates the combinations of basic services with the additional services and delivery instructions. This ”Validate Combination” service is described in section 5.2

In the case of the Domestic Parcels, Express and Solutions service groups you have the option of printing the address label as a shipping label and affixing it to the item, or incorporating the label in your delivery note for use as a label in a document pouch. 

The address labels are available in various layouts, printer resolutions (dpi) and image formats/printer languages. These are described in sections 4.5 to 4.8.

2.1.1 Operation “Validate combination”

With the “Validate combination” operation, you have the option of testing the validity of the combination before running the “Generate address label” operation. This in turn enables you to test basic services in combination with additional services or delivery instructions or to test the compatibility of additional services and delivery instructions.

Together with the read operations, you can therefore show dynamically to users the basic and additional services/delivery instructions functions applicable to them only, which they can perform based on their frequently selected options.

2.1.2 Operation “Generate address label”

The “Generate address label” function is the primary function of the “Barcode” web service. By way of support, you can download web service XSD schema and sample files with technical details on the “Barcode” web service website: www.swisspost.ch/post-barcode-cug.

With the “Generate address label” request, the combinations of selected basic and additional services/delivery instructions will be tested automatically, whether or not you have already done this yourself beforehand. With the “Generate address label” operation, the mailing data (e.g. COD amount) is also validated. 

For the “Parcels”, “Express” and “Solutions” service groups, the mailing data is automatically transferred to DataTransfer. This means that you receive the same benefits as you would under DataTransfer.

2.1.3 Operation “Generate single barcodes”

Operation “Generate single barcodes” only applies to letters with barcodes. In the request, all selected basic and additional services are defined; as response you receive all barcodes individually as graphics, which you can then position in your address label yourself using the design and placement instructions

2.1.4 Operation “Generate barcodes”

Letter customers who create the delivery note online (LSO) themselves can use this operation to obtain the barcode required for the delivery note number.

2.1.5 Operation “Read basic services of a franking licence”

With this operation, you can request all basic services included in a franking licence number. This can be very helpful when using different franking licence numbers and service groups (e.g. Parcels domestic, Letter with barcode [BMB] international, etc.) in ensuring that the correct franking licence number is used.

2.1.6 Operation “Read service groups”

The “Read service groups” operation allows you to query all valid service groups offered by the “Barcode” web service (e.g. Parcel, Express, Letters with barcode domestic). The results form the basis of other read operation queries. This allows you to convert the dynamic views of available services options. 

2.1.7 Operation “Read basic services”

The “Read service groups” operation allows you to query all valid basic services offered by the “Barcode” web service (e.g. PostPac Priority, Swiss-Express “Moon”, Registered [R] domestic) with an available service group. The results form the basis of other read operation queries. This allows you to convert the dynamic views of available services options.

2.1.8 Operation “Read additional services”

The “Read additional services” operation allows you to query all valid additional services offered by the “Barcode” web service (e.g. Signature, electronic COD, Fragile) with an available basic service. The results form the basis of other read operation queries. This allows you to convert the dynamic views of available services options.

2.1.9 Operation “Read delivery instructions” 

The “Read delivery instructions” operation allows you to query all valid delivery instructions offered by the “Barcode” web service (e.g. ZAW3211) with an available basic service.

2.1.10 Operation “Read presentation types”

The “Read presentation types” allows you to query all valid presentation types offered by the “Barcode” web service (e.g. A6, window). What basic services and how many additional services or delivery instructions can be selected, depending on the size, are defined for each presentation type.

2.2 E-mail notification service for Parcels, Express and Solutions

You can arrange for your recipient customer to receive updates via e-mail on the tracking status of a mail item, or specify that you receive delivery confirmation of each mail item, thus ensuring you are immediately informed that the item has been delivered. The notification service is available for mail items in the Parcels, Express (without SameDay afternoon/evening and SameDay afternoon/evening bulky goods) and Solutions service groups (no “delivery information” with VinoLog). The above gives you five different services to choose from. Technical information on notification services is described in section 5.3.1.2. Please contact your Swisspost customer advisor for the wording of e-mail messages and the instructions on free text.

“Order confirmation” notification

With this service, you inform your recipient that you have handed over the mail item to Post CH Ltd. With this notification service, Post CH Ltd gives no guarantee that it has actually accepted the item (i.e. Post CH Ltd cannot confirm at the time of sending the message whether the item has been accepted).

The notification message is sent as soon the data transfer has been concluded. You can add personal free text for your messages.

“Delivery information” message

With this service, the recipient is advised of an upcoming delivery. The message is triggered by sorting information from the sorting centre. Based on this data, the delivery date can be estimated and the recipient advised accordingly. You can choose between standard text or personal free text for your message.

“Collection information” message

This service is designed for those recipients who collect their mail items from a Post Office (P.O. Box or poste restante). This notification dispels uncertainty as to whether the item is ready for collection or not. The message is triggered by delivery of the item to the relevant post office

“Reminder to recipient” message

This service entails the recipient receiving a message that the parcel has not yet been collected. This reminder message is triggered when initial delivery of the item to the recipient was not possible and is sent as a collection advice notifying the customer that an item has not been collected within three days of arrival at the respective post office. This service is provided when you enter the data, but is only triggered if the above situation occurs.

“Handover status to sender” message

As soon as the item has been delivered or a delivery attempt has been made, you or the e-mail recipient specified in the data file will receive an e-mail. This means that you are proactively informed as soon as a delivery or attempted delivery has been made. In the event of an attempted delivery, you will receive a second message as soon as delivery occurs within the following ten days.

“Exchange/return” delivery notification (delivery notification ZAW3233)

With the “Exchange/return” delivery notification, we are able to offer a simple, standardised service for the exchange or return of goods sent to your customers. This involves your customer receiving advanced notice via a standard Swiss Post e-mail message regarding this exchange or return. This process enables your customers to receive good quality.

For more information on the “Exchange/return” delivery notification, please contact your Customer Advisor.

“Saturday delivery” notification

You can use the additional service “SA” (Saturday delivery) to inform the recipient by e-mail about the scheduled delivery on the next Saturday. The standard notification (free text is not supported) is triggered after data transmission.

2.2.1 Overview of notification services

Notification services are currently available for the following DLG Parcel, Express and Solutions services.

1) Notification services cannot be used for basic services with business reply labels

3.1 Registration

Registration for and activation of the “Barcode” web service (WSBC) is carried out in the following steps:

3.1.1 Registration and activation of “Barcode” web service

To register for the “Barcode” web service, please contact your customer advisor.

Once the “Barcode” web service has been activated, you will receive an e-mail from Digital Integration with the access data for calling up the WSBC (technical user name, password, franking licence numbers) and links for downloading useful files.

3.1.2 Access data

The “Barcode” web service is protected from unauthorized access by a special account (known as a “technical user”) with a user name and password. You can also control specific access rights for the web service from this account.

Digital Integration will manage the access data and communicate it to you. If you require a new password or an additional technical user name, please contact Digital Integration.

3.1.3 Optional homologation

Post CH Ltd offers customers the option of a homologation for shipping labels. If you would like a homologation, please follow the steps described below.

The optional homologation process is as follows:

• Create five sample addresses with integrated barcode on the original label
• Send the sample addresses directly to one of the addresses below. For homologation of Parcel, Express items or Solutions (Direct parcel posting, VinoLog), you also send the completed customer sheet, as detailed in section 7, Appendix 1
• The Centre of Excellence for Packaging and Address Quality or your contact person letter barcodes will check the design
• If any of the requirements are not met, Swiss Post will contact you to discuss the corrections that need to be made and the next steps to take
• Once the labels have been approved, the Parcel Quality CoE will also notify “Barcode” Digital Integration staff directly, who will then activate the “Barcode” web service for generating production labels
• Support staff will also notify you by e mail when the “Barcode” web service has been activated for you. You can then use the “Barcode” web service in its entirety

The following is recommended to help you achieve the quality required for homologation quickly:

• The size of the address label conforms to the dimensions specified
• Good print contrast
• Good quality paper is used for mail items, in order to obtain a clean, well-defined print-out
• The printer is set to Normal mode (i.e. not Economy mode with “low toner”)

If the print quality of the address labels is unsatisfactory, Post CH Ltd will have the right to deactivate the “Barcode” web service. However, the customer will always be notified of the inadequate quality first. Labels may only be printed with the defined printer resolutions and print formats.

3.1.4 Integration of the consignment barcode in dispatch documents

When integrating the address label into a dispatch document (e.g. delivery note), please note the following, which applies to the Parcels, Express and Solutions service groups:

Size of address label

The dimensions of the graphics supplied by “Barcode” web services must not be changed:

A5: 148 mm × 210 mm

A6: 105 mm × 148 mm

A7: 74 mm × 105 mm

The size of the consignment barcode must keep within the following measurements:

Length: 68,0 to bis 69,0 mm

Height: 22,8 to bis 23,2 mm

White space

Between the mailing barcode and the left edge of the document, a white space of at least 8 mm must be observed. There must be at least 10 mm of white space all around the recipient address.

Position of the sender

If you insert the sender’s details yourself, ensure that they are positioned on the left hand side of the mailing barcode within the document. In addition, the sender’s details should not appear lower than the last line of the recipient’s address, where the sender’s details are not vertically aligned. (This applies only to “Parcels”, “Express” and “Solutions”.) 

Centre of excellence for Domestic Parcels, Express and Solutions

Contact for Letters with barcode (BMB) domestic and international barcodes

3.1.5 Support

If you have any questions about the “Barcode” web service, please contact your Swiss Post customer advisor or, for technical support, contact Digital Integration.

3.1.6 Termination

If you no longer wish to use the “Barcode” web service, please send an e-mail to Digital Integration providing the reason for your cancellation, the time of deactivation and the relevant franking licence numbers: digitalintegration@post.ch.

4.1 Description of the service

A description of the “Barcode” web service can be found in the WSDL file: www.swisspost.ch/post-barcode-cug.htm

You can perform tests with the XSD schema: www.swisspost.ch/post-barcode-cug.htm

You will require a technical user to call the “Barcode” web service (see section 3.1.2). The user name and password must be communicated with “Basic Authentication” when you call the web service.

To help you with your programming, you can also obtain instructions on access with PHP with examples as PHP sources and a Client API user manual with library for Java and C#/.Net from: www.swisspost.ch/post-barcode-cug.

Sample requests in XML for the various operations can be found at www.swisspost.ch/post-barcode-cug.

4.2 Endpoint address for “Barcode” web service

Swiss Post environment for producing labels:

Endpoint: https://wsbc.post.ch/wsbc/barcode/v2_4

Username: will be sent to you by Digital Integration

Password: will be sent to you by Digital Integration

4.3 Scheduled interruptions /availability

Installation work or other scheduled interruptions to the “Barcode” web service will be carried out at off-peak times wherever possible. Customers will be advised in good time via e-mail of scheduled downtimes and interruptions to the service.

4.4 Interruptions to “Barcode” web service

Swiss Post sets the highest internal standards for high performance and stable, trouble-free operation of the “Barcode” web service. However, in exceptional circumstances technical problems or failures may result in an interruption to the “Barcode” web service. In order to deal with such situations, we recommend you have the ability to fall back on an alternative process using Swiss Post’s conventional barcode labels

4.5 Services offered

Labels are available for the following service groups:

• Domestic Parcels (PostPac Priority, PostPac Economy, bulky goods Priority, bulky goods Economy, PostPac Promo, PostPac Economy GAS, PostPac Priority GAS, bulky goods Economy GAS, bulky goods Priority GAS)
• Express (Swiss-Express “Moon”, bulky goods “Moon”, Swiss Express “Moon” GAS, SameDay afternoon/evening , SameDay afternoon/evening bulky goods, SameDay afternoon/evening GAS
• Solutions (VinoLog, Direct parcel posting)
• Letters with barcode (BMB) domestic with the following basic services:
• Registered (R) domestic, A Mail Plus, Dispomail, Dispomail Easy, Court documents (GU) and Debt collection documents (BU) (all including the relevant additional services)
• A and B Mail letters with Electronic cash on delivery (BLN) additional service
• Letters with barcode (BMB) international with the following products:
• Registered (R) international

4.6 Label formats

• Format A7 (74 × 105 mm)
• Format A6 (105 × 148 mm)
• Format A5 (148 × 210 mm): only available for Domestic Parcels, Express and Solutions
• Format FE (window envelope): only available for Letters with barcode (BMB) domestic and international

4.6.1 Contents for individual label formats

1) For legal reasons NO address labels can be generated in formats A6 and A7 for the basic services Court documents (GU) and Debt collection documents (BU).

2) When using two delivery instructions per address label (affects DLG Parcels, Express and Solutions) or with VinoLog, there may be an overlap of the last sender character by the consignment number or the VinoLog bar.

3) For Letters with barcode (BMB) domestic the ProClima logo will be printed automatically (at no additional charge).

4) Basic services with additional barcodes must be included in maximum number of PRZL (e.g. for PostPac Priority, Swiss-Express Moon, etc.).

5) Delivery instructions are only available for Domestic Parcels, Express and Solutions

6) When retrieving single barcodes, it is not possible to reduce their size, because the positioning of the single barcodes is the responsibility of the user and must conform to the guidelines stipulated in the manual on “Barcodes and Data Matrix codes for letters mail” (www.post.ch/-/media/portal-opp/pm/dokumente/handbuch-barcodes-und-datatmatrix-codes-fuer-briefsendungen.pdf?la=en&vs=5).

4.6.2 Recipient’s address – maximum number of address lines (concerns the “GenerateLabel” request)

The number of address lines that can be printed on an address label is limited because there is a limited amount of space on the labels. Depending on the selected format, the selected basic service, the number of address fields and, if applicable, the delivery instructions (ZAW) or free text, not all address lines can be printed.

Rules when exceeding the maximum amount of address lines

When the maximum permitted amount of address lines is exceeded, address lines are omitted from the address label in the order below. This only applies to address lines from the “Recipient” address block and – if applicable and permissible – for free text

1. Title (Title) is omitted
2. Address suffix (AddressSuffix) is omitted
3. Name 3 (Name3) is omitted
4. Free text (FreeText) is omitted

Please find some examples further down.

Data transmission

The information from the “AddressSuffix” address field element is not transmitted to DataTransfer, regardless of the number of address lines used.

„LabelAddress“ address block

When using the “LabelAddress” address block, you can define yourself which recipient’s address lines are to be printed on the address label and in what order for a minimum of 2 and a maximum of 5 address lines (LabelLine1 to LabelLine5). An exception applies to the fields “ZIP” and “City” (and, for international mailings, also to “Country”), which are taken across from the “Recipient” address block. This means that you must define the procedure to be used yourself if the maximum amount of address lines is exceeded.

1) Delivery instructions are not possible for A7 format.

Examples for addressing rules for the “Recipient” address block

The examples below apply only if the “LabelAddress” address block is not used. Missing information in the recipient’s address is completed using the contents of the “Recipient” address block and – if available – the free text.

Example 1: Format A6, max. 1 ZAW, DLG parcels

Details in the “Recipient” block + free text: 8 address lines

• FreeText (1st address line) Title (2nd address line)
• Firstname (3rd address line)
• Name1 (3rd address line)
• Name2 (4th address line)
• Name3 (5th address line)
• AddressSuffix (6th address line)
• Street (7th address line)
• HouseNo (7th address line)
• ZIP (8th address line)
• City (8th address line)

Details on the address label: max. no. of address lines allowed: 8 no adjustment by WSBC required

• FreeText
• Title
• Firstname Name1
• Name2
• Name3
• AddressSuffix
• Street HouseNo
• ZIP City

Example 2: Format A6, 2 ZAWs, DLG parcels

Details in the “Recipient” block + free text: 8 address lines

• Title (1st address line)
• Firstname (2nd address line)
• Name1 (2nd address line)
• Name2 (3rd address line)
• Name3 (4th address line)
• AddressSuffix (5th address line)
• Street (6th address line)
• HouseNo (6th address line)
• ZIP (7th address line)
• City (7th address line)

Details on the address label: max. no. of address lines allowed: 6 automatic adjustment by WSBC

• Firstname Name1
• Name2
• Name3
• AddressSuffix
• Street HouseNo
• ZIP City

Example 3: Format A7, DLG BMB domestic; “Registered (R) domestic”

Details in the “Recipient” block: 7 address lines

• Title (1st address line)
• Firstname (2nd address line)
• Name1 (2nd address line)
• Name2 (3rd address line)
• Name3 (4th address line)
• AddressSuffix (5th address line)
• Street (6th address line)
• HouseNo (6th address line)
• ZIP (7th address line)
• City (7th address line)

Details on the address label:max. no. of address lines allowed: 6 automatic adjustment by WSBC

• Firstname Name1
• Name2
• Name3
• AddressSuffix
• Street HouseNo
• ZIP City

4.6.3 Names of label elements

4.7 Printer resolution (dpi)

200 dpi (equivalent to 203 dpi on Zebra label printers)

300 dpi (equivalent to 305 dpi on Zebra label printers)

600 dpi (equivalent to 610 dpi on Zebra label printers)

4.8 Image formats /printer languages

EPS

GIF

JPG (not recommended as barcode may not have high enough quality)

PNG

PDF

sPDF¹⁾

ZPL2

4.9 Layout options for express items

The basic service barcodes for SameDay and Swiss-Express “Moon” services are printed in colour.

If there is no possibility to print the corresponding basic service barcode in colour on the address label, it can be printed in black and white. However, an additional, coloured basic service barcode must then be affixed to the item.

The coloured stickers can be ordered via www.swisspost.ch/ online-services > Order forms & brochures.

4.10  Label generation time and file sizes

The time it takes to generate a label and the corresponding file size depend on the format selected, the printer resolution, the sender’s logo and the image format/printer language used. The speed of the Internet connection is also a key factor. It is therefore very important to have a fast connection.

The table below gives some guideline values (measured with transfer rate of 45,000 kbps, without a sender’s logo). However, these do not take the data rate of your Internet connection into account, which could have a major impact on performance. These are average figures for formats A5, A6, A7 and FE

1)  Format sPDF is a PDF file without embedded fonts. In order to display this format correctly, the Arial font must be installed on your computer. The generation and transmission times are faster with sPDF than with PDF.

4.11 Sender’s logo

The sender’s address must always be entered in the “Barcode” web service. You can hide the display of the sender details on the address label or display them as a text or image (e.g. company logo).

If using an image/logo, please note the following:

• File size: max. 50 kB
• File forma: GIF, PNG or JPG

You can control how your image/logo is printed on address labels with the following four optional fields:

• Aspect ratio: Using this field, you can decide whether the original ratio of width to height should be maintained or scaled to 47 mm × 25 mm.
• Vertical align: Using this field, you can decide whether the logo should be aligned vertically at the top or in the middle.
• Horizontal align: Using this field, you can decide whether the logo should be aligned horizontally at the left margin or flush with the barcode.
• Rotation: Using this field, you can decide whether the logo should be printed in portrait or landscape orientation on the address label (clockwise rotation options: 0°/90°/180°/270°).

If no settings are changed in these fields, your image/logo will be automatically printed with the following settings:

• scaling to the aspect ratio of 1.88 (image width: 47 mm / image height: 25 mm)
• The logo will be printed rotated anti-clockwise by 90°.

We recommend using a black and white logo for printing in the ZLP2 format.

4.12 Printer models approved for “Barcode” web service

When your system receives them, you can forward the labels generated by the “Barcode” web service directly to a continuous label printer. This is possible with printer language ZPL2. In order for this to work, the printer models used must support ZPL2 as a printer language, otherwise the quality requirements of the labels will not be met.

To ensure adequate barcode print quality, you should always use high-quality shipping label materials.

Note also that shipping labels are printed in either landscape or portrait format, depending on the specifications of the printer models.

5.1 Overview of service codes (DLC)

• Technical errors (e.g. validation errors) are returned as error elements in the response. A response may contain warnings as well as the desired response – e.g. several warnings may be issued when generating multiple address labels. With warnings, the request is executed, but when an error occurs it is rejected.
• Master data and error messages are returned in the language used for the call (German, French, Italian or English)

5.1.1 Overview for service codes (DLC) – Domestic Parcels, Express and Solutions

The service descriptions for the following basic and additional services plus delivery instructions can be found at www.swisspost.ch/post-distribution-national.

Combinations of multiple service codes, e.g. “PRI, SP”, are split into their individual elements. The following is given as an example (sequencing of individual content does not matter):

<PRZL> PRI </PRZL>

<PRZL> SP </PRZL>

1) When using the ZFZ (Time slot delivery) value-added service, we recommend you first perform an area check for each recipient address via your connection to the Digital Commerce API – Swiss Post shipping options.

2) For the collection of empty containers or materials for recycling – please contact your customer advisor for further information.

3) Only available in conjunction with notification service code 128 (“Exchange/return”).

5.1.2 Overview of service codes (DLC) – Letters with barcode (BMB) domestic

The product descriptions for the following basic and additional services can be found at www.swisspost.ch/post-briefe-versand-national.

1) Only available for “legal documents (GU)” basic service.

5.1.3 Overview of service codes (DLC) – Letters with barcode (BMB) international

The product descriptions for the following basic and additional services can be found at www.swisspost.ch/post-versand-international-gk.

Combinations from several services codes, e.g.“RETR, PRI” will be transmitted individually as content where appropriate. The following is given as an example (sequencing of individual content does not matter):

<PRZL> RETR </PRZL>

<PRZL> PRI </PRZL>

5.2 Validate Combination operation

This operation returns a validation response for a given combination of service codes.

5.2.1 Validate Combination request

You can download an XML example as well as a graphical interface description per request here: www.swisspost.ch/post-barcode-cug

5.2.2 Validate Combination response

Returns a list of errors and warnings from validation if applicable.

You can download an XML example as well as a graphical interface description per request here: www.swisspost.ch/post-barcode-cug

5.3 Generate Label operation (Generate Label)

Returns one or more generated labels in binary format.

5.3.1 Generate Label request (Generate Label)

You can download an XML example as well as a graphical interface description per request here: www.swisspost.ch/post-barcode-cug

1) Domestic Parcels, Express and Solutions: either address or P.O. box permitted. BMB domestic: state address and P.O. box with number (if applicable). P.O. Box details are compulsory fpr Dispomail and Dispomail Easy. BMB international: no rules. All address components must be split between Address 1 and Address 2.

2) Validation logic for FrankingLicence, ItemID, ItemNumber, IdentCode and Hauskey fields: – FrankingLicence: Mandatory (left-pad with zeros up to 8 digits) – ItemID: Optional, any value – ItemNumber: Optional, any value. If filled in, validation for uniqueness. If ItemNumber is empty, the item number is generated and the identcode is generated from this item number and the franking licence. – IdentCode and Hauskey: Not permitted. If this field is filled, it will be ignored and a warning will also be returned. IdentCode is provided solely for internal calls at Swiss Post.

3) With the basic services with GAS, the recipient is the return address in accordance with the contractual terms for business reply items.

4) The postage paid impression for the Letters with barcode (BMB) domestic and international service groups does not appear automatically in the address and applies to each request.

5) Additional information on BLN (electronic COD) is detailed under section 5.3.1.1.

5.3.1.1 Posting BLN (electronic COD) via “Barcode” web service (for “Parcels” and “Swiss-Express”)

If you already use the “Barcode” web service actively and would later like to programme BLN, we can provide a test environment for you. Please contact Digital Integration for further information.

BLN-defined transaction types for credit notes

The credit note for COD amounts can be applied by means of three different account types:

1. PostFinance account from PostFinance
2. IBAN from a bank or PostFinance
3. QR-IBAN or Swiss Post ISR

With transaction types 1 (PostFinance account) and 2 (IBAN), only the COD amount is required. With transaction type 3 (QR-IBAN/ISR), both the COD amount and the 27-digit QR reference (previously the ISR reference number) are required.

PostFinance account (transaction type 1) or IBAN (transaction type 2)

QR-IBAN or Swiss Post ISR (transaction type 3)

5.3.1.2 Notification services

Notification code

In the “Notification” element, the “Service” field has the following valid values:

Notification text messages

The description of the content of e-mail messages as well as technical specifications regarding free text are available at www.swisspost.ch/post-e-log-avisierungsservices-details.

1) This notification service can only be used with delivery instruction ZAW3233.

2)  This notification service can only be used with the additional service “SA”.

5.3.2 Generate Label response (Generate Label)

You can download an XML example as well as a graphical interface description per response here: www.swisspost.ch/post-barcode-cug

5.4 Generate barcodes operation (Generate Barcode) (only relevant for letter products)

For the corresponding request, precisely one barcode will be generated and returned in the correct format for the Barcode online delivery note (LSO 98.93). This enables you to obtain a delivery note number via “Barcode” web service, if you create the online delivery note yourself (only available for service group “Letter with barcode” [BMB])

5.4.1 Generate barcodes request (Generate Barcode)

You can download an XML example as well as a graphical interface description per request here: www.swisspost.ch/post-barcode-cug

5.4.2 Generate barcodes response (Generate Barcode)

You can download an XML example as well as a graphical interface description per response here: www.swisspost.ch/post-barcode-cug

5.5 Generate single barcodes operation (GenerateSingleBarcodes) (only relevant for letter products)

Returns all single barcodes for one or several address labels generated in binary format

5.5.1 Generate single barcodes request (GenerateSingleBarcodes)

You can download an XML example as well as a graphical interface description per request here: www.swisspost.ch/post-barcode-cug

5.6 Read Service Groups operation (ReadServiceGroups)

Returns all service groups.

5.5.2 Generate single barcodes response (GenerateSingleBarcodes)

You can download an XML example as well as a graphical interface description per response here: www.swisspost.ch/post-barcode-cug

5.6 Read Service Groups operation (ReadServiceGroups)

Returns all service groups.

5.6.1 Read Service Groups request (ReadServiceGroups)

You can download an XML example as well as a graphical interface description per request here: www.swisspost.ch/post-barcode-cug

5.6.2 Read Service Groups response (ReadServiceGroups)

You can download an XML example as well as a graphical interface description per response here: www.swisspost.ch/post-barcode-cug

5.7 Read Basic Services operation (ReadBasicServices)

Returns all the basic services for a specified service group.

5.7.1 Read Basic Services request (ReadBasicServices)

You can download an XML example as well as a graphical interface description per request here: www.swisspost.ch/post-barcode-cug

5.7.2 Read Basic Services response (ReadBasicServices)

You can download an XML example as well as a graphical interface description per response here: www.swisspost.ch/post-barcode-cug

5.8 Read Additional Services operation (ReadAdditionalServices)

Returns all the additional services for a specified basic service.

✓ = permitted, X = not permitted

For Letters with barcode (BMB) domestic

✓ = permitted, X = not permitted

For Letters with barcode (BMB) international

✓ = permitted, X = not permitted

5.8.1 Read Additional Services request (ReadAdditionalServices)

You can download an XML example as well as a graphical interface description per request here: www.swisspost.ch/post-barcode-cug

5.8.2 Read Additional Services response (ReadAdditionalServices)

You can download an XML example as well as a graphical interface description per response here: www.swisspost.ch/post-barcode-cug

5.9 Read Delivery Instructions operation (ReadDeliveryInstructions) for Domestic Parcels, Express and Solutions

Returns all the delivery instructions for a specified basic service. You can order the corresponding document (Barcode for Business Customers – Appendix 1) by e-mailing paketnational.pl43@post.ch.

5.9.1 Read Delivery Instructions request (ReadDeliveryInstructions)

You can download an XML example as well as a graphical interface description per request here: www.swisspost.ch/post-barcode-cug

5.9.2 Read Delivery Instructions response (ReadDeliveryInstructions)

You can download an XML example as well as a graphical interface description per response here: www.swisspost.ch/post-barcode-cug

5.10 Read Label Layouts operation (ReadLabelLayouts)

Returns all the label layouts for a specified service group.

5.10.1 Read Label Layouts request (ReadLabelLayouts)

You can download an XML example as well as a graphical interface description per request here: www.swisspost.ch/post-barcode-cug

5.10.2 Read Label Layouts response (ReadLabelLayouts)

You can download an XML example as well as a graphical interface description per response here: www.swisspost.ch/post-barcode-cug

5.11 Read basic services of a franking licence operation (ReadAllowedServices ByFrankingLicense)

Returns all for a franking licence applicable to group services with description, PostId, and available basic services.

5.11.1 Read basic services of a franking licence request (ReadAllowedServices ByFrankingLicense)

You can download an XML example as well as a graphical interface description per request here: www.swisspost.ch/post-barcode-cug

5.11.2 Read basic services of a franking licence response (ReadAllowedServices ByFrankingLicense)

You can download an XML example as well as a graphical interface description per response here: www.swisspost.ch/post-barcode-cug

5.12 Error messages

Every error message consists of a four-digit error code prefixed by “E” (E1234), beginning at E1000, plus an associated error text. The web service returns the error texts in the specified language (German, French, Italian or English).

If an error message is returned, the requested service is not executed and is rejected. The error must be corrected and the call repeated.

The curly brackets are placeholders and are replaced by the relevant values in the actual error message.

5.13 Warnings

Every warning consists of a four-digit warning code prefixed by “W” (W1234), beginning at W1000, plus an associated warning text. The web service returns the warning texts in the specified language (German, French, Italian or English). An operation may return more than one warning at a time.

If a warning is returned, the requested service is executed, taking the warning into account. Warnings help to optimize your use of the “Barcode” web service.

The curly brackets are placeholders and are replaced by the relevant values in the actual warning.

Overview of Swiss Post’s online services

www.swisspost.ch/online-services

Publications on the “Barcode” web service

“Barcode” web service website

www.swisspost.ch/post-webservice-barcode

User manual Client API, Library for Java and C#/.Net and instructions for PHP

www.swisspost.ch/post-barcode-cug

Manual, WSDL, XSD and examples for downloading

www.swisspost.ch/post-barcode-cug.htm

“Barcode” web service subscriber conditions

www.swisspost.ch/post-tnb-webservice-barcode.pdf

Publications on the “Track & Trace” web service

“Track & Trace” web service website

www.swisspost.ch/post-e-log-webservice-sendung-verfolgen

Manual, WSDL and examples for the “Track consignment”web service

www.swisspost.ch/post-sendungenverfolgen-cug

Publications on DataTransfer for Letters with barcode BMB

www.swisspost.ch/post-datatransfer-cug-briefe.htm

Costumer sheet (WSBC) (PDF, 61.8 KB)

Updates in version 2.5.4 (September 2023)

• New contact points added. Affected sections: 1.7 / 3.15 / 3.16
• New basic services added: SmallPac Economy, SmallPac Priority, VinoLog Priority. Affected sections 2.2.1 / 5.1.1 / 5.7 / 5.8 / 5.9