ZSR Webservice Specification
Status codes
The SASIS Regis uses standard http status codes.
The following status codes will generally be used by the API:
| Status Code | Description |
|---|---|
| 200 | Success |
| 202 | Accepted; Request is valid and business process could be triggered successfully. |
| 400 | Bad Request; The request data is invalid. |
| 401 | Unauthorized; The caller does not have sufficient privileges to perform the call. |
| 403 | Forbidden; The server is refusing the action. |
| 500 | Internal Server Error; Any unexpected internal failure. |
Referenced Algorithms
Clearing number check digit
The clearing number has the following structure:
- A leading char as check digit
- A four digit sequential number
- A two digit number circle / canton number
The leading char of the clearing number is created and validated as follows:
- Each number is multiplied with its position (calculate from the right end).
- All products are summarized into one sum.
- Modulo 26 of the sum denotes the char in the alphabet (result 0 results in char 'Z').
Example L248519:(9*1)+(1*2)+(5*3)+(8*4)+(4*5)+(2*6) = 9090 mod 26 = 1212th char in the alphabet = L
UID ECH0097 check digit
The ECH0097 enterprise identification number (Unternehmensidentifikationsnummer UID, Numéro d’identification des entreprises IDE, Numero d’identificazione delle imprese IDI) has the following structure:
- ISO-Alpha-3 Code (ISO 3166-1) of Switzerland (CHE)
- 8 digit pseudo random number
- check digit
The check digit is created and validated as follows:
- Each digit of the pseudo-random number is multiplied with a predefined multiplier: 54327654
- All products are summarized into one sum.
- 11 minus Modulo 11 of the sum defines the check digit.
Example CHE-114.617.288:(1*5)+(1*4)+(4*3)+(6*2)+(1*7)+(7*6)+(2*5)+(8*4) = 124124 mod 11 = 311 - 3 = 8
Authentication / Autorisation
The authentication is based on OpenID Connect, an identity layer on top of OAuth 2.0 and its corresponding flows/grants. For application integration, the resource owner password flow using the OAuth 2.0 password grant is to be used.
The SASIS IAM infrastructure acts a OpenID provider / authorization server.
- The API Client requests the token endpoint from the auth server.
- The token endpoint is returned to the API Client.
- Request an access token from the auth server by providing the following post request parameters:
- grant_type: set to 'password'
- client_id: provided individually by SASIS
- client_secret: provided individually by SASIS
- username: provided individually by SASIS
- password: provided individually by SASIS
- scope: set constantly to 'openid profile email offline_access roles c1s_profile cpr'
- The access token as well as the refresh token is returned to the API Client.
- The specific API resource is called providing the access token in as bearer in the Authorization http header:
'Authorization: Bearer <access token>' - The API responds to the request.
- Once the access token expired, the previously received refresh token is used to request a new access token from the auth server by providing the following parameters:
- grant_type: set to 'refresh_token'
- client_id: provided individually by SASIS
- client_secret: provided individually by SASIS
- scope: set constantly to 'openid profile email offline_access roles c1s_profile cpr'
- refresh_token: The refresh token received with the last access token.
- A new access token as well as a new refresh token is returned to the API Client.
- The specific API resource is called providing the new access token in as bearer in the Authorization http header:
'Authorization: Bearer <access token>' - The API responds to the request.
Access token
The access token response contains additional information:
{
"access_token": "MTQ0NjOkZmQ5OTM5NDE9ZTZjNGZmZjI3",
"refresh_token": "GEbRxBNZmQOTM0NjOkZ5NDE9ZedjnXbL",
"token_type": "bearer",
"expires_in": 300,
"scope": "openid profile email offline_access roles c1s_profile cpr"
}
The token itself is a JWT and can therefore be decoded on the JWT website.
The expires_in field defines the validity period of the token in seconds. Afterwards, a new token must be retrieved.
Code samples
A complete c# sample shows how to access one specific API resource (numbers):
Authentication in other languages follows the same procedure.
The following code snippets explain the procedure on a step-by-step basis: