Digital Commerce API



Language navigation

Digital Commerce API

Close

Digital Commerce API

1 Swiss Post e-commerce API reference

The Swiss Post e-commerce API is a REST API which provides predictable and resource-oriented URLs and uses HTTP response codes to indicate API errors. It uses built-in HTTP features to receive commands and return responses. This makes it easy to communicate with from a wide variety of environments, from command-line utilities, server-side or client-side web applications and mobile devices. It supports the JSON format in requests and it returns JSON content in all of its responses, including errors. It supports cross-origin resource sharing to allow you to interact securely with our API from a client-side web application.

The access to the Swiss Post e-commerce API is controlled by the OAuth authorization protocol. An access token is required to consume the endpoints exposed by the API. This is obtained after a sucessful authentication.

2 Overview

2.1 API endpoints

Endpoint URL Aim
address Integration
https://wedecint.post.ch/api/address/v1
Production
https://wedec.post.ch/api/address/v1
Provides the access to the personal addresses of Swiss Post registered users, it refers to the list of their delivery addresses.
Moreover this API provides the access to unpersonal business data and exposes address validation service and an auto-completion service for zip codes, street names and house numbers.
delivery Integration
https://wedecint.post.ch/api/delivery/v1
Production
https://wedec.post.ch/api/delivery/v1
Provides the access to unpersonal data delivered by the logistic services of Swiss Post, it refers to the list of the deliverabilities, when and how a given valid address can be delivered.
userinfo Integration
https://wedecint.post.ch/userinfo
Production
https://wedec.post.ch/api/userinfo
Provides the access to personal data of Swiss Post registered users, it refers to the attributes of their Swiss Post profile.
http://openid.net/specs/openid-connect-core-1_0.html#UserInfo
http://openid.net/specs/openid-connect-core-1_0.html#IDToken
authorization Integration
https://wedecint.post.ch/WEDECOAuth/authorization
OAuth Endpoint for querying an authorization code, usually obtained with the consent of an authenticated end user, given a set of scopes and credentials.
http://openid.net/specs/openid-connect-core-1_0.html#AuthRequest
token Integration
https://wedecint.post.ch/WEDECOAuth/token
OAuth Endpoint for exchanging an authorization code against an access token.
http://openid.net/specs/openid-connect-core-1_0.html#TokenRequest

3 Authentication

The access to the Swiss Post connector and the e-commerce API is controlled by both OpenID-Connect protocol version 1.0 and OAuth authorization protocol version 2.0.

Only Swiss Post registered clients can be authorized to consume the Swiss Post connector and the e-commerce API. The OpenID endpoint and some endpoints of the e-commerce API require the authorization of the end users when personal data is queried. 

OAuth is an authorization protocol and not an authentication protocol. The client and the end user have to be authenticated; consequently the authentication is an implicit part of the protocol.

For more information see http://tools.ietf.org/html/rfc6749

3.1 OAuth

A client of the Swiss Post e-commerce API must first obtain an OAuth access token in order to consume the endpoints of the API.

  • The client is authenticated by the OAuth credentials received after a successful registration: client-id, client-secret.
  • A set of scopes need to be mentioned when ordering the access token, a scope corresponds to a use case applied on one or more endpoints of the API.
  • These scopes must be a subset of the ones configured during the registration process.
  • Moreover the end user may have to be authenticated and have to authorize the client for the set of ordered scopes.
  • Finally an access token is returned to the client through a redirection URL configured during the registration. The returned access token is a bearer token.
  • Depending on the implemented OAuth flow for the query of the access token, a refresh token is returned. This is used for access token renewal without user consent. 

The OAuth authorization protocol defines a set of standard flows for querying an access token. A client of the Swiss Post e-commerce API is responsible for the integration of the desired flows in his use cases.

For more information see http://tools.ietf.org/html/rfc6749

3.2 OpenID-Connect

The access to personal data by a registered client through the Swiss Post connector is controlled by the OpenID-Connect protocol. This is based on the OAuth standard authorization protocol. The OpenID-Connect flow is based on the OAuth authorization code grant flow or the OAuth implicit code grant flow. It finally returns an ID-Token and an access token to the client. 

  • The returned ID-Token contains the personal data out of the identity of the end user mapped to each ordered OpenID scope.
  • The returned access token can be used for consuming the standard Userinfo endpoint or the endpoints of the Swiss Post e-commerce API when eventually covered by the other ordered non-OpenID scopes.
  • Both the returned ID-Token and access token are bearer tokens.
  • With the ID-Token the client maybe already receives the full desired data at the end of the flow and is not forced to implement a subsequent call to consume the standard Userinfo endpoint. 

A client of the Swiss Post Connector is responsible for the integration of the desired flows in his use cases. 

For more information see http://openid.net/specs/openid-connect-core-1_0.html#Introduction

3.3 Authorization code grant flow

See http://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth

Some scopes giving access to non-personal data can be ordered besides the other scopes. They do not require any consent by the end user and are not displayed inside the consent screen.

3.3.1 Authentication request

GET request

https://wedec.post.ch/WEDECOAuth/authorization?
client_id=wedec-fake-shop&
scope=WEDEC_READ_ADDRESS+openid+profile+email+address&
response_type=code&
redirect_uri=http://localhost:8080/fake-shop/&
nonce=f5bb9f70-2&
state=bbe6606b-b

For more information see http://openid.net/specs/openid-connect-core-1_0.html#AuthRequest

3.3.2 Authentication response

Response

HTTP/1.1 302 Found
Location: http://localhost:8080/fake-shop/?state=056be689-d&code=iUkxvid_e4k813KgLWcNvYj2KAqK60r0ixe8W4kiMPY

For more information see http://openid.net/specs/openid-connect-core-1_0.html#AuthResponse

3.3.3 Authentication response validation

We recommend that the client validates the authentication response, see http://openid.net/specs/openid-connect-core-1_0.html#AuthResponseValidation

3.3.4 Token request

POST request

https://wedec.post.ch/WEDECOAuth/token?
grant_type=authorization_code&
client_id=wedec-fake-shop&
client_secret=wedec-fake-shop-secret&
redirect_uri=http://localhost:8080/fake-shop/&
code=iUkxvid_e4k813KgLWcNvYj2KAqK60r0ixe8W4kiMPY

For more information see http://openid.net/specs/openid-connect-core-1_0.html#TokenRequest

3.3.5 Token response

Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
“expires_in”:300,
“token_type”:“Bearer”,
“id_token”:
“eyJhbGciOiJSUzI1NiJ9.eyJleHAiOjE0MTEwNTE5MTQsInN1YiI6IjEwMDQ5MjIiLCJub25jZSI6IjczZDc3N2U0LTciLCJhdWQiOlsid2Vk
ZWMtZmFrZS1zaG9wIl0sImlzcyI6Imh0dHBzOlwvXC9hcGlkZXYucG5ldC5jaCIsImlhdCI6MTQxMTA1MTMxNH0.
SBYodQCRmsbZvSHnBenLqPGS-U9Q_Z
S8wTM7TvvyiDxiF27pKvjwsF6vYzJsucpluz750bH-OVtL-Esh72M-Ki8L_3hGImgpZ-K7KaRRM9BG3UA-
5M8ZZloVTpz6W47H_xi-Q_NwCqApgawdEP8rI
ECKtSdk3En8A3rDSrCLNhF2LO-56rsC2rwcdBqrpth_89Iq00O1kMPNZ2H_HJpQzBIku04WGOwbx-
2K3f5b_BV-VKVjqkqEMoacJcP_c9pQY2YxpIGAfOnS
ROMYCJfM5M-QmsgDCn9B9Z0yicbPwDexS4y1FqOMFXVIJYt94qek8n8CVqp9KQBl2ptEuAbD6HIA”,
“access_token”:“eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMjU2R0NNIn0.XpENWZLOwkvlwiY0TWCUZ2LTAbd-
P895E1BlAClqmB3oHTehtMGkXCNudURQtwc
CVR23dYalRYLDP_huIHqwNjHoAYip2CsyiTrYQySp4wZzRb5Cm1QKvTq2yGfFUcK2qIqr7nFD_CEei8_EpVHanYSE3srnWZkVEI8btQOg32bKOaidwLBaP
LgFHfgom6l7n6ewh7UFv1WcRjk9Ug48oHUrpVQEBnu1pXr8gFEtEpmTZhT1TUCwUsyxzH36dkgzSZ4DHCvuIPDOtWpurQZQiu0OQVWd3ih2z7jSECXzUD7
9oIxqzN_pWNVeb4jGvVhTYktBmsCYxJZCslm_NtuMJg.V4qpGmkldszeRMk.KI_swCCP6rvvkiGOkNWLghqK-
0BXrsz5qdimYNxkGNkbE2NQeJKfaGPtLKb
1d59YIwe_Ng_kqpBg05_39OOLgC4tA5JsEipOPm951fDlclmx0ybKwPqtNCjigGP_yxrwcbHwPSEofnNMakt-
GnVpCadUMjeNUb6QRzybylS3CxeWsv19md
U48xTiHGNqzgB2iWT9DkzfCcP0o3bTqTNcdD4uLdE1oA-hev5bT3XDV56XlH1SprSva2sQ86k6mFgHTcqTp8MnFzEXSjBe_
QkiJJgfx53c8pzVruby2kiW
xdYm91ILStVUCQZ26EPGFhTN03TZTZ0BeM6cHvapvOO_JWwWdbsc_dx4YLpCIdF9FjlJruLHFx-
29ZAweSuXdSmM4v7X9jCh3_5iNWeniYjwmzYb9vMbOd2
UrlGoGxnUdJ_BTOjB8LXHQ7mO35ycl4L0o7j8pF6qDxJiQapPFl4jI77WksrvkVFNvyTUIL_JggQrPjO0cCuHlevIi-
W0I50aS3Vj8oGLFcOM9QnBuL3tyk
1BvQdwtfXX6mmqvp1OfFWkfClytBcBcBWdLgzFKKpkXQ0Unaa_uQxtVLBfAuisF1w8idPia9hcP2jv_Eeyy0iqjnDtO.
CKPdNsuq22qlhNRRQODqnw”
}

For more information see http://openid.net/specs/openid-connect-core-1_0.html#TokenResponse

3.3.6 Token response validation

We recommend that the client validates the token response, see http://openid.net/specs/openid-connectcore-1_0.html#TokenResponseValidation

3.4 Implicit code grant flow

See http://openid.net/specs/openid-connect-core-1_0.html#ImplicitFlowAuth

Some scopes giving access to non-personal data can be ordered besides the other scopes. They do not require any consent by the end user and are not displayed inside the consent screen.

3.4.1 Token request

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
“expires_in”:300,
“token_type”:“Bearer”,
“id_token”:
“eyJhbGciOiJSUzI1NiJ9.eyJleHAiOjE0MTEwNTE5MTQsInN1YiI6IjEwMDQ5MjIiLCJub25jZSI6IjczZDc3N2U0LTciLCJhdWQiOlsid2Vk
ZWMtZmFrZS1zaG9wIl0sImlzcyI6Imh0dHBzOlwvXC9hcGlkZXYucG5ldC5jaCIsImlhdCI6MTQxMTA1MTMxNH0.
SBYodQCRmsbZvSHnBenLqPGS-U9Q_Z
S8wTM7TvvyiDxiF27pKvjwsF6vYzJsucpluz750bH-OVtL-Esh72M-Ki8L_3hGImgpZ-K7KaRRM9BG3UA-
5M8ZZloVTpz6W47H_xi-Q_NwCqApgawdEP8rI
ECKtSdk3En8A3rDSrCLNhF2LO-56rsC2rwcdBqrpth_89Iq00O1kMPNZ2H_HJpQzBIku04WGOwbx-
2K3f5b_BV-VKVjqkqEMoacJcP_c9pQY2YxpIGAfOnS
ROMYCJfM5M-QmsgDCn9B9Z0yicbPwDexS4y1FqOMFXVIJYt94qek8n8CVqp9KQBl2ptEuAbD6HIA”,
“access_token”:“eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMjU2R0NNIn0.XpENWZLOwkvlwiY0TWCUZ2LTAbd-
P895E1BlAClqmB3oHTehtMGkXCNudURQtwc
CVR23dYalRYLDP_huIHqwNjHoAYip2CsyiTrYQySp4wZzRb5Cm1QKvTq2yGfFUcK2qIqr7nFD_CEei8_EpVHanYSE3srnWZkVEI8btQOg32bKOaidwLBaP
LgFHfgom6l7n6ewh7UFv1WcRjk9Ug48oHUrpVQEBnu1pXr8gFEtEpmTZhT1TUCwUsyxzH36dkgzSZ4DHCvuIPDOtWpurQZQiu0OQVWd3ih2z7jSECXzUD7
9oIxqzN_pWNVeb4jGvVhTYktBmsCYxJZCslm_NtuMJg.V4qpGmkldszeRMk.KI_swCCP6rvvkiGOkNWLghqK-
0BXrsz5qdimYNxkGNkbE2NQeJKfaGPtLKb
1d59YIwe_Ng_kqpBg05_39OOLgC4tA5JsEipOPm951fDlclmx0ybKwPqtNCjigGP_yxrwcbHwPSEofnNMakt-
GnVpCadUMjeNUb6QRzybylS3CxeWsv19md
U48xTiHGNqzgB2iWT9DkzfCcP0o3bTqTNcdD4uLdE1oA-hev5bT3XDV56XlH1SprSva2sQ86k6mFgHTcqTp8MnFzEXSjBe_
QkiJJgfx53c8pzVruby2kiW
xdYm91ILStVUCQZ26EPGFhTN03TZTZ0BeM6cHvapvOO_JWwWdbsc_dx4YLpCIdF9FjlJruLHFx-
29ZAweSuXdSmM4v7X9jCh3_5iNWeniYjwmzYb9vMbOd2
UrlGoGxnUdJ_BTOjB8LXHQ7mO35ycl4L0o7j8pF6qDxJiQapPFl4jI77WksrvkVFNvyTUIL_JggQrPjO0cCuHlevIi-
W0I50aS3Vj8oGLFcOM9QnBuL3tyk
1BvQdwtfXX6mmqvp1OfFWkfClytBcBcBWdLgzFKKpkXQ0Unaa_uQxtVLBfAuisF1w8idPia9hcP2jv_Eeyy0iqjnDtO.
CKPdNsuq22qlhNRRQODqnw”
}
HTTP/1.1 302 Found
Location: http://localhost:8080/fake-shop/#
state=ca48d322-7906-40e4-b8d5-09933cbcce45&
token_type=Bearer&
expires_in=300&
access_token=eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMjU2R0NNIn0.aBvqaCwZF7_44_wCSJ6jebzU00DFrqEikcsDuy_
MNFzzUxkM7P7C9EQ2LqjZcqwlybO8hE2XdJKEHGD16SFTH-J4_el3x8tlJJyfTwvQCNfklYY4der-
6SCPXo8D6HfAK5Ehes1507sKBjQ7hW1zRLxww6I4o0sab23PWKx9fLZydTQamFhu
_EwBYvIA0ya8vpqaIhYtmnQbt_9ylfVY2azM9UAm6TPwkD0HjGs1itz5_AmoR-AaKvZNhpDFL6gbdOs-
V2AVMfcpSaGDs7r-s4GIoOqjTSudMAc1S_g5DTlmmKg8mb2BhiNQj_rdS7kgS483GJSwl84r0MKlIrmOlLDA.
jUKXofbp6IFXzokp.PRg7TmHoE9444SpPcsGu8hVdaNfovKZV7Grp1COqZ2Wf3OYHOsTaKLajbfoSvSEFS6t-
Dyw_FPkRssh58MtADjQJYwbf4qDuflHw7iYua-hQFNt4zUh6AJZCTbpz0YEqUbllE7r6dzg36VXlO9ueQi0DmHqH9P0zwTW4CKcIi_
Q.D-hUFgKsbQ2WrO2k9tjwDA

For more information see http://openid.net/specs/openid-connect-core-1_0.html#ImplicitAuthResponse

3.4.2 Token response validation

We recommend that the client validate the token response, see http://openid.net/specs/openid-connectcore-1_0.html#TokenResponseValidation

3.5 Client credential flow

This flow is suitable for the server-side access by a registered client to non-personal data. No consent by any end user is necessary for the ordered scopes, the client exchanges its OAuth credentials for an access token.

This flow is implemented on the server side.

3.5.1 Token request

$ curl -X POST https://wedec.post.ch/WEDECOAuth/token?grant_type=client_credentials&client_id=wedec-fake-shop&client_secret=wedec-fake-shop-secret&scope=WEDEC_DELIVERY

3.6 Use access token

3.6.1 Resource request

$ curl -H Authorization: Bearer
eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMjU2R0NNIn0.XpENWZLOwkvlwiY0TWCUZ2LTAbdP895E1BlAClqm-
B3oHTehtMGkXCNudURQtwc
CVR23dYalRYLDP_huIHqwNjHoAYip2CsyiTrYQySp4wZzRb5Cm1QKvTq2yGfFUcK2qIqr7nFD_CEei8_
EpVHanYSE3srnWZkVEI8btQOg32bKOaidwLBaP
LgFHfgom6l7n6ewh7UFv1WcRjk9Ug48oHUrpVQEBnu1pXr8gFEtEpmTZhT1TUCwUsyxzH36dkgzSZ4DHCvuIPDOtWpurQZQiu0OQVWd3ih2z7jSECXzUD7
9oIxqzN_pWNVeb4jGvVhTYktBmsCYxJZCslm_NtuMJg.V4qpGmkldszeRMk.KI_swCCP6rvvkiGOkNWLghqK0BXrsz5qdimYNxkGNkbE2NQeJKfaGPtLKb
1d59YIwe_Ng_kqpBg05_39OOLgC4tA5JsEipOPm951fDlclmx0ybKwPqtNCjigGP_yxrwcbHwPSEofnNMaktGnVpCadUMjeNUb6QRzybylS3CxeWsv19md
U48xTiHGNqzgB2iWT9DkzfCcP0o3bTqTNcdD4uLdE1oAhev5bT3XDV56XlH1SprSva2sQ86k6mFgHTcqTp8MnFzEXSjBe_
QkiJJgfx53c8pzVruby2kiW
xdYm91ILStVUCQZ26EPGFhTN03TZTZ0BeM6cHvapvOO_JWwWdbsc_dx4YLpCIdF9FjlJruLHFx-
29ZAweSuXdSmM4v7X9jCh3_5iNWeniYjwmzYb9vMbOd2
UrlGoGxnUdJ_BTOjB8LXHQ7mO35ycl4L0o7j8pF6qDxJiQapPFl4jI77WksrvkVFNvyTUIL_JggQrPjO0cCu-
HlevIiW0I50aS3Vj8oGLFcOM9QnBuL3tyk
1BvQdwtfXX6mmqvp1OfFWkfClytBcBcBWdLgzFKKpkXQ0Unaa_uQxtVLBfAuisF1w8idPia9hcP2jv_Eeyy-
0iqjnDtO.CKPdNsuq22qlhNRRQODqnw
https://wedec.post.ch/api/userinfo
HTTP/1.1 200 OK Content-Type: application/json
{
“sub”: “248289761001”,
“name”: “Lang Michael”,
“given_name”: “Michael”,
“family_name”: “Lang”,
“preferred_username”: “michael.lang”,
“email”: “michael.lang@gmail.com”,
}

3.7 Use refresh token

Refresh tokens are issued when access tokens are issued during the authorization code grant flow and client credential grant flow. It can also depend on the configuration of the authroization server.

A refresh token has a higher TTL than the associated access token. This refresh token is used for access token renewal without user consent.

3.7.1 Access token renewal

$ curl -H Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
https://wedec.post.ch/WEDECOAuth/token?
grant_type=refresh_token&
refresh_token=tGzv3JOkF0XG5Qx2TlKWIA

3.8 End user’s personal information query

3.8.1 Prerequisites

  • OAuth access token for a set of OpenID scopes: openid, profile, email, address, phone. These scopes require the consent of the end user and can be obtained from an authorization code grant flow or an implicit grant flow.
  • Each OpenID scope is associated with a set of OpenID claims, see http://openid.net/specs/openid-connectcore-1_0.html#ScopeClaims
  • Bearer access token stored in the header of the request:
    Authorization: Bearer <OAuth access token>

3.8.2 KLP mapping

The standard OpenID claims (see http://openid.net/specs/openid-connect-core-1_0.html#StandardClaims) are mapped this way:

OpenID claims Aggregation Swiss Post profile attribute
sub - user profile id
name - firstName name
given_name - firstName
family_name - name
email - email
email_verified - TRUE or FALSE
gender - female or male
locale - language (rfc5646, without country code)
phone_number - mobilePhone or phone
phone_number_verified - TRUE or FALSE
address formatted name firstName
addressLine1
addressLine2
addressLine3
addressLine4
zip city
country
address street_address addressLine2
address locality city
address postal_code zip
address country country
updated_at - last user account change

3.8.3 The information out of the profile of the end user

GET request

https://wedec.post.ch/api/userinfo

Response

{
“sub”: “248289761001”,
“name”: “Lang Michael”,
“given_name”: “Michael”,
“family_name”: “Lang”,
“preferred_username”: “michael.lang”,
“email”: “michael.lang@gmail.com”,
}

3.8.4 Error codes

Code Reason
200 OK
403 Not authorized
404 No results found
500 Internal server error

4 Alternative Delivery Addresses

4.1 End user’s addresses query

4.1.1 Prerequisites

4.1.2 The personal addresses of the end user

GET request

https://wedec.post.ch/api/address/v1/users/current/addresses

Response

[
{
“type”:“MAIN”,
“nickname”:“KLP”,
“addressee”:{“firstName”:“Massimo”,“lastName”:“Cotelli”},
“geographicLocation”:{“house”:{“street”:“Via
Golena”,“houseNumber”:“31C”},“zip”:{“zip”:“6512”,“city”:“Giubiasco”}},
“logisticLocation”:{“house”:{“street”:“Via
Golena”,“houseNumber”:“31C”},“zip”:{“zip”:“6512”,“city”:“Giubiasco”}}
},
{
“id”:“e3089ed6-35cd-47ed-b477-143396f96ef4”,
“type”:“DOMICILE”,
“nickname”:“test-zytglogge”,
“addressee”:{“title”:“MISTER”,“firstName”:“Massimo”,“lastName”:“Cotelli”},
“geographicLocation”:{“house”:{“street”:“Zytgloggelaube”,“houseNumber”:“2”,“houseKey”:“701091
5”},“zip”:{“zip”:“3011”,“city”:“Bern”}},
“logisticLocation”:{“house”:{“street”:“Zytgloggelaube”,“houseNumber”:“2”,“houseKey”:“7010915”},
“zip”:{“zip”:“3011”,“city”:“Bern”}}
},
{
“id”:“573b3a3c-43df-4c3b-aaf2-4c3c0ca8f315”,
“type”:“POST_OFFICE”,
“nickname”:“432”,
“addressee”:{“title”:“MISTER”,“firstName”:“Massimo”,“lastName”:“Cotelli”},
“geographicLocation”:{“house”:{“street”:“Bahnhofstrasse”,“houseNumber”:“18”,“houseKey”:“37651
”},“zip”:{“zip”:“611000”,“city”:“Wolhusen”}},
“logisticLocation”:{“postBoxNumber”:“999”,“house”:{“street”:“Postfach”,“houseKey”:“37651”},“-
zip”:{“zip”:“6110”,“city”:“Wolhusen”}}
},
{
“id”:“1abf6700-2a3c-49fb-bf2c-c1790d85352f”,
“type”:“PICK_POST”,
“nickname”:“Test Modifica”,
“addressee”:{“title”:“MISTER”,“firstName”:“Massimo”,“lastName”:“Cotelli”},
“geographicLocation”:{“house”:{“street”:“Brünigstrasse”,“houseNumber”:“101”,“house-
Key”:“174827”},
“zip”:{“zip”:“607200”,“city”:“Sachseln”}},
“logisticLocation”:{“postBoxNumber”:“5”,“house”:{“street”:“Postfach”,“houseKey”:“174827”},“zip”:
{“zip”:“6072”,“city”:“Sachseln”}}
},
{
“id”:“b8dbdf51-6a6a-4ba4-aa55-45377277651f”,
“type”:“MY_POST_24”,
“nickname”:“mypost24”,
“addressee”:{“title”:“MISTER”,“firstName”:“Massimo”,“lastName”:“Cotelli”},
“geographicLocation”:{“house”:{“street”:“Avenue
A.Piccard”,“houseKey”:“76419394”},“zip”:{“zip”:“101573”,“city”:“Lausanne”}},
“logisticLocation”:{“house”:{“street”:“Avenue
A.Piccard”,“houseKey”:“76419394”},“zip”:{“zip”:“1015”,“city”:“Lausanne”}}
},
{
“id”:“36e720e8-a908-469e-9daf-6b376071a557”,
“type”:“POSTBOX”,
“nickname”:“testPF”,
“addressee”:{“title”:“MISTER”,“firstName”:“Massimo”,“lastName”:“Cotelli”},
“geographicLocation”:{“house”:{“street”:“Via
Galbisio”,“houseNumber”:“2”,“houseKey”:“72014233”,“zip”:{“zip”:“6503”,“city”:“Bellinzona”}},
“logisticLocation”:{“postBoxNumber”:“123”,“house”:{“street”:“Casella
postale”,“houseKey”:“72014233”},“zip”:{“zip”:“6503”,“city”:“Bellinzona”}}
}
]

4.1.3 The main address of the end user

GET request

https://wedec.post.ch/api/address/v1/users/current/addresses/main

Response

{
“type”:“MAIN”,
“nickname”:“KLP”,
“addressee”:{“firstName”:“Massimo”,“lastName”:“Cotelli”},
“geographicLocation”:{“house”:{“street”:“Via Golena”,“houseNumber”:“31C”},“zip”:{“zip”:“6512”,
“city”:“Giubiasco”}},
“logisticLocation”:{“house”:{“street”:“Via Golena”,“houseNumber”:“31C”},“zip”:{“zip”:“6512”,“city”:
“Giubiasco”}}
}

4.1.4 A single personal address of the end user

GET request

https://wedec.post.ch/api/address/v1/users/current/addresses/e3089ed6-35cd-47ed-b477-143396f96ef4

Response

{
“id”:“e3089ed6-35cd-47ed-b477-143396f96ef4”,
“type”:“DOMICILE”,
“nickname”:“test-zytglogge”,
“addressee”:{“title”:“MISTER”,“firstName”:“Massimo”,“lastName”:“Cotelli”},
“geographicLocation”:{“house”:{“street”:“Zytgloggelaube”,“houseNumber”:“2”,“house-
Key”:“7010915”
,“zip”:{“zip”:“3011”,“city”:“Bern”}},
“logisticLocation”:{“house”:{“street”:“Zytgloggelaube”,“houseNumber”:“2”,“house-
Key”:“7010915”},“zip
:{“zip”:“3011”,“city”:“Bern”}}
}

4.1.5 Error codes

Code Reason
200 OK
400 Invalis id parameter
403 Not authorized
404 No result found or address does not exist or is not owned by the currently authenticated Swiss Post user
500 Internal server error

5 Address Checker

5.1 Address validation

5.1.1 Prerequisites

5.1.2 Validate a given address

POST request

https://wedec.post.ch/api/address/v1/addresses/validation

POST payload

{
“addressee”:{“firstName”:“”,“lastName”:“”,“title”:“MISTER”},
“geographicLocation”:{
“house”:{“street”:“Serafino Balestra”,“houseNumber”:“20”},
“zip”:{“zip”:“6600”,“city”:“Locarno”}}
}

Response

{
“quality”:“CERTIFIED”,
“expires”:“20141118T110056+0100”,
“address”:{
“id”:“034ce086-c9bb-49df-9ed1-1b674e6d5717”,
“type”:“DOMICILE”,
“addressee”:{“title”:“MISTER”,“firstName”:“”,“lastName”:“”},
“geographicLocation”:{
“house”:{“street”:“Serafino Balestra”,“houseNumber”:“20”,“houseKey”:“76439798”},
“zip”:{“zip”:“6600”,“city”:“Locarno”}}}
}

5.1.3 Error codes

Code Reason
200 OK
400 Invalid address parameter
403 Not authorized
500 Internal server error

5.2 Address auto-completion

5.2.1 Prerequisites

5.2.2 Zip auto-completion

GET request

https://wedec.post.ch/api/address/v1/zips?zipCity=66&type=DOMICILE
https://wedec.post.ch/api/address/v1/zips?zipCity=66&type=POSTBOX

Response

{
“zips”:[
{“zip”:“6600”,“city18”:“Locarno”,“city27”:“Locarno”},
{“zip”:“6600”,“city18”:“Muralto”,“city27”:“Muralto”},
{“zip”:“6600”,“city18”:“Solduno”,“city27”:“Solduno”},
{“zip”:“6601”,“city18”:“Locarno”,“city27”:“Locarno”},
{“zip”:“6602”,“city18”:“Muralto”,“city27”:“Muralto”},
{“zip”:“6604”,“city18”:“Locarno”,“city27”:“Locarno”},
{“zip”:“6605”,“city18”:“Locarno”,“city27”:“Locarno”},
{“zip”:“6605”,“city18”:“Monte Brè Locarno”,“city27”:“Monte Brè sopra Locarno”},
{“zip”:“6611”,“city18”:“Crana”,“city27”:“Crana”},
{“zip”:“6611”,“city18”:“Gresso”,“city27”:“Gresso”},
{“zip”:“6611”,“city18”:“Mosogno”,“city27”:“Mosogno”},
{“zip”:“6612”,“city18”:“Ascona”,“city27”:“Ascona”},
{“zip”:“6613”,“city18”:“Porto Ronco”,“city27”:“Porto Ronco”},
{“zip”:“6614”,“city18”:“Brissago”,“city27”:“Brissago”},
{“zip”:“6614”,“city18”:“Isole di Brissago”,“city27”:“Isole di Brissago”},
{“zip”:“6616”,“city18”:“Losone”,“city27”:“Losone”},
{“zip”:“6618”,“city18”:“Arcegno”,“city27”:“Arcegno”},
{“zip”:“6622”,“city18”:“Ronco sopra Ascona”,“city27”:“Ronco sopra Ascona”},
{“zip”:“6631”,“city18”:“Corippo”,“city27”:“Corippo”},
{“zip”:“6632”,“city18”:“Vogorno”,“city27”:“Vogorno”}
]
}

5.2.3 Street name auto-completion

GET request

https://wedec.post.ch/api/address/v1/streets?name=Via+Se
https://wedec.post.ch/api/address/v1/streets?name=Via+
Se&zip=6600

Response

{
“streets”:[
“Via Sempione”,
“Via Serafino Balestra”
]
}

5.2.4 House number auto-completion

GET request

https://wedec.post.ch/api/address/v1/houses?zip=6600&streetName=Via+Serafino+Balestra&number=2

Response

{
“houses”:[“1”,“1 A”,“2”,“3”,“4”,“5”,“6”,“7”,“8”,“9 A”]
}

5.2.5 Error codes

Code Reason
200 OK
400 Incomplete/invalid search parameters
403 Not authorized
404 No results found
500 Internal server error

6 Delivery

6.1 Delivery days query

6.1.1 Prerequisites

6.1.2 The deliverabilities at Serafino Balestra 20, 6600 Locarno for the next 3 days

GET request

https://wedecint.post.ch/api/delivery/v1/deliverabilities/when?
address.geographicLocation.house.street=Serafino+Balestra&
address.geographicLocation.house.houseNumber=20&
address.geographicLocation.zip.zip=6600&
address.geographicLocation.zip.city=Locarno&
dayCount=3

Response

{
“days”:[
{
“deliveryDate”:“2014-11-17”,
“deliverabilities”:[],
“activity”:“NO_SERVICE”
},
{
“deliveryDate”:“2014-11-18”,
“deliverabilities”:[
{“incomingDate”:“2014-11-17”,“productCode”:“PRI”},
{“incomingDate”:“2014-11-17”,“productCode”:“SEM”}],
{“incomingDate”:“2014-11-18”,“productCode”:“AZS,DIR”},
{“incomingDate”:“2014-11-17”,“productCode”:“AZS,PRI”}],
“activity”:“WORK”
},
{
“deliveryDate”:“2014-11-19”,
“deliverabilities”:[
{“incomingDate”:“2014-11-17”,“productCode”:“ECO”},
{“incomingDate”:“2014-11-18”,“productCode”:“PRI”},
{“incomingDate”:“2014-11-18”,“productCode”:“SEM”},
{“incomingDate”:“2014-11-19”,“productCode”:“AZS,DIR”},
{“incomingDate”:“2014-11-18”,“productCode”:“AZS,PRI”},
{“incomingDate”:“2014-11-17”,“productCode”:“AZS,ECO”}],
“activity”:“WORK”
},
{
“deliveryDate”:“2014-11-20”,
“deliverabilities”:[
{“incomingDate”:“2014-11-18”,“productCode”:“ECO”},
{“incomingDate”:“2014-11-19”,“productCode”:“PRI”},
{“incomingDate”:“2014-11-19”,“productCode”:“SEM”}],
“activity”:“WORK”
}
],
“quality”:“RELIABLE”
“deliveryToTheDoor”:“AVAILABLE”
}

6.1.3 The deliverabilities at 6600 Locarno (default date of first day = today, default day count = 14)

GET request

https://wedec.post.ch/api/delivery/v1/deliverabilities/when?address.geographicLocation.zip.zip=6600&address.
geographicLocation.zip.city=Locarno
https://wedec.post.ch/api/delivery/v1/deliverabilities/when?address.geographicLocation.zip.zip=6600&address.
geographicLocation.zip.city=Locarno&date=2014-11-17&dayCount=2
https://wedec.post.ch/api/delivery/v1/deliverabilities/when?address.geographicLocation.zip.zip=6600&address.
geographicLocation.zip.city=Locarno&dayCount=2

Response

{
“days”:[
{
“deliveryDate”:“2014-11-17”,
“deliverabilities”:[],
“activity”:“NO_SERVICE”
},
{
“deliveryDate”:“2014-11-18”,
“deliverabilities”:[
{“incomingDate”:“2014-11-17”,“productCode”:“PRI”},
{“incomingDate”:“2014-11-17”,“productCode”:“SEM”}],
“activity”:“WORK”
},
{
“deliveryDate”:“2014-11-19”,
“deliverabilities”:[
{“incomingDate”:“2014-11-17”,“productCode”:“ECO”},
{“incomingDate”:“2014-11-18”,“productCode”:“PRI”},
{“incomingDate”:“2014-11-18”,“productCode”:“SEM”}],
“activity”:“WORK”
}
],
“quality”:“RELIABLE”
“deliveryToTheDoor”:“AVAILABLE”
}

6.1.4 The deliverabilities at 6959 Piandera Paese for the given delivery dates

GET request

https://wedec.post.ch/api/delivery/v1/deliverabilities/when?
address.geographicLocation.zip.zip=6959&
address.geographicLocation.zip.city=Piandera+Paese&
deliveryDates=2014-12-24&
deliveryDates=2014-12-25

POST request

https://wedecint.post.ch/api/delivery/v1/deliverabilities/when

POST payload

{
“address”: {
“geographicLocation”: {
“zip”: {
“zip”: 6959,
“city”: “Piandera Paese”
}
}
},
“deliveryDates”: [“2014-12-24”,“2014-12-25“]
}

Response

{
“days”:[
{
“deliveryDate”:“2014-12-24”,
“deliverabilities”:[
{“incomingDate”:“2014-12-22”,“productCode”:“ECO”},
{“incomingDate”:“2014-12-23”,“productCode”:“PRI”},
{“incomingDate”:“2014-12-23”,“productCode”:“SEM”}],
“activity”:“WORK”
},
{
“deliveryDate”:“2014-12-25”,
“deliverabilities”:[],
“activity”:“HOLIDAY”}
],
“quality”:“RELIABLE”
“deliveryToTheDoor”:“AVAILABLE”
}

6.1.5 Error codes

Code Reason
200 OK
403 Not authorized
404 No results found
500 Internal server error

6.2 Logistic product information query

6.2.1 Prerequisites

6.2.2 The information for the logistic product “PRI”

GET request

https://wedec.post.ch/api/delivery/v1/deliverabilities/how/PRI

Response

{
“productCode”:“PRI”,
“barcode”:“0509”,
“deliveryInstructions”:[
{“code”:“3211”},{“code”:“3212”},{“code”:“3213”},{“code”:“3214”},{“code”:“3215”},{“code”:
“3216”},
{“code”:“3217”},{“code”:“3218”},{“code”:“3219”},{“code”:“3220”},{“code”:“3222”},{“code”:
“3232”},
{“code”:“3233”},{“code”:“3234”}],
“additionalServices”:[
{“code”:“BLN”,“mandatory”:false},
{“code”:“COLD”,“mandatory”:false},
{“code”:“RMP”,“mandatory”:false},
{“code”:“SP”,“mandatory”:false},
{“code”:“MAN”,“mandatory”:false},
{“code”:“FRA”,“mandatory”:false},
{“code”:“AS”,“mandatory”:false},
{“code”:“SI”,“mandatory”:false},
{“code”:“LQ”,“mandatory”:false}]
}

6.2.3 Other logistic products

GET request

https://wedec.post.ch/api/delivery/v1/deliverabilities/how/ECO
https://wedec.post.ch/api/delivery/v1/deliverabilities/how/SEM

6.2.4 Error codes

Code Reasom
200 OK
403 Not authorized
404 No results found
500 Internal server error

6.3 Additional services information query

6.3.1 Prerequisites

6.3.2 Information for all additional services

 

GET request

https://wedec.post.ch/api/delivery/v1/options/additionalservices

Response

[
{
“code”:“BLN”,
“name”:{
“de”:“BLN”,
“fr”:“BLN”,
“it”:“BLN”,
“en”:“BLN”},
“barcode”:“0341”
},
{“code”:“COLD”,“name”:{“de”:“COLD”,“fr”:“COLD”,“it”:“COLD”,“en”:“COLD”},“barcode”:“
3781”},
{“code”:“RMP”,“name”:{“de”:“RMP”,“fr”:“RMP”,“it”:“RMP”,“en”:“RMP”},“barcode”:“0322”},
{“code”:“SP”,“name”:{“de”:“SP”,“fr”:“SP”,“it”:“SP”,“en”:“SP”},“barcode”:“0309”},
{“code”:“MAN”,“name”:{“de”:“MAN”,“fr”:“MAN”,“it”:“MAN”,“en”:“MAN”},“barcode”:“0421”},
{“code”:“FRA”,“name”:{“de”:“FRA”,“fr”:“FRA”,“it”:“FRA”,“en”:“FRA”},“barcode”:“0310”},
{“code”:“AS”,“name”:{“de”:“AS”,“fr”:“AS”,“it”:“AS”,“en”:“AS”},“barcode”:“0308”},
{“code”:“SI”,“name”:{“de”:“SI”,“fr”:“SI”,“it”:“SI”,“en”:“SI”},“barcode”:“0307”},
{“code”:“LQ”,“name”:{“de”:“LQ”,“fr”:“LQ”,“it”:“LQ”,“en”:“LQ”},“barcode”:“0549”},
{“code”:“SA”,“name”:{“de”:“SA”,“fr”:“SA”,“it”:“SA”,“en”:“SA”},“barcode”:“0543”},
{“code”:“AZS”,“name”:{“de”:“AZS”,“fr”:“AZS”,“it”:“AZS”,“en”:“AZS”},“barcode”:“0581”}
]

6.4 Delivery instructions information query

6.4.1 Prerequisites

6.4.2 Information for all delivery instructions

GET request

https://wedec.post.ch/api/delivery/v1/options/deliveryinstructions

Response

[
{
“code”:“3211”,
“barcode”:“3211”,
“name”:{
“de”:“Sendung dem Empfänger direkt auf der Etage zustellen”,
“fr”:“Sendung dem Empfänger direkt auf der Etage zustellen”,
“it”:“Sendung dem Empfänger direkt auf der Etage zustellen”,
“en”:“Sendung dem Empfänger direkt auf der Etage zustellen”},
“editable”:false,
“placeHolderNames”:[],
“optionNames”:[]
},
...
]

6.4.3 Error codes

Code Reasom
200 OK
403 Not authorized
404 No results found
500 Internal server error

6.5 Holidays query

6.5.1 Prerequisites

6.5.2 The list of holidays

GET request

https://wedec.post.ch/api/delivery/v1/options/holidays

Response

[
{
“date”:“2014-12-24”,
“name”:{
“de”:“Weihnachten”,
“fr”:“Weihnachten”,
“it”:“Weihnachten”,
“en”:“Weihnachten”}
},
...
]

6.5.3 Error codes

Code Reasom
200 OK
403 Not authorized
404 No results found
500 Internal server error

7 PickPost / My Post 24

7.1 Get PickPost ID or My Post 24 ID for a specific user

7.1.1 Prerequisites

  • OAuth access token for scope WEDEC_PICKPOST. This scope does not require the consent of the end user and can be obtained from:
    - an authorization code grant flow
    - an implicit grant flow
    - a client credential grant flow
  • Bearer access token stored in the header of the request:Authorization:
    Bearer <OAuth access token>
  • Integration of the “Location search” map application:
    - Fill the registration form for the “Location search”. You then receive the “Location search” API key.
    - You need to obtain a Google Maps API key. Registration with Google is a necessary prerequisite for this.
    - Make the necessary changes in the HTML code in order to integrate the Swiss Post location search into your website.
    - You can find a detailed manual for the integration of the “Location search” map application here.
  • PickPost API | INT | https://wedecint.post.ch/doc/swagger/index.html?url=https://wedecint.post.ch/doc/api/pickpost/v1/swagger.yaml

7.1.2 Retrieve the PickPost ID (or My Post 24 ID) of a customer

POST request

https://wedecint.post.ch/api/pickpost/v1/users

POST payload

{
“userDetails”: {
“gender”: “MALE”,
“firstName”: “Test”,
“lastName”: “User”,
“language”: “DE”
},
“address”: {
“house”: {
“street”: “Bellerivestrasse”,
“houseNumber”: “5”
},
“zip”: {
“zip”: “8008”,
“city”: “Zürich”,
“countryCode”: “CH”
}
},
“notification”: {
“notifyMode”: “EMAIL”,
“email”: “testuser1@post.ch”
},
“service”: “PICKPOST”
}

Response

{
“id”: “PT011227”,
“verified”: “NONE”
}

7.1.3 Error codes

 Code Reason
200 OK
403 Not authorized
500 Internal server error

8 Barcode

8.1 Prerequisites

8.2 Label formats

  • A7 format (74 ×105 mm)
  • A6 format (105 ×148 mm)
  • A5 format (148 × 210 mm): only available for Domestic Parcels, Express and Solutions

8.2.1 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.

Maximum number of address lines per DLG and format Format A7[1] Format A6[1] Format A5[1]
DLG parcel incl. any free text (up to 1 delivery instruction) 6[1] 8 8
DLG parcel incl. any free text (with 2 delivery instructions) - 6 8
DLG Express incl. any free text (up to 1 delivery instruction) 6[1] 8 8
DLG Express incl. any free text (with 2 delivery instructions) - 6 8
DLG solutions, VinoLog only incl. any free text (up to 1 delivery instruction) - 7 7
DLG solutions, VinoLog only incl. any free text (with 2 delivery instructions) - 5 7
DLG solutions, without VinoLog incl. any free text (up to 1 delivery instruction) 5[1] 7 7
DLG solutions, without VinoLog incl. any free text (with 2 delivery instructions) - 5 7
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 
Details on the address label: max. no. of address lines allowed: 8
no adjustment by WSBC required
FreeText (1st address line) FreeText
Title (2nd address line) Title
Firstname (3rd address line) Firstname Name1
Name1 (3rd address line) Name2
Name2 (4th address line) Name3
Name3 (5th address line) AddressSuffix
AddressSuffix (6th address line) Street HouseNo
Street (7th address line) ZIP City
HouseNo (7th address line) -
ZIP (8th address line) -
City (8th address line) -
Example 2: Format A6, 1 ZAW, DLG parcels
Details in the “Recipient” block + free text:
8 address lines
Details on the address label: max. no. of address
lines allowed: 6
automatic adjustment by WSBC required
FreeText (1st address line) FreeText
Title (2nd address line) Title
Firstname (3rd address line) Firstname Name1
Name1 (3rd address line) Name2
Name2 (4th address line) Name3
Name3 (5th address line) AddressSuffix
AddressSuffix (6th address line) Street HouseNo
Street (7th address line) ZIP City
HouseNo (7th address line) -
ZIP (8th address line) -
City (8th address line) -

8.3 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)

8.4 Image formats / printer languages

  • EPS
  • GIF
  • JPG (not recommended as barcode may not have high enough quality)
  • PNG
  • PDF
  • sPDF[1]
  • ZPL2
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.

8.5 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.

8.6 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 and A7.

Image formats / printer languages Average figure, only generation time in milliseconds Average including data transmission in milliseconds
EPS ~ 50 500–1000
GIF ~ 100 500–1000
JPG ~ 300 750–1500
PNG ~ 400 750–1500
PDF ~ 50 500–1000
sPDF ~ 15 300–750
ZPL2 ~ 5 300–750

8.7 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 format: 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.

8.8 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 for homologation of the labels will not be met.

Ideally you should use one of the printer models we have already homologated. To ensure adequate barcode print quality, you should always use high-quality shipping label materials. An overview of our homologated printer models is available at www.swisspost.ch/post-mypostbusiness-auftrag-druckermodelle.

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

8.9 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>
DLC Basic services
ECO PostPac Economy
PRI PostPac Priority
SP, ECO Bulky goods Economy
SP, PRI Bulky goods Priority
PPR PostPac Promo
SEM Swiss-Express “Moon”
SEM, SP Bulky goods “Moon”
SKB SameDay afternoon/evening
SKB, SP SameDay afternoon/evening bulky goods
VL VinoLog
DIRECT Direct[1]
GAS, ECO PostPac Economy GAS
GAS, PRI PostPac Priority GAS
GAS, SP, ECO Bulky goods Economy GAS
GAS, SP, PRI Bulky goods Priority GAS
GAS, SEM Swiss-Express “Moon” GAS
GAS, SKB SameDay afternoon/evening GAS
DLC Delivery instructions
ZAW3211 Direct delivery to an upper floor (A)
ZAW3212 Do not place in letterbox; deliver manually or notify (B)
ZAW3213 Notify delivery by telephone (C)
ZAW3214 Place in letterbox or at front door (D)
ZAW3215 Deliver contents; take back box (K)
ZAW3216 Failed delivery; return item as priority on the same day (E)
ZAW3217 Specific delivery date, deliver on ... (F)
ZAW3218 Deliver when all items have arrived (G)
ZAW3219 Deposit item (H)
ZAW3220 Follow delivery information in document pouch (I)
ZAW3222 Present item; leave in cellar (L)
ZAW3232 You require a contract with Post CH Ltd[3]
ZAW3233 Exchange/Return[4]
ZAW3234 Do not deliver to mailbox or neighbour: do not leave anywhere
DLC Additional services
FRA Fragile
MAN Manual processing
RMP Personal delivery
SI Signature
AS Signature (insurance)
COLD Disposet Cold
BLN Electronic COD
LQ Limited Quantities (hazarouds goods)
SA Saturday delivery
AZS Evening delivery[2]
ZFZ0912 Time slot delivery 9 –12[2]
ZFZ1114 Time slot delivery 11–14[2]
ZFZ1316 Time slot delivery 13–16[2]
ZFZ1518 Time slot delivery 15–18[2]
DLC Combination code (comprising multiple DLC)
PRISI PRI + SI
PRIAZS PRI + AZS
PRIAZSI PRIORITY + AZS + SI (NB: only one S in DLC)
DIRAZS DIRECT + AZS
DIRAZSI DIRECT + AZS + SI (NB: only one S in DLC)
PRI0912 PRI + ZFZ0912
PRI1114 PRI + ZFZ1114
PRI1316 PRI + ZFZ1316
PRI1518 PRI + ZFZ1518
PRISI09 PRI + SI + ZFZ0912
PRISI11 PRI + SI + ZFZ1114
PRISI13 PRI + SI + ZFZ1316
PRISI15 PRI + SI + ZFZ1518

1
   Basic service DIRECT can only be used in conjunction with AZS.
2   When using the AZS (Evening delivery) and ZFZ (Time slot delivery) value-added services, we recommend you first perform an area check for each recipient address via your connection to the Digital Commerce API – Swiss Post shipping options.
3   For the collection of empty containers or materials for recycling – please contact your customer advisor for further information.
4   Only available in conjunction with notification service code 128 (“Exchange/return”).

8.10 Generate Label request (Generate Label)

Element Cardinality Type Description Example (if appropriate)
GenerateLabel 1..1 GenerateLabel Root element of Generate address label operation -
Language 1..1 Enumeration (de, fr, it, en) Language in which the service is activated de
Envelope 1..1 GenerateLabelEnvelope Content holder -
LabelDefinition 1..1 GenerateLabelDefinition Content holder with address label details -
LabelLayout 1..1 String (2, [a-zA-Z,0-9]{2}) Address label layout A5
PrintAddresses 1..1 Enumeration (None, OnlyRecipient, OnlyCustomer, RecipientAndCustomer) Details on the printing of sender’s and recipient’s address (delivery note)
None – no addresses are printed 
OnlyRecipient – only the recipient’s address is printed
OnlyCustomer – only the customer’s address is printed
RecipientAndCustomer – Both the sender’s and the recipient’s addresses are printed
OnlyRecipient
ImageFileType 1..1 String (1..5,[a-zA-Z,0-9]{1,5}) Address label file format PDF
ImageResolution 1..1 Integer Address label resolution in DPI (dots per inch) 300
PrintPreview 1..1 Boolean PrintPreview enabled/disabled (SPECIMEN lettering from the label generated) true
FileInfos 1..1 GenerateFileInfos Content holder -
FrankingLicense[2] 1..1 String (4..8,[a-zA-Z,0-9]{4} or [0-9]{6} or [0-9]{8}) Customer franking licence number or postcode -
PpFranking[4] 1..1 Boolean Indicates whether the PP flag has been set or not true
CustomerSystem 0..1 String(0..255), [a-zA-Z,0-9,\s]{1,255} Indicates optional parameters for customer system names AVG Client
Customer 1..1 GenerateCustomer Content holder with customer details. Refers to the sender’s customer -
Name1 1..1 String (0..25) First name and surname, or company name Meier AG
Name2 0..1 String (0..25) Additional name 1 (company suffix or department) General
Agency
Street 1..1 String (0..25) Address (house number and street) Viktoriaplatz 10
POBox 0..1 String (0..25) P.O. Box P.O. Box 4021
ZIP 1..1 Integer (0..6) Postcode 8048
City 1..1 String (0..25) Place Zurich
Country 0..1 (2,[a-zA-Z]{2}) Country as two-digit ISO-3166-1-alpha-2 code CH
Logo 0..1 Binary (Base64) Binary customer logo -
LogoFormat 0..1 String (3) Logo format GIF
LogoRotation 0..1 Enumeration (0, 90, 180, 270) Clockwise rotation 270
LogoAspectRatio 0..1 Enumeration (EXPAND, KEEP) Aspect ratio (width to height) EXPAND
LogoHorizontalAlign 0..1 Enumeration (WITH_CONTENT, LEFT) Horizontal alignment WITH_CONTENT
LogoVerticalAlign 0..1 Enumeration (TOP, MIDDLE) Vertical alignment TOP
DomicilePostOffice 0..1 String (0..35) Domicile Post Office 3097 Liebefeld
Data 1..1 GenerateData Content holder -
Provider 1..1 GenerateProvider Content holder -
Sending 1..1 GenerateSending Content holder -
SendingID 0..1 String (0..50) ID assigned by customer at request level is returned unchanged in the response.
If no SendingID is supplied, WSBC generates a random number.
-
Item 1..n GenerateItem Content holder per address label -
ItemID[2] 0..1 String (0..200) ID assigned by customers at address label level will be returned unchanged in the response -
ItemNumber[2] 0..1 String (0..8,[0-9]{1,8}) Mailing number 12345678
IdentCode[2] 0..1 String (13..23, [0-9]{18} or [0-9]{23} or [a-zA-Z,0-9]{13}) Mailing code. For use by Swiss Post internal systems only. In systems external to Swiss Post this field is ignored and a warning returned. 9934123456
12345678
Recipient[3] 1..1 Generate
Recipient
Content holder with recipient details -
PostIdent 0..1 String (0..15) Postal identification -
Title 0..1 String (0..35) Salutation Ms
PersonallyAddressed 0..1 Boolean When set to FALSE, indicates the company first, then the recipient, on the address label Toggles to TRUE Default True. True
Firstname 0..1 String (0..35) First name of recipient Melanie
Name1 1..1 String (0..35) Last name and first name (if not in Firstname) Steiner
Name2 0..1 String (0..35) Additional name 1 (company suffix, department or keyword & PickPost / My Post 24 UserID) Marketing
Dept. or
PickPost
12345678
Name3 0..1 String (0..35) Additional name 2 (Attn/FAO; c/o or department [if not in Name2]) Attn/FAO
Hans Meier
AddressSuffix 0..1 String (0..35) Additional name address East building
Street[1] 0..1 String (0..35) Street Viktoriastrasse
HouseNo 0..1 String (0..10) House number 21
PoBox[1] 0..1 String (0..35) Name “P.O. box” and – if available – P.O. box number P.O. Box 4021
FloorNo 0..1 String (0..5) Floor number (data transfer only, not printed on address labels) 3a
MailboxNo 0..1 Integer (0..10) Letter box number (data transfer only, not printed on address labels) 10
ZIP 0..1 String (0..10) Postcode 3030
City 1..1 String (0..35) Place Berne 1
Country 0..1 String (2,[a-zA-Z]{2}) Country – two-digit ISO 3166-1-alpha-2 code CH
Phone 0..1 String (0..20) Telephone number (for delivery instruction 3213) 031 338 11 11
Mobile 0..1 String (0..20) Mobile number (for delivery instruction 3213) 031 338 11 11
Email 0..1 String (0..160) E-mail address h.muster@post.ch
LabelAddress 0..1 LabelAddress Used in order to display the address lines in a customized order, or to specifically abbreviate long addresses. The postcode and location are taken across from the “Recipient” address block. -
LabelLine 2..5 String (0..35) Contents of the recipient address lines, min. 2 and max. 5 address lines (the postcode and location fields are automatically taken across from the “Recipient” address block. -
AdditionalINFOS 0..1 GenerateAdditionalINFOS Content holder -
AdditionalData 0..20 GenerateAdditionalData Content holder -
Type 1..1
1..1
String (0..35) General keys for electronic cash on delivery (BLN) COD amount in CHF
Additional keys for BLN with ISR ISR reference number
NN_BETRAG
NN_ESR_REFNR
Value 1..1 String (0..50) Value for additional information, must be separated by decimal point (comma not allowed) 150.50
Attributes
0..1 GenerateAttributes Content holder -
PRZL 1..n String (1..7,[a-zA-Z,0-9]{1,7}) Service code (DLC) ECO, PRI, SP
FreeText 0..1 String (0..34) Free text for recipient address Thank you for your order
DeliveryDate 0..1 Date Delivery date (for delivery instruction 3217) 2009-08-20
ParcelNo 0..1 Integer (0..99) Parcel number of total (for delivery instruction 3218) 2
ParcelTotal 0..1 Integer (0..99) Total number of parcels (for delivery instruction 3218) 5
DeliveryPlace 0..1 String (0..35) Drop point (for delivery instruction 3219) At front door
ProClima 0..1 Boolean Printing of ProClima logo -
Dimensions 0..1 Dimensions Content holder for dimensions -
Weight 0..1 Integer (0..99’999) Weight in grams (limited to 5 digits) for Parcels, Express and Solutions service groups 12500
UNNumbers 0..1 - Content holder for UN number for the “LQ” (hazardous goods) additional service -
UNNumber 0..n Integer (0..9’999) List of UN numbers (limited to 4 digits) for “LQ” additional service (hazardous goods) 1234, 1235, 1236
Notification 0..15 Generate Notification List of notification services -
Type 1..1 String (Mail, SMS) Means of communication SMS or EMAIL
Service 1..1 Integer (0..20) Service code 1, 2, 128
FreeText1 0..1 String (0..160) Free text 1 Test 1
FreeText2 0..1 String (0..512) Free text 2 Test 2
Language 1..1 Language Language DE, FR, IT or EN
Communication 1..1 Generate-Communication Content holder for communication medium Email or Mobile
Email 0..1 String (0..160) E-mail address a@b.ch
Mobile 0..1 String (9..20) Mobile number +41791234567

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 and IdentCode 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: 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.

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

BLN-defined transaction types

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 Web Service Support for further information.

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

  1. Yellow Account with inpayment slip (IS) from PostFinance, with upper limit on domestic transactions.
  2. By Swiss Post ISR.

With transaction type 1 (yellow Account IS) only the COD amount is required. With transaction type 2 (Swiss Post ISR) both the COD amount and the ISR reference number is required.

ISR reference number

For the ISR reference number, the following data format is valid (excerpt from the PostFinance manual on “Record Structures – electronic Services”) www.postfinance.ch/content/dam/pf/de/doc/consult/manual/dldata/efin_recdescr_man_en.pdf

  • Reference number
  • 84 
  • 9(27) 
  • For 5-digit ISR customer numbers 000000000000999999999999999
  • For 9-digit ISR customer numbers 99999999999999999999999999P
  • Mandatory: The reference number is printed on the processing document in blocks of 5, whereby leading zeros can be suppresses. The details must be entered in the field with right alignment, empty positions must be extended with leading zeros. Reference numbers with the value “0” (zero) will be rejected. We recommaned that you recalculate and compare the check digit (modulo 10, recursive).
Yellow Account with inpayment slip (TransactionType 1)
Element Cardinality Type Description Example (if appropriate)
AdditionalINFOS 0..1 - Content holder -
AdditionalData 0..20 - Content holder -
Type 1..1 String (0..35) Field for COD amount NN_BETRAG
Value 1..1 String (0..50) COD amount, must be separated by decimal point (comma not allowed) 150.50
Type 1..1 String (0..35) Field for ISR reference number NN_ESR_REFNR
Value 1..1 String (0..50) Reference number Reference number

8.10.2 Notification services

Notification code

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

Notification Code
Proof of posting 1
Delivery information 2
Collection information 4
Reminder to recipient 32
Handover status to sender 64
“Exchange/return” 128[1]
Saturday delivery 256[2]
Evening delivery following days 257[3]
Evening delivery same day 258[4]

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”.

3
   This notification service can only be used with the additional service “AZS” and the basic service PostPac Priority, bulky goods Priority, PostPac Economy or bulky goods Economy.

4
   This notification service can only be used with the additional service “AZS” and the basic services SameDay afternoon/evening, SameDay afternoon/evening bulky goods or “Direct”.
Notification text messages

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

8.11 Retrieve the Barcode Label

POST request

https://wedecint.post.ch/api/barcode/v1/generateAddressLabel

POST payload

{
“language”:”DE”,
“frankingLicense”: “35900034”,
“customer”: {
“name1”: “Test Kunde”,
“street”: “Wankdorfallee 4”,
“zip”: “3030”,
“city”: “Bern”,
“domicilePostOffice”:”3011 Bern”,
“country”: “CH”
},
“labelDefinition”: {
“labelLayout”: “A6”,
“printAddresses”: “RECIPIENT_AND_CUSTOMER”,
“imageFileType”: “JPG”,
“imageResolution”: 300
},
“item”:
{
“itemID”: “1234567”,
“recipient”: {
“name1”: “Hans”,
“name2”: “Muster”,
“street”: “Wankdorfallee”,
“houseNo”: “4”,
“zip”:”3030”,
“city”: “Bern”,
“country”: “CH”
},
“attributes”: {
“przl”: [“PRI”,”SA”],
“weight”:12345
}
}
}

Response

{
“labelDefinition” : {
“labelLayout” : “A6”,
“imageFileType” : “jpg”,
“imageResolution” : 300,
“printPreview” : false,
“colorPrintRequired” : true
},
“item” : {
“itemID” : “1234567”,
“identCode” : “993590003400000002”,
“label” : [ “<Base64Image>” ]
}
}

8.11.1 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.

Error code Error message (English)
E1000 The desired combination of the basic service codes ({0}) is invalid.
E1001 The desired additional services ({0}) cannot be combined with the requested basic service ({1}).
E1002 The requested additional services ({0}) cannot be combined with each other.
E1003 The desired delivery instructions ({0}) cannot be combined with the requested basic service ({1}).
E1004 The desired delivery instructions ({0}) cannot be combined with the requested additional services ({1}).
E1005 The requested delivery instructions ({0}) cannot be combined with each other.
E1006 The stated number of basic and additional service codes ({0}) exceeds the maximum number of presentable service codes for the desired presentation type. Please reduce the number of service codes or choose a larger presentation format.
E1007 The stated number of delivery instructions ({0}) exceeds the maximum number of presentable delivery instructions for the desired presentation type. Please reduce the number of delivery instructions or choose a larger presentation format.
E1008 The desired service group is invalid.
E1009 The desired basic service is invalid.
E1011 The stated presentation type ({0}) is invalid.
E1012 The stated service code ({0}) is invalid for the desired service group ({1}).
E1013 The stated presentation type ({0}) is invalid for the desired service group ({1}).
E1014 An additional service with COD amount must be selected (BLN).
E1015 No valid basic service codes could be found in the list of service codes ({0}).
E1016 The presentation time ({0}) is invalid for the basic service selected ({1}).
E2001 A valid recipient address must be stated.
E2002 A domicile post office must be provided.
E2003 The COD amount must be provided for COD items (BLN).
E2004 The ISR reference number for the electronic COD (BLN) is invalid. Please check the format and check digit.
E2005 A telephone number must be provided for the delivery instruction “Notify delivery by telephone” (ZAW3213).
E2006 A valid delivery date must be stated for the delivery instruction “Specific delivery date: deliver on ...” (ZAW3217).
E2007 A “parcel number” and a “parcel total” must be provided for the delivery instruction “Deliver when all items have arrived” (ZAW3218).
E2008 A “deposit point” must be provided for the delivery instruction “Deposit consignments” (ZAW3219).
E2009 No franking licence was indicated.
E2010 This account is not authorized to purchase addresses for the franking licence ({0}).
E2011 The consignment number provided is outside the area of validity (1–{0}).
E2012 The desired picture format ({1}) is not offered. Please select a valid picture format ({1}).
E2013 The desired resolution ({0} dpi) is not offered. Please select a valid picture format ({1}).
E2014 VinoLog deliveries are not possible for the desired recipient postcode ({0}).
E2015 VinoLog deliveries in combination wtih evening delivery (ZAW3229) are not possible for the desired recipient postcode ({0}).
E2016 The consignment number provided is not unique.
E2017 A valid sender address must be stated.
E2018 The indicated sender logo format ({0}) is not permitted.
E2019 The sender logo exceeds the maximum size of {0} KB.
E2020 The COD amount is outside the valid range.
E2021 Two COD amounts were indicated. Please indicate the amount for COD items (N) in the “ATT_Amount” field and in the “REC_DATA” field for electronic COD items (BLN).
E2024 The sender logo could not be scanned. Please check that it conforms to a valid picture format ({0}).
E2025 A P.O. box address must be specified.
E2026 The franking licence used ({0}) is not authorized for the basic service ({1}) of the service group ({2}).
E2027 The franking licence used ({0}) is not the correct length.
E2028 {0} is not a valid ISO country code.
E2029 Additional service {0} is not permitted for mailings to {1} or only in combination with another additional service.
E2030 Basic service {0} does not belong to an international service group.
E2031 Basic service {0} does not belong to a domestic service group.
E2032 For domestic mailings the addressee’s postcode must be specified.
E2033 For domestic mailings the addressee’s postcode must consist of digits only.
E2034 For domestic mailings the addressee’s postcode must not exceed the maximum length of {0} characters.
E2035 This franking licence ({0}) is not a customer franking licence and a valid consignment barcode must therefore be specified.
E2036 The weight should be express as a maximum of 5 digits and should not amount to more than {0} grams (e.g.29500).
E2037 The weight must be a value great than 0.
E2038 The UN number must be exactly 4 digits (e.g. 1234).
E2039 The LQ additional service is only available from Version 2.1 onwards.
E2040 The notification service {0} cannot be combined with the basic service {1}.
E2041 The e-mail address ({0}) must correspond to the following pattern {1}.
E2042 The telephone number ({0}) must be between 10 and 20 digits long and must begin with {1}, {2} or {3}. Numbers and spaces are permitted; hyphens (-) or forward slashes (/) or other special characters (|, \, ^, etc.) are not permitted. 
E2043 For the {0} notification the delivery instruction {1} is required.
E2044 For the {0} delivery instruction the notification {1} is required.
E2045 The following characters only are permitted in the Item ID: A to Z (and a to z), numbers 0 to 9, underscore “_”, hyphen “-”, plus sign “+”.
E2047 The communication type (e-mail or SMS) does not match the telephone number or e-mail address given.
E2049 For COD items (BLN), a valid ISR customer number (NN_ESR_KNDNR) must be set.
E2050 For COD items (BLN), a valid IBAN number (NN_IBAN) must be set.
E2051 For COD items (BLN) with IBAN, a valid name for the end beneficiary (NN_END_NAME_VORNAME) must be set.
E2052 For COD items (BLN) with IBAN, a valid additional description for the end beneficiary (NN_END_ZUSATZ_NAME) must be set.
E2053 For COD items (BLN) with IBAN, a valid street (NN_END_STRASSE) must be set.
E2054 For COD items (BLN) with IBAN, a valid postcode (NN_END_PLZ) must be set.
E2055 For COD items (BLN) with IBAN, a valid city (NN_END_ORT) must be set.
E2056 For COD items (BLN) with IBAN or ISR account number (NN_ESR_KNDNR), a valid sender contact e-mail address (NN_CUS_EMAIL) must be specified.
E2057 For COD items (BLN) with IBAN or ISR account number (NN_ESR_KNDNR), a valid sender contact phone number (NN_CUS_PHONE or NN_CUS_MOBILE) must be specified.
E2058 For COD items (BLN), a combination of ISR and IBAN fields is not permitted.
E2059 The basic service {0} can only be used in conjunction with the value-added service {1}.
E2060 The notification service {0} can only be used together with the value-added service {1}.
E2061 The recipient address could not be determined – check for evening delivery not possible.
E2062 Evening delivery for this address not part of the offer.
E2063 The checking of the evening delivery cannot be carried out at the moment. Please contact Support.
E2064 At least two LabelLines are required. LabelLines that are blank or only contain empty spaces are not permitted.
E2065 The checking of the evening delivery cannot be carried out at the moment. Please contact Support.
E9991 The output format for single barcodes is currently not supported.
E9992 No valid web service call!
E9993 The Zubofi system is currently not available. Please try again later.
E9994 The Kurepo system is currently not available. Please try again later.
E9995 The output format ({1}) is currently not supported in resolution ({0} dpi).
E9996 Too many addressees were requested. A maximum of {3} addressees per request can be generated with the resolution ({0} dpi), output format ({1}) and addressee format ({2}).
E9997 The web service barcode was unable to generate a unique consignment number. If the problem reoccurs, please contact the Support team.
E9998 User {0} is not authorized for this service.
E9999 The service is not available at the moment.

8.11.2 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.

Warning code Warning (English)
W2003 You have indicated a COD amount without requesting the additional service “COD” (BLN).
W2004 You have indicated an ISR reference number without requesting the additional service “Electronic COD” (BLN).
W2005 You have indicated a telephone number without requesting the delivery instruction “Notify delivery by telephone” (ZAW3213).
W2006 You have indicated a delivery date without requesting the delivery instruction “Specific delivery date: delivery on ...” (ZAW3217).
W2007 You have indicated a parcel number and/or a parcel total without requesting the delivery instruction “Deliver when all consignments have arrived” (ZAW3218).
W2008 You have indicated a deposit point without requesting the delivery instruction “Deposit consignments” (ZAW3219).
W2009 A text cannot be generated with the requested presentation type ({0}); the display will be suppressed. To display a text, please select a larger presentation type.
W2010 Generation of the addressee will require too much time with the requested presentation type ({0}) and resolution ({1}).
W2011 PP franking is ignored for the basic service {0}.
W2012 For in-house Swiss Post applications the weight field is optional. The weight field has not been filled in correctly (max. {0} grams, greater than or the same as 0) and has therefore not been returned.
W2013 Free text 2 cannot be used with SMS notifications. Free text 2 has been ignored.
W2014 Free text is not required in the notification {0}. Free text 1 and 2 have been ignored.
W2015 No delivery information can be found for these address details. Please ensure that your address details are correct and complete.
W2016 For the chosen presentation type the recipient is restricted to {0} lines. The title will be ignored. To display the title, please select a larger presentation type.
W2017 For the chosen presentation type the recipient is restricted to {0} lines. The AddressSuffix will be ignored. To display the AddressSuffix, please select a larger presentation type.
W2018 For an A6 label with 2 ZAWs, the sender’s address is truncated to 20 characters per line in ZPL2 format.
W2019 For the chosen presentation type the recipient is restricted to {0} lines. Name3 will be ignored. To display Name3, please select a larger presentation type.
W2020 For the chosen presentation type the recipient is restricted to {0} lines. Free text will be ignored. To display the free text, please select a larger presentation type.
W2021 For the chosen presentation type, the recipient is restricted to {0} lines. Excessive LabelLines will be ignored. To display all LabelLines, please select a larger presentation type.
W2022 The specified weight will not be printed on the label as this information is not relevant to the selected service group.
W9997 The Consignment code field may be filled in using Swiss Post applications only.

9 Registration

A client of the Swiss Post e-commerce API must be registered at Swiss Post. No online registration feature supports the registration process at the moment.

9.1 Artifacts

Artifact
  • Client Identifier (Secret-ID)
  • Client Secret (Token-ID)
Remark

These credentials have to be communicated when ordering an access token.

9.2 Required information

Attribute Remark Related API
Domain name The domain name of the web shop Login Post Connector / Alternative Delivery Addresses
i18n client text A text for the web shop to be displayed in the consent screen Login Post Connector / Alternative Delivery Addresses
Icon An icon for the web shop to be displayed in the consent screen Login Post Connector / Alternative Delivery Addresses
redirect_uri Used for returning the data when consuming both authorization and token endpoints. Domain name of the URI is expected to be the one specified above. Login Post Connector / Alternative Delivery Addresses
scopes The scopes configured for a client. Every scope gives access to an endpoint or to a set of personal attributes (OpenID). The end user may have to give his consent during the OAuth authorization flows. all

10 CORS

Cross Origin Resource Sharing is a relaxing technique for the cross origin policy. This policy is imposed by web browsers in order to minimize cross origin problems. It does not concern requests initiated on the server side.

Any client who wants to consume an endpoint of the Swiss Post e-commerce API from the client-side (for example with Javascript) will face the cross origin policy because the domains where the client and the Swiss Post e-commerce API are running are different.

The domain of the client must be registered in the CORS configuration of the API proxy server. This step is part of the registration process.

11 Versioning

Every endpoint of the Swiss Post e-commerce API has a version ww.xx.yy.zz. This version is composed of a major and a minor release number. Some other number may signify hotfixes or internal builds. The major release number is part of the URL of an endpoint. The major release number is updated when backward compatibility with previous versions of the endpoint is broken. The minor release number is updated when a new method or new fields are added to the API of an endpoint which do not break the backward compatibility.

The updates of other numbers are supposed to keep the backward compatibility. Several versions of an endpoint will be deployed in parallel in order to support the latency of the clients regarding the update of their integration of the Swiss Post e-commerce API.