ZSR (public)

Page tree

Versions Compared

Old Version 85

changes.mady.by.user Miriam Stettler

Saved on

compared with

New Version Current

changes.mady.by.user Miriam Stettler

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Sv translation
languagede


Panel
titleInhalt

Table of Contents



HTML
<div class="references">


Panel
titleLinks

ApiGateway/swagger/index.html

ApiGateway/swagger/1/swagger.json

Swagger Editor - editor.swagger.io

OpenID Connect - openid.net

OAuth - oauth.net

JSON Web Tokens - jwt.io

ReDoc - redocly.github.io

W3 Status Code Definition - w3.org

Service Level Agreement IT Services SASIS DE

Service Level Agreement IT Services SASIS FR

Service Level Agreement IT Services SASIS IT

Abo-Optionen

Release Notes

Kontakt

Mapping Abo Files - Webservice

BusinessActivityEnumListe


HTML
</div>




Integration des Webservices

Welche Daten können über den ZSR-Webservice bezogen werden?

Die über den Webservice gelieferten Daten entsprechen grundsätzlich den Daten die in den RK-Abos geliefert werden. Welche Daten abgefragt werden können ist also abhängig von den Modulen die der Kunde abonniert hat. Siehe Abo-Optionen

Daten können abgefragt werden zu ZSR-Nummern / K-Nummern, bei welchen die Sistierung nicht länger als 10 Jahre zurückliegt.


Werden die Daten in gleicher Struktur geliefert wie in den Abo-Files?

Mit dem Webservice hat sich das Datenmodell (im Vergleich zu den Abo-Files) geändert. Siehe auch auch Mapping Subscription Abo Files - Webservice.

Die wichtigsten Entitäten sind

  • CareProvider - Leistungserbringer
  • CareProviderBusiness - Standort
  • ClearingNumber - ZSR-Nummer
  • EmployeeNumber - K-Nummer


Expand
titleHauptentitäten ClearingNumber (vereinfachte Darstellung)

clearingNumber (Zahlstelle)

  • number (ZSR-Nummer)
  • correspondenceParty (Korrespondenzadresse)
  • account (Konto)
  • clearingNumberLaws (Zulassung)
  • careProvider (Leistungserbringer)
    • careProviderParties (Adressen)
    • qualifications (Qualifikationen)
    • employeeNumbers (K-Nummer)
  • careProviderBusinesses (Zahlstellen-Standorte)
    • careProviderBusinessParties (Adressen)
    • facilities (Einrichtung)
    • healthServices (Methoden)
    • affiliations (Mitgliedschaften)
  • businessScope (OG/UG)
  • businessActivity (Haupttätigkeit Ärztin/Arzt)
  • relatedClearingNumbers (zugeordnete Zahlstellen/Zusätzliche Zahlstellen)
  • relatedEmployees (Arbeitnehmer/Angestellte)
  • licenses (Kantonale Bewilligung)
  • admissions (Kantonale Zulassung)
  • tariffSystems (Tarif-Verträge)

Hinweise:
Es handelt sich um eine stark vereinfachte Darstellung - für Details siehe Swagger-Schema.
Berücksichtigt sind die Anpassungen gemäss Release Notes ZSR Webservice (24.06.22)



Weshalb wurde das Datenmodell (im Vergleich zu den Abo-Files) verändert?

Gründe für die Änderung des Datenmodells:

  • Eine Wahrheit: Das alte Datenmodell hat es zugelassen, dass für den gleichen LERB unterschiedliche Stammdaten geführt werden mussten. Dies gibt Unschärfen bei den fachlichen Daten und erschwert eine einheitliche Identifikation. Beim neuen Datenmodell wurde darauf geachtet, dass die Legacy-Daten über Zeit zusammengeführt werden können und pro LERB ein einheitlicher Datensatz geliefert wird. Der englische Arbeitsname der Applikation lautet denn auch CareProviderRegister (=Leistungserbringer-Register) und verwendet "Zahlstellenregister" nicht mehr.
  • Fachliche Daten: Das alte Datenmodell konnte nicht in allen Bereichen eine fachliche Historie anlegen. Das neue Datenmodell sorgt dafür, dass eine fachliche Historisierung aller relevanten Daten möglich ist bzw. leicht ergänzt werden kann.
  • Zukunftssicherer: Das alte Datenmodel konnte künftige Anforderungen ans Leistungserbringer-Register nur schwer abbilden. Mit dem neuen Datenmodell wurde Flexibilität geschaffen, um Änderungen der fachlichen Workflows schneller abbilden zu können.


Mit welchem Response-Format gibt der ZSR-Webservice Antwort?

Die Daten werden in JSON Format geliefert (XML wird nicht unterstützt).


Können Referenzdaten (=Stammdaten) separat geladen werden?

Stammdaten/Basisdaten zu ZSR-/K-Nummern Werten (Methoden, Qualifikationen, Banken, usf.) müssen grundsätzlich nicht separat geladen werden. Alle notwendigen Daten werden direkt in der Detail-Response zur einzelnen Nummer mitgeliefert.

Bei Bedarf können Stammdaten/Basisdaten dennoch separat wie folgt eingelesen werden:

  • Alle Enum-Werte (z.B. Gender, Canton u.a.) werden bereits im swagger.json (JSON) vollständig ausgewiesen. Mit Hilfe des SwaggerEditors oder anderer Tools lassen sich Referenz-Klassen des ZSR-Webservice samt der dazugehörigen Enum-Werte automatisch generieren.
  • Nicht als Enum-Werte im swagger.json ausgewiesen, aber über einen dedizierten ZSR-Webservice Endpoint abrufbar sind folgende Werte:
    • Affiliations (Verbandscodes)
    • BusinessScopes (PAOG/PAUG)
    • ClearingNumberSuffixes (Nummernkreise)
    • Countries (Länder)
    • Facilities (Standorteigenschaften)
    • HealthServices (Methoden)
    • Qualifications (Qualifikationen)
    • TariffSystems (Tarifsysteme)

Die eindeutige Identifikation der Stammdaten ist über das Element "key" (string) möglich. Siehe Werden technische Id's geliefert?
Beispiel: "key": "3fa85f64-5717-4562-b3fc-2c963f66afa6"



Wo finde ich die technische Dokumentation des Webservice?

Es steht eine Open API Specification zur Verfügung.

Nebst Swagger kann beispielsweise ReDoc zur Darstellung OpenAPI Specification genutzt werden: ZSRN-API Live (ReDoc).


Gibt es eine Versionierung des ZSR-Webservice?

Der ZSR-Webservice liegt in der Version v1.x vor. Alle Änderungen am Webservice werden bis auf Weiteres nicht über neue Versionen im Parallelbetrieb umgesetzt, sondern alle Anpassungen erfolgen direkt auf der Version v1.x. Jegliche Änderungen werden jedoch rechtzeitig als Release-Notes publiziert und per Stage-System zur Verfügung gestellt. Es gelten die SASIS SLA https://www.sasis.ch/sharepoint/public/service-level-agreement.pdf.

Weil eine Versionierung des ZSR-Webservice bis auf Weiteres fehlen wird, empfiehlt die SASIS AG ihren Integratoren ein Adapterpattern zu verfolgen, das über eine releaseunabhängige Parametrierung eine Anpassung der Client-System Schnittstellen zum Webservice erlaubt. 


Wie lauten die aktuellen IT-SLA der SASIS AG

Für den Webservice kommt das Service Level Agreement der SASIS IT Services zur Anwendung.



Anfragen und Support

Wo kann der Zugang zum ZSR-Webservice beantragt werden?

Bitte nehmen Sie Kontakt mit uns auf um den Zugang zum ZSR-Webservice zu beantragen.


An wen kann man sich bei Supportanfragen zum ZSR-Webservice wenden?

Bitte nehmen Sie Kontakt mit uns auf.



Authentifizierung und Absetzen von Abfragen

Wie kann auf den ZSR-Webservice zugegriffen werden?

Bitte nehmen Sie Kontakt mit uns auf um den Zugang zum ZSR-Webservice zu beantragen.


Wie erfolgt die Authentifizierung?

Die Authentifizierung basiert auf OpenID Connect bzw. OAuth 2.0 unter Verwendung von password grant.

draw.io Diagram
bordertrue
viewerToolbartrue
fitWindowfalse
diagramNameapi_access_sequence
simpleViewerfalse
width600
diagramWidth676
revision2

  1. The API Client requests the token endpoint from the auth server.
  2. The token endpoint is returned to the API Client.
  3. Request an access token from the auth server by providing the following post request parameters:
    1. grant_type: set to 'password'
    2. client_id: provided individually by SASIS
    3. client_secret: provided individually by SASIS
    4. username: provided individually by SASIS
    5. password: provided individually by SASIS
    6. scope: set constantly to 'openid profile email offline_access roles c1s_profile cpr'
  4. The access token as well as the refresh token is returned to the API Client.
  5. The specific API resource is called providing the access token in as bearer in the Authorization http header:
    'Authorization: Bearer <access token>'
  6. The API responds to the request.
  7. 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:
    1. grant_type: set to 'refresh_token'
    2. client_id: provided individually by SASIS
    3. client_secret: provided individually by SASIS
    4. scope: set constantly to 'openid profile email offline_access roles c1s_profile cpr'
    5. refresh_token: The refresh token received with the last access token.
  8. A new access token as well as a new refresh token is returned to the API Client.
  9. The specific API resource is called providing the new access token in as bearer in the Authorization http header:
    'Authorization: Bearer <access token>'
  10. The API responds to the request.

Access token

The access token response contains additional information:

Code Block
languagejava
titleAccess token response
{
  "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): 

HTML
<div class="references">

CprApiAccessSample.zip

HTML
</div>

Authentication in other languages follows the same procedure.

The following code snippets explain the procedure on a step-by-step basis:

Code Block
languagec#
themeConfluence
title1./2. Retrieve the auth servers token endpoint
collapsetrue
        /// <summary>
        /// Loads the IAM configuration.
        /// </summary>
        private async Task<DiscoveryResponse> GetDiscoveryDocumentAsync(CancellationToken ct)
        {
            using (var client = new HttpClient())
            {
                var discoveryResponse = await client.GetDiscoveryDocumentAsync(new DiscoveryDocumentRequest
                {
                    Address = "[AuthorityUrl]"
                }, ct).ConfigureAwait(false);

                if (discoveryResponse.IsError)
                    throw new Exception(discoveryResponse.Error);

                return discoveryResponse;
            }
        }


Code Block
languagec#
themeConfluence
title3./4. Request access and refresh token
collapsetrue
        /// <summary>
        /// Gets a new token response with a username and password.
        /// </summary>
        private async Task<TokenResponse> RequestTokenAsync(CancellationToken ct)
        {
            using (var client = new HttpClient())
            {
                var discoveryResponse = await GetDiscoveryDocumentAsync(ct).ConfigureAwait(false);

                var tokenResponse = await client.RequestPasswordTokenAsync(new PasswordTokenRequest
                {
                    ClientId = "[ClientId]",
                    ClientSecret = "[ClientSecret]",
                    UserName = "[UserName]",
                    Password = "[Password]",
                    Address = discoveryResponse.TokenEndpoint,
                    GrantType = OidcConstants.GrantTypes.Password,
                    Scope = string.Join(" ", _scopes),
                }, ct).ConfigureAwait(false);

                if (tokenResponse.IsError)
                    throw new Exception(tokenResponse.Error);

                return tokenResponse;
            }
        }


Code Block
languagec#
themeConfluence
title7./8. Token refresh strategy based validity of cached token response and request new access token
collapsetrue
        /// <summary>
        /// Gets the access token by either requesting a new token or by using the refresh token of an already existing token.
        /// </summary>
        private async Task<string> GetAccessTokenAsync(CancellationToken ct)
        {
            if (_tokenResponse == null)
            {
                // Creates a new token response
                _tokenResponse = await RequestTokenAsync(ct).ConfigureAwait(false);
            }
            else
            {
                var jwtSecurityTokenHandler = new JwtSecurityTokenHandler();

                // Parses JWT access token
                var jwtSecurityToken = jwtSecurityTokenHandler.ReadToken(_tokenResponse.AccessToken) as JwtSecurityToken;

                // The access token might be valid now, but expired the very next millisecond.
                // Thus, add a reasonable reserve in minutes for the validity time comparison below.
                var comparisionCorrectionInMinutes = 1;

                // Compares the access token life time with the current time, modified by the comparison correction value.
                if (jwtSecurityToken.ValidTo < DateTime.UtcNow.AddMinutes(comparisionCorrectionInMinutes))
                {
                    // Updates the existing token response
                    _tokenResponse = await RefreshTokenAsync(_tokenResponse.RefreshToken, ct).ConfigureAwait(false);
                }
            }

            return _tokenResponse.AccessToken;
        }

        /// <summary>
        /// Gets an updated token response by using a refresh token.
        /// </summary>
        private async Task<TokenResponse> RefreshTokenAsync(string refreshToken, CancellationToken ct)
        {
            using (var client = new HttpClient())
            {
                var discoveryResponse = await GetDiscoveryDocumentAsync(ct).ConfigureAwait(false);

                var tokenResponse = await client.RequestTokenAsync(new TokenRequest
                {
                    ClientId = "[ClientId]",
                    ClientSecret = "[ClientSecret]",
                    Address = discoveryResponse.TokenEndpoint,
                    ClientCredentialStyle = ClientCredentialStyle.AuthorizationHeader,
                    GrantType = OidcConstants.GrantTypes.RefreshToken,
                    Parameters =
                    {
                        { "refresh_token", refreshToken },
                        { "scope", string.Join(" ", _scopes) }
                    }
                });

                if (tokenResponse.IsError)
                    throw new Exception(tokenResponse.Error);

                return tokenResponse;
            }
        }


Code Block
languagec#
themeConfluence
title5./6./9./10. API resource call using the access token in the Authorization http header
collapsetrue
        /// <summary>
        /// A simple CPR API number search request.
        /// </summary>
        private async Task<BulkResponse> CprApiSampleRequestAsync(string accessToken, CancellationToken ct)
        {
            BulkResponse bulkResponse = new BulkResponse();

            using (var client = new HttpClient())
            {
                client.SetBearerToken(accessToken);

                var response = await client.GetAsync($"https://[CprBaseUrl]/ApiGateway/api/v1/numbers?searchOptions=Okp&offset=0&limit=10", ct).ConfigureAwait(false);

                if (!response.IsSuccessStatusCode)
                    throw new Exception("There was a problem with the request");

                string content = await response.Content.ReadAsStringAsync();

                if (content != null && content.Length > 0)
                {
                    bulkResponse = JsonConvert.DeserializeObject<BulkResponse>(content);
                }
            }

            return bulkResponse;
        }


Code Block
languagec#
themeConfluence
titlePlain API Call (putting everything together)
collapsetrue
        var accessToken = await GetAccessTokenAsync(ct).ConfigureAwait(false);

        var cprApiResponse = await CprApiSampleRequestAsync(accessToken, ct).ConfigureAwait(false);



Welche Limiten bestehen auf Batchabfragen?

Als Batchabfragen gelten Abfragen mit mehr als 50 Requests pro Minute und Kunde.

Abfragen aus Batch-Prozessen auf Online-Dienste der SASIS AG dürfen ausschliesslich zwischen 22.00 und 4.00 Uhr durchgeführt werden.
Die Online-Dienste der SASIS AG sind mit einer Begrenzung versehen, welche die Anfragen ab einer Überschreitung von 1000 Abfragen pro Minute und Kunde zurückweist (http Statuscode 503). 

Siehe auch  Service Level Agreement der SASIS IT Services.


Weshalb kann ich nur 500 Nummern bei der Detailansicht beziehen?

Abfragen an die Endpoints ClearingNumbers und EmployeeNumbers sind aus Performance Gründen auf 500 Nummern limitiert. Der Abfrage-Prozess ist so zu planen, das jeweils maximal 500 Nummern in einem Request enthalten sind.


Welche Statuscodes werden vom Webservice zurückgegeben?

Der Webservice verwendet http status codes. Folgende Codes können zurückgegeben werden:

Status Code

Description

200Success
202Accepted; Request is valid and business process could be triggered successfully.
400Bad Request; The request data is invalid.
401Unauthorized; The caller does not have sufficient privileges to perform the call.
403Forbidden;  The server is refusing the action.
500Internal Server Error; Any unexpected internal failure.



Wie können 503er-Fehler verhindert/vermieden werden?

Wird der Webservice mit zu vielen parallelen Abfragen überlastet, werden 503er-Fehler zurückgegeben. Um 503er-Fehler zu vermeiden, müssen die Anweisungen für das Laden der Nummernliste wie auch das Laden der Nummerndetails unbedingt beachtet werden (siehe auch Wie können Daten zu ZSR- und K-Nr. über den Webservice abgefragt werden?). Die Anzahl Requests kann weiter reduziert werden, indem beispielsweise nur Mutationen als Tagesscheiben abgefragt werden (siehe auch Wie können Mutationen abgefragt werden?). Nach dem Auftreten eines 503er-Fehlers sollte zudem ein Zeitpuffer von 5 Minuten bis zur nächsten Abfrage implementiert werden. Allenfalls ist auch zu prüfen, ob Webservice-Abfragen auf einen anderen, nächtlichen Zeitslot verlegt werden können


Wie können 400er-Fehler verhindert/vermieden werden?

Wenn der Client einen ungültigen Request an den Webservice sendet, wird ein 400er-Fehler zurückgegeben. Um 400er-Fehler zu vermeiden, müssen die Anweisungen für das Laden der Nummernliste wie auch das Laden der Nummerndetails unbedingt beachtet werden (siehe auch Wie können Daten zu ZSR- und K-Nr. über den Webservice abgefragt werden?). Der Abfrage-Prozess ist so zu planen, das jeweils maximal 500 Nummern in einem Request enthalten sind.



Abfrage von ZSR- und K-Nummern

Wie wird der Numbers Endpoint verwendet?

Der Endpoint Numbers liefert ZSR- und K-Nummern zurück die den Filterkriterien entsprechen.

Siehe auch Wie können Daten zu ZSR- und K-Nr. über den Webservice abgefragt werden?


Was sind die möglichen Filterkriterien beim Numbers Endpoint?

Filterkriterien:

  • filterOptions: Begrenzt die Anzahl zurückgegebener Nummern auf bestimmte Kategorie(n)/Zertifizierer. Verfügbare Module analog der Abo-Optionen.
  • numberTypes: Bestimmt den zurückgegebenen Nummerntyp (ZSR-/K-Nummer).
  • offset: Paging-Wert, der eine Anzahl von Nummern überspringt. In der Regel kann hier 0 übergeben werden.
  • limit: Paging-Wert, der die Anzahl zurückgegebener Nummern begrenzt. Damit mit einem Request alle Nummern auf einmal geladen werden können, darf hier ein relativ hoher Wert mitgegeben werden, z.B. 200'000. 
  • modifiedFrom: Das "Modified-Stichdatum", s. Abfrage von Mutationen (DIFF).


Gibt es eine erweiterte Suche?

Erweiterte Suchanfragen mit Filterkriterien auf Feldebene, beispielsweise nach Name oder Postleitzahl, werden über den ZSR-Webservice nicht angeboten. Für erweiterte Suchanfragen steht die ZSR-Vollversion zur Verfügung. 

Für die Filterkriterien des Webservice siehe Datenabfrage.


Wie können Daten zu ZSR- und K-Nr. über den Webservice abgefragt werden?

Die Abfrage der Daten erfolgt in zwei Schritten.

Schritt 1 - Laden der Nummernliste:

Abfrage aller gewünschten ZSR-/K-Nummern über den Endpoint "Numbers". Angewendete Filterkriterien und die Benutzer-Berechtigungen beeinflussen das Suchresultat. Der Endpoint "Numbers" liefert sämtliche ZSR-/K-Nummern aus, die den Filterkriterien entsprechen und auf welche der Kunde berechtigt ist. Nicht geliefert werden ZSR-/K-Nummern die länger als 10 Jahre sistiert sind.

Filterkriterien:

  • filterOptions: Begrenzt die Anzahl zurückgegebener Nummern auf bestimmte Kategorie(n)/Zertifizierer. Verfügbare Module analog der Abo-Optionen.
  • numberTypes: Bestimmt den zurückgegebenen Nummerntyp (ZSR-/K-Nummer).
  • offset: Paging-Wert, der eine Anzahl von Nummern überspringt. In der Regel kann hier 0 übergeben werden.
  • limit: Paging-Wert, der die Anzahl zurückgegebener Nummern begrenzt. Damit mit einem Request alle Nummern auf einmal geladen werden können, darf hier ein relativ hoher Wert mitgegeben werden, z.B. 200'000. 
  • modifiedFrom: Das "Modified-Stichdatum", s. Abfrage von Mutationen (DIFF).

Schritt 2 - Laden der Nummerndetails:

Mit dem Resultat von Schritt 1 ist für jeweils 500 Nummern ein Request über den jeweiligen Detail-Endpoint abzusetzen. Die Response der Detail-Endpoints beinhaltet die kompletten Nummern-Details, auf die der User berechtigt ist. Auf gehäufte, parallele Einzelrequest ist aus performancegründen unbedingt zu verzichten.

Endpoints:

  • für ZSR-Nummern: Endpoint "ClearingNumbers"
  • für K-Nummern: Eindpoint "EmployeeNumbers"


Was sind Subscription Options?

Die über den Webservice gelieferten Daten entsprechen grundsätzlich den Daten die in den RK-Abos geliefert werden. Die Subscription Options sind abhängig von den Modulen die der Kunde abonniert hat. Siehe Abo-Optionen


Wie können die Subscription Options geändert werden?

Bitte nehmen Sie Kontakt mit uns auf.


Wie wird der ClearingNumbers Endpoint verwendet?

Der Endpoint ClearingNumbers liefert Details zu ZSR-Nummern zurück.

Siehe Wie können Daten zu ZSR- und K-Nr. über den Webservice abgefragt werden?


Wie wird der EmployeeNumbers Endpoint verwendet?

Der Endpoint EmployeeNumbers liefert Details zu K-Nummern zurück.

Siehe Wie können Daten zu ZSR- und K-Nr. über den Webservice abgefragt werden?


Wie können gelöschte Nummern identifiziert werden?

Wenn ein fachlicher Wert einmal geliefert wurde (mit einer bestimmten ID bzw. ZSR-/K-Nummer) und zu einem späteren Zeitpunkt nicht mehr in der Response enthalten ist, dann handelt es sich um einen gelöschten/stornierten Wert.


Wie können Mutationen abgefragt werden?

Über den Endpoint "Numbers" kann als Parameter ein "Modified-Stichdatum" festgelegt werden. In der Response enthalten sind dann nur Nummern, die seit diesem Datum modifiziert wurden. Solche Modifikationen können fachlicher Natur sein, aber auch nur rein technische Werte der Nummer betreffen.

Länger als 10 Jahre sistierte und stornierte Nummern werden über den Numbers-Endpoint nicht geliefert. Um herausfinden zu können, welche Nummern betroffen sind, müssen zuerst alle aktiven Nummern über den Numbers-Endpoint geladen werden. Fehlen Nummern in diesem Resultat, die im Client-System jedoch noch aktiv geführt werden, sind diese im Client-System zu beenden bzw. zu löschen.

Nach dem Laden aller modifizierten Nummern können die Details zu diesen Nummern wie üblich über die Detail-Endpoints abgefragt werden. Die Response dieser Endpoints liefert immer alle verfügbaren Daten zu einer ZSR-/K-Nummer und nicht nur die effektiv geänderten Werte.

Mutationen können vom Client-System z.B. mittels Vergleich des JSON-Resultats der letzten Abfrage mit dem JSON-Resultat der neuen Abfrage verarbeitet werden. Hierzu gäbe es folgende Fälle zu beachten:

  • Element mit techn. ID x besteht im Client-System und wird im JSON-Resultat geliefert: Es ist zu prüfen, ob sich ein für das Client-System relevanter Feldwert des Elements geändert hat.
  • Element mit techn. ID y besteht im Client-System und wird im JSON-Resultat nicht geliefert: Alle Feldwerte des Elements gelten als storniert und müssen entfernt werden.
  • Element mit techn. ID z besteht nicht im Client-System und wird im JSON-Resultat geliefert: Alle Feldwerte des Elements sind neu und müssen eingelesen werden.

Die Integration des Webservice sollte immer so erfolgen, dass diese unabhängig von der Anzahl der gemeldeten Mutationen funktioniert, z.B. sollen selbst gewählte Thresholds nicht zum Abbruch des Daten-Imports führen.


Können auch nur geänderte ZSR-/K-Nummern geladen werden?

Ja, das Filterkriterium "modifiedFrom" erlaubt die Abfrage von Mutationen per Stichdatum. Siehe auch Wie können Mutationen abgefragt werden?


Wie sind Mutationen zu verarbeiten?

  • Element mit techn. ID x besteht im Client-System und wird im JSON-Resultat geliefert: Es ist zu prüfen, ob sich ein für das Client-System relevanter Feldwert des Elements geändert hat.
  • Element mit techn. ID y besteht im Client-System und wird im JSON-Resultat nicht geliefert: Alle Feldwerte des Elements gelten als storniert und müssen entfernt werden.
  • Element mit techn. ID z besteht nicht im Client-System und wird im JSON-Resultat geliefert: Alle Feldwerte des Elements sind neu und müssen eingelesen werden.

Interpretation der Daten

Wie sind K-Nummern und ZSR-Nummern verknüpft?

Der CareProvider (Leistungserbringer) ist ein Property auf dem Detail-Record der ZSR-/K-Nummer.

ClearingNumber → CareProvider (LERB)
EmployeeNumber → CareProvider (LERB)
Anstellungsverhältnisse sind wie folgt abgebildet:

ClearingNumber → RelatedEmployees (alle Angestellten einer ZSR-Nummer)
EmployeeNumber → RelatedEmployers (alle Arbeitgeber einer K-Nummer)

Auf welchen Daten basiert die ausgewiesene Gültigkeit (validityPeriod) einer ZSR-/K-Nr?

Die Gültigkeit einer ZSR-/K-Nummer besteht nicht mehr nur aus einem Start- und Endedatum (Zeitraum). Die Gültigkeit wird anhand verschiedener Zeiträume bestimmt und als eine Liste von Gültigkeitsperioden (ValidityPeriods) ausgeliefert. Darin werden auch Gültigkeitslücken klar ausgewiesen.

Diese Gültigkeitsperioden werden wie folgt bestimmt:

ClearingNumber

  • OKP: Start-Datum (S5) bis Ende-Datum (S6) plus Abzug von vergangenen bzw. aktiven Sistierungszeiträumen.
  • OG52/56: Alle aggregierten Zeiträume der Methoden (HealthServices) plus gegebenenfalls Zeiträume von Standort-Eigenschaften (Facilities) wie FitnesClassification oder SPAK-Anerkennung.

EmployeeNumber

  • Alle aggregierten Zeiträume der Anstellungsverhältnisse.

Wie kann ich feststellen, ob es sich um ein Bank- oder Postkonto handelt?

Die Klassifizierung Bankkonto/Postkonto wird im ZSR-Webservice nicht mehr geführt.

Ob ESR Zahlungen möglich sind, ist unter ClearingNumberAccount anhand vom Feld hasPaymentOrderReferenceNumber eruierbar.

Endpoint: ClearingNumbers, Objekt: clearingNumberAccount

Welche Bedeutung haben die Daten «0001-01-01» bzw. «9999-12-31»?

Für fachliche Zeiträume liefert der ZSR-Webservice immer einen Wert für Start- und Ende-Datum, auch dort wo sich aus den Legacy-Daten oder aus anderen Gründen sinnvollerweise keine genauen Datumswerte bestimmen lassen.

Dafür werden je einen Platzhalterwert für das Start- und das Ende-Datum verwendet. Die Interpretation dieser Werte ist wie folgt:

  • «0001-01-01» ist ein Platzhalterwert für ein Startdatum und bedeutet, dass es kein bekanntes fachliches Anfangsdatum gibt (NULL).
  • «9999-12-31» ist ein Platzhalterwert für ein Endedatum und bedeutet, dass es kein bekanntes fachliches Enddatum gibt (NULL).

Ein fachlicher Wert mit fachlichem Startdatum «0001-01-01» und fachlichem Endedatum «9999-12-31» ist somit zu jedem Zeitpunkt gültig.

Werden technische Id's geliefert?

Die in der Detail-Response gelieferten IDs haben keinerlei fachliche Bedeutung und sollten nicht zur fachlichen Interpretation von Werten herbeigezogen werden. Sie dienen ausschliesslich der technischen Identifikation der gelieferten Daten bzw. können zur Handhabung von Mutationen (siehe Wie können Mutationen abgefragt werden? bzw. Wie sind Mutationen zu verarbeiten?) genutzt werden.

Idealerweise wird auf die Verwendung von technischen IDs komplett verzichtet, da die Beständigkeit nicht garantiert wird. Das gilt sowohl für volatile, technische IDs von Zuweisungen als auch für technische IDs von "Stammdaten", z.B. wie Kanton, Land usf., auch wenn diese grundsätzlich beibehalten werden.

Für den Hauptrecord der ZSR-/K-Nummer wird ausserdem überhaupt keine technische ID geliefert. Eine Identifikation ist nur mittels ZSR-/K-Nummer möglich. Ein Ersatzwert zur vormaligen ZahlstellenId wird nicht ausgeliefert

Wie können Dummy-Nummern identifiziert werden?

Die sogenannten Dummy-Nummern sind ein weiterhin verwendetes Legacy-Konstrukt, das weiterhin per ZSR-Webservice bezogen werden kann.

Sobald auf dem ClearingNumber Objekt ein Wert für das Property "clearingNumberDummy" geliefert wird, handelt es sich um eine Dummy-Nummer.

Beispiel-Struktur:

Code Block
languagejs
{
	"clearingNumber": {
		"clearingNumberDummy": {
			"id": 912
			"name": "CH-Arzt",
		}
	}
}

Wie werden Partnerart-Obergruppe/Partnerart-Untergruppe im Webservice ausgewiesen?

Alle Leistungserbringer ausser Ärzte und Ärztinnen

  • Im Feld parentBusinessScope wird immer der Wert für die Partnerart-Obergruppe geliefert.
  • Im Feld businessScope wird
    • falls vorhanden der Wert der Partnerart-Untergruppe geliefert.
    • ansonsten wird der Wert der Partnerart-Obergruppe geliefert.
Ärzte und Ärztinnen
"Ärzte und Ärztinnen" werden in businessScope und businessActivity kategorisiert.

Die Werte für BusinessScopes/ParentBusinessScopes können Sie via Webservice über den Endpoint «BusinessScopes» abfragen: /api/v1/businessscopes.

Die Werte für businessActivity sind als Enum-Werte im swagger.json (JSON) ausgewiesen.

Siehe auch MappingAboFiles_Webservice ,Tabs PAOG_BusinesssScope, PAOG_BusinesssScope, PAUG_BusinessActivities

Allgemeine Informationen zum Zahlstellenregister

Wie setzt sich eine gültige ZSR-Nummer zusammen?

Die ZSR-Nummer setzt sich zusammen aus einem Prüfbuchstaben (1. Stelle), Laufnummer (Stellen 2-5) und dem Nummernkreis (Stellen 6-7).

Prüfbuchstabe 1
Laufnummer 4
Kantons-Identifikation 2
Beispiel: L248519
L = Prüfbuchstabe
2485 = Laufnummer
19 = Nummernkreis

Berechnung Prüfbuchstabe
Jeder Wert wird zuerst mit seiner Stellenposition multipliziert (letzte Zahl = Stellenposition 1).
Die Resultate werden anschliessend summiert.
Die Summe wird durch die Anzahl Buchstaben im Alphabet geteilt (Modulo 26).
Der Restbetrag ergibt die Stelle des Buchstabens im Alphabet

Beispiel: L248519

(9*1)+(1*2)+(5*3)+(8*4)+(4*5)+(2*6)=90
90/26=4.461...
90-(3*26)=12
12ter Buchstabe im Alphabet= L

Beispiel: Y274589

(9*1)+(8*2)+(5*3)+(4*4)+(7*5)+(2*6)=103
103/26=3.96...103-(26*3)=25
25ter Buchstabe im Alphabet = Y

Wie setzt sich eine gültige K-Nummer zusammen?

K-Nummern setzen sich zusammen aus einer Laufnummer (Stellen 1-6) und dem Buchstaben "K" (7.Stelle).

Sv translation
languagefr

Es gibt somit zwei Varianten wie eine Veränderung eines bestehenden Wertes geliefert werden kann: 

  • Variante 1: mit fachlicher Historisierung → bei jeder Mutation des Feldwertes wird ein Element mit neuer technischer ID angelegt.
  • Variante 2: noch ohne fachliche Historisierung → ein Feldwert ändert sich, die technische ID bleibt gleich.

Im Endausbau des Webservice wird nur noch Variante 1 zur Anwendung kommen. Aktuell muss die Integration so erfolgen, dass die Client-Systeme mit beiden Varianten umgehen können.


Weshalb sind einzelne Einträge plötzlich nicht mehr in der Response enthalten?

Wurde ein Element bisher im JSON-Resultat geliefert und nun nicht mehr, dann handelt es sich um einen Storno (Falsche Erfassung von Daten bzw. nachträgliche Korrektur).

Wir empfehlen dieses Element im Client-System zu löschen.

Siehe auch Wie sind Mutationen zu verarbeiten?


Interpretation der Daten

Wie werden ZSR-Nummern Beziehungen im Webservice geliefert?

  • ClearingNumber.relatedClearingNumbers enthält durch die SASIS manuell geführte Beziehungen zu ZSR-Nummern. Diese werden nur noch so lange geführt, bis vom Leistungserbringer bestätigte Daten vorliegen.
  • CareProvider.ClearingNumbers enthält vom Leistungserbringer bestätigte Beziehungen zu ZSR-Nummern.
  • CareProvider.EmployeeNumbers enthält vom Leistungserbringer bestätigte Beziehungen zu K-Nummern. (hierbei handelt es sich NICHT um Angestelltenverhältnisse).

Um die Gesamtheit der ZSR-Nummern Beziehungen zu erhalten, müssen somit sowohl ClearingNumber.relatedClearingNumbers wie auch CareProvider.ClearingNumbers berücksichtigt werden.

Expand
titleBeispiele


Code Block
titleClearingNumber.relatedClearingNumbers
    "relatedClearingNumbers": [
        {
          "clearingNumber": "B222222",
          "clearingNumberRelationType": "CHANGE_OF_HANDS",
          "clearingNumberRelationTypeTranslations": {
            "de": "Besitzerwechsel",
            "fr": "Changement de propriétaire",
            "it": "Cambiamento di proprietario"
          },
          "id": 520754
        }
      ]


Code Block
titleCareProvider.ClearingNumbers
"clearingNumbers": [
          {
            "number": "N111111"
          }
        ]


Code Block
titleCareProvider.EmployeeNumbers
 "employeeNumbers": [
          {
            "number": "999999K"
          }
        ]

Hinweis: Eine Beziehungsart wird nicht geführt und kann daher nicht ausgeliefert werden für CareProvider.ClearingNumbers und CareProvider.EmployeeNumbers.



Wie werden Angestelltenverhältnisse im Webservice geliefert?

Angestelltenverhältnisse werden unter clearingNumber.relatedEmployees geliefert.


Auf welchen Daten basiert die ausgewiesene Gültigkeit (validityPeriod) einer ZSR-/K-Nr?

Die Gültigkeit einer ZSR-/K-Nummer besteht nicht mehr nur aus einem Start- und Endedatum (Zeitraum). Die Gültigkeit wird anhand verschiedener Zeiträume bestimmt und als eine Liste von Gültigkeitsperioden (ValidityPeriods) ausgeliefert. Darin werden auch Gültigkeitslücken klar ausgewiesen.

Diese Gültigkeitsperioden werden wie folgt bestimmt:

ClearingNumber

  • OKP: Start-Datum (S5) bis Ende-Datum (S6) plus Abzug von vergangenen bzw. aktiven Sistierungszeiträumen.
  • OG52/56: Alle aggregierten Zeiträume der Methoden (HealthServices) plus gegebenenfalls Zeiträume von Standort-Eigenschaften (Facilities) wie FitnesClassification oder SPAK-Anerkennung.

EmployeeNumber

  • Alle aggregierten Zeiträume der Anstellungsverhältnisse.


Wenn mehrere validityPeriods vorhanden sind (z.B. clearingNumber.validityPeriods) welche muss dann berücksichtigt werden?

Im Gegensatz zu den Abo-Files können über den Webservice mehrere Gültigkeitsbereiche (validityPeriods) zu einem Element ausgeliefert werden. Grundsätzlich sollten im Sinne einer fachlichen Historie alle vorhandenen Gültigkeitsperioden übernommen werden. Ist dies nicht möglich, empfehlen wir die aktuellste bzw. letzte gültige zu berücksichtigen.


Wie kann ich feststellen, ob es sich um ein Bank- oder Postkonto handelt?

Die Klassifizierung Bankkonto/Postkonto wird im ZSR-Webservice nicht mehr geführt.

Ob ESR Zahlungen möglich sind, ist unter ClearingNumberAccount anhand vom Feld hasPaymentOrderReferenceNumber eruierbar.

Endpoint: ClearingNumbers, Objekt: clearingNumberAccount


Welche Bedeutung haben die Daten «0001-01-01» bzw. «9999-12-31»?

Für fachliche Zeiträume liefert der ZSR-Webservice immer einen Wert für Start- und Ende-Datum, auch dort wo sich aus den Legacy-Daten oder aus anderen Gründen sinnvollerweise keine genauen Datumswerte bestimmen lassen.

Dafür werden je einen Platzhalterwert für das Start- und das Ende-Datum verwendet. Die Interpretation dieser Werte ist wie folgt:

  • «0001-01-01» ist ein Platzhalterwert für ein Startdatum und bedeutet, dass es kein bekanntes fachliches Anfangsdatum gibt (NULL).
  • «9999-12-31» ist ein Platzhalterwert für ein Endedatum und bedeutet, dass es kein bekanntes fachliches Enddatum gibt (NULL).

Ein fachlicher Wert mit fachlichem Startdatum «0001-01-01» und fachlichem Endedatum «9999-12-31» ist somit zu jedem Zeitpunkt gültig.


Werden technische Id's geliefert?

Element id

Die in der Detail-Response gelieferten IDs haben keinerlei fachliche Bedeutung und sollten nicht zur fachlichen Interpretation von Werten herbeigezogen werden. Sie dienen ausschliesslich der technischen Identifikation der gelieferten Daten bzw. können zur Handhabung von Mutationen (siehe Wie können Mutationen abgefragt werden? bzw. Wie sind Mutationen zu verarbeiten?) genutzt werden. Auf der technischen IDs sollte nie eine Logik codiert werden.

Für den Hauptrecord der ZSR-/K-Nummer wird ausserdem überhaupt keine technische ID geliefert. Eine Identifikation ist nur mittels ZSR-/K-Nummer möglich. Ein Ersatzwert zur vormaligen ZahlstellenId wird nicht ausgeliefert

Element key

"Stammdaten/Referenzdaten", z.B. wie Kanton, Land, Qualifikation usf., werden mit einer beständigen GUID als Identifikator ausgeliefert. Siehe auch Können Referenzdaten (=Stammdaten) separat geladen werden?

Die eindeutige Identifikation ist über das Element "key" (string) möglich bei folgenden Entitäten: 

  • Affiliations
  • BusinessScopes
  • ClearingNumberSuffixes
  • Countries
  • Facilities
  • HealthServices
  • Qualifications
  • TariffSystems

Beispiel: "key": "3fa85f64-5717-4562-b3fc-2c963f66afa6"


Wie können Dummy-Nummern identifiziert werden?

Die sogenannten Dummy-Nummern sind ein weiterhin verwendetes Legacy-Konstrukt, das weiterhin per ZSR-Webservice bezogen werden kann.

Sobald auf dem ClearingNumber Objekt ein Wert für das Property "clearingNumberDummy" geliefert wird, handelt es sich um eine Dummy-Nummer.

Beispiel-Struktur:

Code Block
languagejs
{
	"clearingNumber": {
		"clearingNumberDummy": {
			"id": 912
			"name": "CH-Arzt",
		}
	}
}



Wie werden Partnerart-Obergruppe/Partnerart-Untergruppe im Webservice ausgewiesen?

Alle Leistungserbringer ausser Ärzte und Ärztinnen

  • Im Feld parentBusinessScope wird immer der Wert für die Partnerart-Obergruppe geliefert.
  • Im Feld businessScope wird
    • falls vorhanden der Wert der Partnerart-Untergruppe geliefert.
    • ansonsten wird der Wert der Partnerart-Obergruppe geliefert.


Ärzte und Ärztinnen
"Ärzte und Ärztinnen" werden in businessScope und businessActivity kategorisiert.


Die Werte für BusinessScopes/ParentBusinessScopes können Sie via Webservice über den Endpoint «BusinessScopes» abfragen: /api/v1/businessscopes.

Die Werte für businessActivity sind als Enum-Werte im swagger.json (JSON) ausgewiesen.

Siehe auch Mapping Abo Files - Webservice,Tabs PAOG_BusinesssScope, PAOG_BusinesssScope, PAUG_BusinessActivities



Allgemeine Informationen zum Zahlstellenregister

Wie setzt sich eine gültige ZSR-Nummer zusammen?

Die ZSR-Nummer setzt sich zusammen aus einem Prüfbuchstaben (1. Stelle), Laufnummer (Stellen 2-5) und dem Nummernkreis (Stellen 6-7).

Prüfbuchstabe 1
Laufnummer 4
Kantons-Identifikation 2
Beispiel: L248519
L = Prüfbuchstabe
2485 = Laufnummer
19 = Nummernkreis

Berechnung Prüfbuchstabe
Jeder Wert wird zuerst mit seiner Stellenposition multipliziert (letzte Zahl = Stellenposition 1).
Die Resultate werden anschliessend summiert.
Die Summe wird durch die Anzahl Buchstaben im Alphabet geteilt (Modulo 26).
Der Restbetrag ergibt die Stelle des Buchstabens im Alphabet


Beispiel: L248519

(9*1)+(1*2)+(5*3)+(8*4)+(4*5)+(2*6)=90
90/26=4.461...
90-(3*26)=12
12ter Buchstabe im Alphabet= L

Beispiel: Y274589

(9*1)+(8*2)+(5*3)+(4*4)+(7*5)+(2*6)=103
103/26=3.96...103-(26*3)=25
25ter Buchstabe im Alphabet = Y


Wie setzt sich eine gültige K-Nummer zusammen?

K-Nummern setzen sich zusammen aus einer Laufnummer (Stellen 1-6) und dem Buchstaben "K" (7.Stelle).







  1. The API Client requests the token endpoint from the auth server.
  2. The token endpoint is returned to the API Client.
  3. Request an access token from the auth server by providing the following post request parameters:
    1. grant_type: set to 'password'
    2. client_id: provided individually by SASIS
    3. client_secret: provided individually by SASIS
    4. username: provided individually by SASIS
    5. password: provided individually by SASIS
    6. scope: set constantly to 'openid profile email offline_access roles c1s_profile cpr'
  4. The access token as well as the refresh token is returned to the API Client.
  5. The specific API resource is called providing the access token in as bearer in the Authorization http header:
    'Authorization: Bearer <access token>'
  6. The API responds to the request.
  7. 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:
    1. grant_type: set to 'refresh_token'
    2. client_id: provided individually by SASIS
    3. client_secret: provided individually by SASIS
    4. scope: set constantly to 'openid profile email offline_access roles c1s_profile cpr'
    5. refresh_token: The refresh token received with the last access token.
  8. A new access token as well as a new refresh token is returned to the API Client.
  9. The specific API resource is called providing the new access token in as bearer in the Authorization http header:
    'Authorization: Bearer <access token>'
  10. The API responds to the request.

Access token

The access token response contains additional information:

Sv translation
languagefr




Panel
titleContent

Table of Contents



HTML
<div class="references">


Panel
titleLinks

ApiGateway/swagger/index.html

ApiGateway/swagger/1/swagger.json

Swagger Editor - editor.swagger.io

OpenID Connect - openid.net

OAuth - oauth.net

JSON Web Tokens - jwt.io

ReDoc - redocly.github.io

W3 Status Code Definition - w3.org

Service Level Agreement IT Services SASIS DE

Service Level Agreement IT Services SASIS FR

Service Level Agreement IT Services SASIS IT

Options d'abonnement

Release Notes

Contact

Mapping Abo Files - Webservice

BusinessActivityEnumListe


HTML
</div>




Web service integration

Which data can be requested via the ZSR web service?

The data delivered via the web service correspond in principle to the data delivered in the backwards-compatible subscriptions. The modules to which the customer has subscribed thus determine which data can be requested. See Subscription options
Data can be requested on clearing numbers/employee numbers that have not been suspended for more than ten years.


Are the data delivered with the same structure as in the subscription files?

The web service uses a different data model from that of the subscription files. See also Mapping Abo Files - Webservice.

The key entities are as follows:

  • CareProvider - service provider
  • CareProviderBusiness - location
  • ClearingNumber - ZSR number
  • EmployeeNumber - K number


Expand
titleMain ClearingNumber entities (simplified view)

clearingNumber

  • number (clearingNumber)
  • correspondenceParty (correspondence address)
  • account (bank account)
  • clearingNumberLaws
  • careProvider
    • careProviderParties (addresses)
    • qualifications
    • employeeNumbers
  • careProviderBusinesses (business location)
    • careProviderBusinessParties (addresses)
    • facilities (business facilities)
    • healthServices (certifier methods)
    • affiliations
  • businessScope (OG/UG)
  • businessActivity
  • relatedClearingNumbers
  • relatedEmployees
  • licenses (cantonal authorizations)
  • admissions (cantonal admissions)
  • tariffSystems

Remarks:
This is a highly simplified view – for details, see the Swagger-Schema.
It incorporates the changes set out in the Release Notes ZSR Webservice (24.06.22)



Why was the data model changed (compared with the subscription files)?

The reasons for changing the data model are as follows:

  • Reality check: The old data model allowed multiple sets of master data to be required for the same service provider. This led to a lack of clarity in the specialist data and made uniform identification harder. With the new data model, attention has been paid to ensuring that the legacy data can be collated over time so that a single data set can be delivered for each service provider. The English working title of the application is now CareProviderRegister – the term “paying agent” has been dropped.
  • Specialist data: The old data model could not create a specialist history in all areas. The new data model ensures that a specialist history containing all relevant data can be created and updated easily.
  • Future-proof: The old data model could not easily meet the requirements that will be placed on CareProviderRegister going forward. The new data model offers the flexibility to adapt more quickly to changes in the specialist workflows.


Which response format does the ZSR web service use?

Data are delivered in JSON format (XML is not supported).


Can reference data (master data) be loaded separately?

Reference/master data for ZSR/K number values (methods, qualifications, banks etc.) do not have to be loaded separately. All required data are delivered directly in the detailed response for the individual number.

If needed, reference/master data can be entered separately as follows:

  • All enum values (e.g. gender, canton etc.) are already contained in full in swagger.json (JSON). The Swagger Editor or other tools can be used to generate ZSR web service reference classes automatically, complete with the corresponding enum values.
  • The following values are not contained in swagger.json as enum values, but they can be requested via a dedicated ZSR web service endpoint:
    • Affiliations (association codes)
    • BusinessScopes (partner type groups/sub-groups)
    • ClearingNumberSuffixes (number groups)
    • Countries
    • Facilities (location features)
    • HealthServices (methods)
    • Qualifications
    • TariffSystems

Unique identification of the reference data is possible using the element “key” (string). See Are technical IDs delivered?

Example: "key": "3fa85f64-5717-4562-b3fc-2c963f66afa6"


Where can I find the technical API documentation?

An Open API Specification is available.

In addition to Swagger, (for example) ReDoc can be used to display the open API specification.


Is there a version history for the ZSR web service?

The ZSR web service is currently at version v1.x. For the time being, all changes to the ZSR web service will not be implemented via new versions in parallel operation but will instead be made directly in version v1.x. However, all changes will be published in release notes at the appropriate time and made available via the stage system. The SASIS Service Level Agreement apply.

As there will not be a version history for the ZSR web service for the time being, SASIS AG recommends that its integrators follow an adapter pattern that allows changes to the client-system interfaces to the ZSR web service via release-independent settings.


What are the current SASIS AG IT SLAs?

The SASIS IT Service Level Agreement applies to the web service.



Questions and support

Where can I request access to the ZSR web service?

Please contact us to request access to the ZSR web service.


Who can provide support if I have an issue with the ZSR web service?

Please contact us.



Authentication and submitting requests

How do I access the ZSR web service?

Please contact us to request access to the ZSR web service.


How does authentication work?

Authentication is based on OpenID Connect or OAuth 2.0 using password grant.

draw.io Diagram
bordertrue
viewerToolbartrue
fitWindowfalse
diagramNameapi_access_sequence
simpleViewerfalse
width600
diagramWidth676
revision2

  1. The API Client requests the token endpoint from the auth server.
  2. The token endpoint is returned to the API Client.
  3. Request an access token from the auth server by providing the following post request parameters:
    1. grant_type: set to 'password'
    2. client_id: provided individually by SASIS
    3. client_secret: provided individually by SASIS
    4. username: provided individually by SASIS
    5. password: provided individually by SASIS
    6. scope: set constantly to 'openid profile email offline_access roles c1s_profile cpr'
  4. The access token as well as the refresh token is returned to the API Client.
  5. The specific API resource is called providing the access token in as bearer in the Authorization http header:
    'Authorization: Bearer <access token>'
  6. The API responds to the request.
  7. 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:
    1. grant_type: set to 'refresh_token'
    2. client_id: provided individually by SASIS
    3. client_secret: provided individually by SASIS
    4. scope: set constantly to 'openid profile email offline_access roles c1s_profile cpr'
    5. refresh_token: The refresh token received with the last access token.
  8. A new access token as well as a new refresh token is returned to the API Client.
  9. The specific API resource is called providing the new access token in as bearer in the Authorization http header:
    'Authorization: Bearer <access token>'
  10. The API responds to the request.

Access token

The access token response contains additional information:

Code Block
languagejava
titleAccess token response
{
  "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): 

HTML
<div class="references">

CprApiAccessSample.zip

HTML
</div>

Authentication in other languages follows the same procedure.

The following code snippets explain the procedure on a step-by-step basis:

Code Block
languagec#
themeConfluence
title1./2. Retrieve the auth servers token endpoint
collapsetrue
        /// <summary>
        /// Loads the IAM configuration.
        /// </summary>
        private async Task<DiscoveryResponse> GetDiscoveryDocumentAsync(CancellationToken ct)
        {
            using (var client = new HttpClient())
            {

Cet article n'est pas disponible en français.

Panel
titleContent

Table of Contents

HTML
<div class="references">
Panel
titleLinks

ApiGateway/swagger/index.html

ApiGateway/swagger/1/swagger.json

Swagger Editor - editor.swagger.io

OpenID Connect - openid.net

OAuth - oauth.net

JSON Web Tokens - jwt.io

ReDoc - redocly.github.io

W3 Status Code Definition - w3.org

Service Level Agreement IT Services SASIS

Options d'abonnement

Release Notes

Contact

Mapping Subscription Files- Webservice

HTML
</div>

Web service integration

Which data can be requested via the ZSR web service?

The data delivered via the web service correspond in principle to the data delivered in the backwards-compatible subscriptions. The modules to which the customer has subscribed thus determine which data can be requested. See Subscription options
Data can be requested on clearing numbers/employee numbers that have not been suspended for more than ten years.

Are the data delivered with the same structure as in the subscription files?

The web service uses a different data model from that of the subscription files. See also Mapping Subscription Files- Webservice.

The key entities are as follows:

  • CareProvider - service provider
  • CareProviderBusiness - location
  • ClearingNumber - ZSR number
  • EmployeeNumber - K number
Expand
titleMain ClearingNumber entities (simplified view)

clearingNumber

  • number (clearingNumber)
  • correspondenceParty (correspondence address)
  • account (bank account)
  • clearingNumberLaws
  • careProvider
    • careProviderParties (addresses)
    • qualifications
    • employeeNumbers
  • careProviderBusinesses (business location)
    • careProviderBusinessParties (addresses)
    • facilities (business facilities)
    • healthServices (certifier methods)
    • affiliations
  • businessScope (OG/UG)
  • businessActivity
  • relatedClearingNumbers
  • relatedEmployees
  • licenses (cantonal authorizations)
  • admissions (cantonal admissions)
  • tariffSystems

Remarks:
This is a highly simplified view – for details, see the Swagger-Schema.
It incorporates the changes set out in the Release Notes ZSR Webservice (24.06.22)

Why was the data model changed (compared with the subscription files)?

The reasons for changing the data model are as follows:

  • Reality check: The old data model allowed multiple sets of master data to be required for the same service provider. This led to a lack of clarity in the specialist data and made uniform identification harder. With the new data model, attention has been paid to ensuring that the legacy data can be collated over time so that a single data set can be delivered for each service provider. The English working title of the application is now CareProviderRegister – the term “paying agent” has been dropped.
  • Specialist data: The old data model could not create a specialist history in all areas. The new data model ensures that a specialist history containing all relevant data can be created and updated easily.
  • Future-proof: The old data model could not easily meet the requirements that will be placed on CareProviderRegister going forward. The new data model offers the flexibility to adapt more quickly to changes in the specialist workflows.

Which response format does the ZSR web service use?

Data are delivered in JSON format (XML is not supported).

Can reference data (master data) be loaded separately?

Reference/master data for ZSR/K number values (methods, qualifications, banks etc.) do not have to be loaded separately. All required data are delivered directly in the detailed response for the individual number.

If needed, reference/master data can be entered separately as follows:

  • All enum values (e.g. gender, canton etc.) are already contained in full in swagger.json (JSON). The Swagger Editor or other tools can be used to generate ZSR web service reference classes automatically, complete with the corresponding enum values.
  • The following values are not contained in swagger.json as enum values, but they can be requested via a dedicated ZSR web service endpoint:
    • Affiliations (association codes)
    • BusinessScopes (partner type groups/sub-groups)
    • ClearingNumberSuffixes (number groups)
    • Countries
    • Facilities (location features)
    • HealthServices (methods)
    • Qualifications
    • TariffSystems

Where can I find the technical API documentation?

An Open API Specification is available.

In addition to Swagger, (for example) ReDoc can be used to display the open API specification: ZSRN-API Live (ReDoc).

Is there a version history for the ZSR web service?

The ZSR web service is currently at version v1.x. For the time being, all changes to the ZSR web service will not be implemented via new versions in parallel operation but will instead be made directly in version v1.x. However, all changes will be published in release notes at the appropriate time and made available via the stage system. The SASIS SLAs apply.

As there will not be a version history for the ZSR web service for the time being, SASIS AG recommends that its integrators follow an adapter pattern that allows changes to the client-system interfaces to the ZSR web service via release-independent settings.

What are the current SASIS AG IT SLAs?

The SASIS IT Service Level Agreement applies to the web service.

Questions and support

Where can I request access to the ZSR web service?

Please contact us to request access to the ZSR web service.

Who can provide support if I have an issue with the ZSR web service?

Please contact us.

Authentication and submitting requests

How do I access the ZSR web service?

Please contact us to request access to the ZSR web service.

How does authentication work?

Authentication is based on OpenID Connect or OAuth 2.0 using password grant.

draw.io Diagram
bordertrue
viewerToolbartrue
fitWindowfalse
diagramNameapi_access_sequence
simpleViewerfalse
width600
diagramWidth676
revision2
Code Block
languagejava
titleAccess token response
{
  "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): 

HTML
<div class="references">

CprApiAccessSample.zip

HTML
</div>

Authentication in other languages follows the same procedure.

The following code snippets explain the procedure on a step-by-step basis:

Code Block
languagec#
themeConfluence
title1./2. Retrieve the auth servers token endpoint
collapsetrue
        /// <summary>
        /// Loads the IAM configuration.
        /// </summary>
        private async Task<DiscoveryResponse> GetDiscoveryDocumentAsync(CancellationToken ct)
        {
            using (var client = new HttpClient())
            {
                var discoveryResponse = await client.GetDiscoveryDocumentAsync(new DiscoveryDocumentRequest
                {
                    Address = "[AuthorityUrl]"
                }, ct).ConfigureAwait(false);

                if (discoveryResponse.IsError)
                    throw new Exception(discoveryResponse.Error);

                return discoveryResponse;
            }
        }
Code Block
languagec#
themeConfluence
title3./4. Request access and refresh token
collapsetrue
        /// <summary>
        /// Gets a new token response with a username and password.
        /// </summary>
        private async Task<TokenResponse> RequestTokenAsync(CancellationToken ct)
        {
            using (var client = new HttpClient())
            {
                var discoveryResponse = await GetDiscoveryDocumentAsync(ct).ConfigureAwait(false);

                var tokenResponse = await client.RequestPasswordTokenAsync(new PasswordTokenRequest
                {
                    ClientId = "[ClientId]",
                    ClientSecret = "[ClientSecret]",
                    UserName = "[UserName]",
                    Password = "[Password]",
                    Address = discoveryResponse.TokenEndpoint,
                    GrantType = OidcConstants.GrantTypes.Password,
                    Scope = string.Join(" ", _scopes),
                }, var discoveryResponse = await client.GetDiscoveryDocumentAsync(new DiscoveryDocumentRequest
                {
                    Address = "[AuthorityUrl]"
                }, ct).ConfigureAwait(false);

                if (tokenResponsediscoveryResponse.IsError)
                    throw new Exception(tokenResponsediscoveryResponse.Error);

                return tokenResponsediscoveryResponse;
            }
        }


Code Block
languagec#
themeConfluence
title73./84. Token refresh strategy based validity of cached token response and request new access tokenRequest access and refresh token
collapsetrue
        /// <summary>
        /// Gets thea accessnew token byresponse eitherwith requesting a newusername tokenand orpassword.
 by using the refresh token of an already existing token.
        /// <//// </summary>
        private async Task<string>Task<TokenResponse> GetAccessTokenAsyncRequestTokenAsync(CancellationToken ct)
        {
            ifusing (_tokenResponsevar client == null new HttpClient())
            {
                //var CreatesdiscoveryResponse a= new token response
await GetDiscoveryDocumentAsync(ct).ConfigureAwait(false);

                var _tokenResponse = await RequestTokenAsync(ct).ConfigureAwait(false);client.RequestPasswordTokenAsync(new PasswordTokenRequest
            }    {
            else
        ClientId = "[ClientId]",
  {
                 var jwtSecurityTokenHandlerClientSecret = new JwtSecurityTokenHandler();

"[ClientSecret]",
                  // Parses JWTUserName access token= "[UserName]",
                var    jwtSecurityTokenPassword = jwtSecurityTokenHandler.ReadToken(_tokenResponse.AccessToken) as JwtSecurityToken;

"[Password]",
                    Address = discoveryResponse.TokenEndpoint,
  // The access token might be valid now, but expired the very next millisecond.
     GrantType = OidcConstants.GrantTypes.Password,
         // Thus, add a reasonable reserve in minutes for the validity timeScope comparison= belowstring.
Join(" ", _scopes),
              var comparisionCorrectionInMinutes = 1}, ct).ConfigureAwait(false);

                // Compares the access token life time with the current time, modified by the comparison correction value.
if (tokenResponse.IsError)
                    throw new Exception(tokenResponse.Error);

                if (jwtSecurityToken.ValidTo < DateTime.UtcNow.AddMinutes(comparisionCorrectionInMinutes))
return tokenResponse;
            }
        }


Code Block
languagec#
themeConfluence
title7./8. Token refresh strategy based validity of cached token response and request new access token
collapsetrue
{
          /// <summary>
         /// UpdatesGets the existingaccess token response
by either requesting a new token or by using the refresh token of an already existing token.
     _tokenResponse = await RefreshTokenAsync(_tokenResponse.RefreshToken, ct).ConfigureAwait(false); /// </summary>
        private async Task<string>      }GetAccessTokenAsync(CancellationToken ct)
        {
    }

        if (_tokenResponse == null)
   return _tokenResponse.AccessToken;
        }{

        /// <summary>
        /// GetsCreates ana updatednew token response by using a refresh token.
        /// </summary>
       _tokenResponse private= asyncawait Task<TokenResponse> RefreshTokenAsync(string refreshToken, CancellationToken ct)RequestTokenAsync(ct).ConfigureAwait(false);
        {
     }
       using (var client = new HttpClient())else
            {
                var discoveryResponsejwtSecurityTokenHandler = awaitnew GetDiscoveryDocumentAsyncJwtSecurityTokenHandler(ct).ConfigureAwait(false);

                var// tokenResponseParses =JWT await client.RequestTokenAsync(new TokenRequestaccess token
                {
var jwtSecurityToken = jwtSecurityTokenHandler.ReadToken(_tokenResponse.AccessToken) as JwtSecurityToken;

               ClientId = "[ClientId]",
            // The access token might be valid now, but expired the very next millisecond.
        ClientSecret = "[ClientSecret]",
         // Thus, add a reasonable reserve in minutes for the validity Addresstime =comparison discoveryResponsebelow.TokenEndpoint,
                var comparisionCorrectionInMinutes = 1;

  ClientCredentialStyle = ClientCredentialStyle.AuthorizationHeader,
            // Compares the access token life time with GrantTypethe = OidcConstants.GrantTypes.RefreshToken,
      current time, modified by the comparison correction value.
              Parameters =
 if (jwtSecurityToken.ValidTo < DateTime.UtcNow.AddMinutes(comparisionCorrectionInMinutes))
                {
                    // Updates the existing { "refresh_token", refreshToken }, response
                    _tokenResponse =   { "scope", string.Join(" ", _scopes) }
await RefreshTokenAsync(_tokenResponse.RefreshToken, ct).ConfigureAwait(false);
                }
            }

            return _tokenResponse.AccessToken;
        });

        /// <summary>
        if (tokenResponse.IsError)/// Gets an updated token response by using a refresh token.
        /// </summary>
        private async  throw new Exception(tokenResponse.Error);
Task<TokenResponse> RefreshTokenAsync(string refreshToken, CancellationToken ct)
        {
            using (var client = return tokenResponse;new HttpClient())
            }{
         }
Code Block
languagec#
themeConfluence
title5./6./9./10. API resource call using the access token in the Authorization http header
collapsetrue
       var discoveryResponse = /// <summary>await GetDiscoveryDocumentAsync(ct).ConfigureAwait(false);

        /// A simple CPR API number search request.
 var tokenResponse = await client.RequestTokenAsync(new TokenRequest
  /// </summary>
        private async Task<BulkResponse> CprApiSampleRequestAsync(string accessToken, CancellationToken ct){
        {
            BulkResponse bulkResponseClientId = new BulkResponse();

"[ClientId]",
            using (var client = new HttpClient())
   ClientSecret   = "[ClientSecret]",
      {
              Address = client.SetBearerToken(accessToken);

discoveryResponse.TokenEndpoint,
                 var response = await client.GetAsync($"https://[CprBaseUrl]/ApiGateway/api/v1/numbers?searchOptions=Okp&offset=0&limit=10", ct).ConfigureAwait(false);

ClientCredentialStyle = ClientCredentialStyle.AuthorizationHeader,
                if (!response.IsSuccessStatusCode)
   GrantType = OidcConstants.GrantTypes.RefreshToken,
               throw new Exception("There was a problem with the request");

Parameters =
                string content = await response.Content.ReadAsStringAsync();

 {
                if (content != null && content.Length > 0)
 { "refresh_token", refreshToken },
            {
            { "scope", string.Join(" ", _scopes)  }
  bulkResponse = JsonConvert.DeserializeObject<BulkResponse>(content);
                }
                });

            return bulkResponse;
    if (tokenResponse.IsError)
         }
Code Block
languagec#
themeConfluence
titlePlain API Call (putting everything together)
collapsetrue
         var accessToken =throw awaitnew GetAccessTokenAsyncException(ct).ConfigureAwait(falsetokenResponse.Error);

        var     cprApiResponse = await CprApiSampleRequestAsync(accessToken, ct).ConfigureAwait(false);

What are the limits on batch requests?

Batch requests are defined as involving more than 50 requests per minute for a given customer.
Requests from batch processes on online services provided by SASIS AG may only be carried out between 10.00 pm and 4.00 am.
SASIS AG’s online services have limits in place that cause batches of more than 1,000 requests per minute for a given customer to be rejected (http status code 503).

See also the SASIS IT Service Level Agreement.

Why can I only call up 500 numbers in the detail view?

Requests involving the endpoints ClearingNumbers and EmployeeNumbers are limited to 500 numbers for performance reasons. The request process must be planned such that no request contains more than 500 numbers.

Which status codes does the web service return?

The web service uses http status codes. The following codes may be returned:

Status Code

Description

200Success202Accepted; Request is valid and business process could be triggered successfully.400Bad Request; The request data is invalid.401Unauthorized; The caller does not have sufficient privileges to perform the call.403Forbidden;  The server is refusing the action.500Internal Server Error; Any unexpected internal failure.

How can 503 errors be avoided?

If the API is overloaded with large numbers of parallel requests, it returns 503 errors. To avoid these, it is very important to follow the instructions for loading the number list and the number details (see also How can data on ZSR and K numbers be requested via the web service?). The number of requests can be reduced further, for example, by requesting only changes via a daily change batch request (see also How can changes be requested?). When a 503 error occurs, it is advisable to wait five minutes before making another request. If possible, customers should check whether API requests can be deferred to a time slot during the night.

How can 400 errors be avoided?

When the client sends an invalid request to the API, it returns a 400 error. To avoid these, it is very important to follow the instructions for loading the number list and the number details (see also How can data on ZSR and K numbers be requested via the web service?). The request process must be planned such that no request contains more than 500 numbers.

ZSR and K number requests

How is the Numbers endpoint used?

The Numbers endpoint delivers ZSR and K numbers that match the filter criteria.

See also How can data on ZSR and K numbers be requested via the web service?

What are the possible filter criteria for the Numbers endpoint?

Filter criteria:

  • filterOptions: limits the numbers returned to specific categories/certifiers. The modules available are as for the subscription options.
  • numberTypes: sets the type of number returned (ZSR or K number).
  • offset: paging value that skips a set number of numbers. As a rule, this can be set to 0.
  • limit: paging value that limits how many numbers are returned. To ensure that all numbers can be loaded at once with a request, a relatively high value can be set here, e.g. 200,000.
  • modifiedFrom: the “modified from” date; see How can changes be requested?

Are extended search functions available?

Extended search queries with filter criteria at field level, e.g. by name and postcode, are not offered via the web service. The full version of ZSR is available for advanced search queries.

For the ZSR web service filter criteria, see the section on data requests.

How can data on ZSR and K numbers be requested via the web service?

Data are requested in two steps.

Step 1 – Loading the number list:

Request all the required ZSR/K numbers via the Numbers endpoint. The filter criteria employed and user authorisations affect the search results. The Numbers endpoint delivers all ZSR/K numbers that match the filter criteria and for which the customer is authorised. It does not deliver ZSR/K numbers that have been suspended for more than ten years.

Filter criteria:

  • filterOptions: limits the numbers returned to specific categories/certifiers. The modules available are as for the subscription options.
  • numberTypes: sets the type of number returned (ZSR or K number).
  • offset: paging value that skips a set number of numbers. As a rule, this can be set to 0.
  • limit: paging value that limits how many numbers are returned. To ensure that all numbers can be loaded at once with a request, a relatively high value can be set here, e.g. 200,000.
  • modifiedFrom: the “modified from” date; see How can changes be requested?

Step 2 – Loading the number details:

The result from step 1 is used to make a request via the appropriate detail endpoint for 500 numbers at a time. The response from the detail endpoint contains the complete number details for which the user is authorised. For performance reasons, it is important to avoid making large numbers of parallel individual requests.

Endpoints:

  • For ZSR numbers: ClearingNumbers endpoint
    For K numbers: EmployeeNumbers endpoint

What are subscription options?

The data delivered via the web service correspond in principle to the data delivered in the backwards-compatible subscriptions. The subscription options depend on the modules to which the customer has subscribed. See Subscription options.

How can the subscription options be changed?

Please contact us.

How is the ClearingNumbers endpoint used?

The ClearingNumbers endpoint delivers details of ZSR numbers.

See How can data on ZSR and K numbers be requested via the web service?

How is the EmployeeNumbers endpoint used?

The EmployeeNumbers endpoint delivers details of K numbers.

See How can data on ZSR and K numbers be requested via the web service?

How can deleted numbers be identified?

If a specialist value has been delivered (with a specific ID/ZSR/K number) but is no longer contained in the response at a later point in time, it is a deleted/cancelled value.

How can changes be requested?

A “modified from” date can be set as a parameter via the Numbers endpoint. The response then contains only numbers that have been changed since that date. Modifications can be specialist in nature or concern purely technical values. Numbers that have been suspended or cancelled for more than ten years are not delivered via the Numbers endpoint. To find out which numbers are affected, all active numbers must first be loaded via the Numbers endpoint. Any numbers that are still active in the client system but are not contained in the results should be cancelled or deleted from the client system.

Once all modified numbers have been loaded, their details can be requested in the usual way via the detail endpoints. The response from these endpoints always contains all available data on a ZSR/K number, not just the values that have been changed.
Changes can be processed from the client system, e.g. by comparing the JSON result from the last request with the JSON result from the new request. The following cases must be borne in mind:

  • An element with the technical ID x exists in the client system and is delivered in the JSON result: it is important to check whether a field value of the element that is relevant for the client system has changed.
  • An element with the technical ID y exists in the client system and is not delivered in the JSON result: all of the element’s field values are regarded as cancelled and must be removed.
  • An element with the technical ID z does not exist in the client system and is delivered in the JSON result: all of the element’s field values are new and must be entered.

The API should always be integrated such that it works regardless of the number of changes reported, i.e. threshold values set by the customer should not cause the data import to fail.

Is it possible to load only ZSR/K numbers that have been changed?

Yes. The filter criterion “modifiedFrom” makes it possible to request changes by date. See also How can changes be requested?

How are changes handled?

  • An element with the technical ID x exists in the client system and is delivered in the JSON result: it is important to check whether a field value of the element that is relevant for the client system has changed.
  • An element with the technical ID y exists in the client system and is not delivered in the JSON result: all of the element’s field values are regarded as cancelled and must be removed.
  • An element with the technical ID z does not exist in the client system and is delivered in the JSON result: all of the element’s field values are new and must be entered.

Interpreting the data

How are K numbers and ZSR numbers linked?

The CareProvider (service provider) is a property on the detail record for a ZSR/K number.

ClearingNumber → CareProvider (service provider)
EmployeeNumber → CareProvider (service provider)Employment relationships are shown as follows:
ClearingNumber → RelatedEmployees (all employees linked to a ZSR number)
EmployeeNumber → RelatedEmployers (all employers linked to a K number)

On which data is the displayed validity period of a ZSR/K number based?

The validity of a ZSR/K number is no longer defined only as a time period with a start date and an end date. It is now defined using multiple time periods (ValidityPeriods), which are delivered as a list. The list clearly shows gaps in validity.

Validity periods are defined as follows::

ClearingNumber

  • Mandatory health insurance: start date (S5) to end date (S6) minus any past or active suspension periods.
  • Partner type groups 52/56: all aggregated periods of the methods (HealthServices) plus any periods for location features (Facilities) such as FitnessClassification or SPAK recognition.

EmployeeNumber

  • All aggregated periods of the employment relationships.

How can I tell the difference between a bank account and a post office account?

The ZSR web service no longer distinguishes between bank and post office accounts.

The field “hasPaymentOrderReferenceNumber” under ClearingNumberAccount shows whether payments using a standard Swiss payment slip are possible.

Endpoint: ClearingNumbers; object: ClearingNumberAccount

What do the data items “0001-01-01” and “9999-12-31” mean?

The ZSR web service always delivers a start date and an end date for time periods, even if it is not possible to determine the exact dates due to the legacy data or for other reasons.

Placeholder values for the start and end date are therefore used. These are to be interpreted as follows:

  • “0001-01-01” is a placeholder value for the start date and means that the actual start date is not known (NULL).
  • “9999-12-31” is a placeholder value for the end date and means that the actual end date is not known (NULL).

A time period with the start date “0001-01-01” and the end date “9999-12-31” is thus valid for any given point in time.

Are technical IDs delivered?

The IDs delivered in the detailed response have no specialist meaning and should not be used to interpret values. They are purely technical identifiers of the delivered data and can serve to process changes (see How can changes be requested? and How are changes handled?).

Ideally, technical IDs would not be used at all as permanence is not guaranteed. This applies to both volatile, technical IDs of allocations and technical IDs of “master data”, e.g. canton, country etc., even if these are in principle maintained.

In addition, no technical IDs whatsoever are delivered for the main ZSR/K number record. Identification is only possible using the ZSR/K number itself. A replacement for the old paying agent ID is not delivered.

How can dummy numbers be identified?

So-called “dummy” numbers are a legacy construct. They are still in use and can be retrieved via the ZSR web service.

If a value for the property "clearingNumberDummy" is delivered on the ClearingNumber object, the number in question is a dummy number.

Example of structure:

Code Block
languagejs
{
	"clearingNumber": {
		"clearingNumberDummy": {
			"id": 912
			"name": "CH-Arzt",
		}
	}
}

General information on the paying agent register

How is a valid  number constructed?

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) = 90
90 mod 26 = 12
12th char in the alphabet = L

How is a valid K number constructed?

K numbers consist of a six-digit serial number followed by the letter K.

Sv translation
languageit
return tokenResponse;
            }
        }


Code Block
languagec#
themeConfluence
title5./6./9./10. API resource call using the access token in the Authorization http header
collapsetrue
        /// <summary>
        /// A simple CPR API number search request.
        /// </summary>
        private async Task<BulkResponse> CprApiSampleRequestAsync(string accessToken, CancellationToken ct)
        {
            BulkResponse bulkResponse = new BulkResponse();

            using (var client = new HttpClient())
            {
                client.SetBearerToken(accessToken);

                var response = await client.GetAsync($"https://[CprBaseUrl]/ApiGateway/api/v1/numbers?searchOptions=Okp&offset=0&limit=10", ct).ConfigureAwait(false);

                if (!response.IsSuccessStatusCode)
                    throw new Exception("There was a problem with the request");

                string content = await response.Content.ReadAsStringAsync();

                if (content != null && content.Length > 0)
                {
                    bulkResponse = JsonConvert.DeserializeObject<BulkResponse>(content);
                }
            }

            return bulkResponse;
        }


Code Block
languagec#
themeConfluence
titlePlain API Call (putting everything together)
collapsetrue
        var accessToken = await GetAccessTokenAsync(ct).ConfigureAwait(false);

        var cprApiResponse = await CprApiSampleRequestAsync(accessToken, ct).ConfigureAwait(false);



What are the limits on batch requests?

Batch requests are defined as involving more than 50 requests per minute for a given customer.
Requests from batch processes on online services provided by SASIS AG may only be carried out between 10.00 pm and 4.00 am.
SASIS AG’s online services have limits in place that cause batches of more than 1,000 requests per minute for a given customer to be rejected (http status code 503).

See also the SASIS IT Service Level Agreement.


Why can I only call up 500 numbers in the detail view?

Requests involving the endpoints ClearingNumbers and EmployeeNumbers are limited to 500 numbers for performance reasons. The request process must be planned such that no request contains more than 500 numbers.


Which status codes does the web service return?

The web service uses http status codes. The following codes may be returned:

Status Code

Description

200Success
202Accepted; Request is valid and business process could be triggered successfully.
400Bad Request; The request data is invalid.
401Unauthorized; The caller does not have sufficient privileges to perform the call.
403Forbidden;  The server is refusing the action.
500Internal Server Error; Any unexpected internal failure.



How can 503 errors be avoided?

If the API is overloaded with large numbers of parallel requests, it returns 503 errors. To avoid these, it is very important to follow the instructions for loading the number list and the number details (see also How can data on ZSR and K numbers be requested via the web service?). The number of requests can be reduced further, for example, by requesting only changes via a daily change batch request (see also How can changes be requested?). When a 503 error occurs, it is advisable to wait five minutes before making another request. If possible, customers should check whether API requests can be deferred to a time slot during the night.


How can 400 errors be avoided?

When the client sends an invalid request to the API, it returns a 400 error. To avoid these, it is very important to follow the instructions for loading the number list and the number details (see also How can data on ZSR and K numbers be requested via the web service?). The request process must be planned such that no request contains more than 500 numbers.



ZSR and K number requests

How is the Numbers endpoint used?

The Numbers endpoint delivers ZSR and K numbers that match the filter criteria.

See also How can data on ZSR and K numbers be requested via the web service?


What are the possible filter criteria for the Numbers endpoint?

Filter criteria:

  • filterOptions: limits the numbers returned to specific categories/certifiers. The modules available are as for the subscription options.
  • numberTypes: sets the type of number returned (ZSR or K number).
  • offset: paging value that skips a set number of numbers. As a rule, this can be set to 0.
  • limit: paging value that limits how many numbers are returned. To ensure that all numbers can be loaded at once with a request, a relatively high value can be set here, e.g. 200,000.
  • modifiedFrom: the “modified from” date; see How can changes be requested?


Are extended search functions available?

Extended search queries with filter criteria at field level, e.g. by name and postcode, are not offered via the web service. The full version of ZSR is available for advanced search queries.

For the ZSR web service filter criteria, see the section on data requests.


How can data on ZSR and K numbers be requested via the web service?

Data are requested in two steps.

Step 1 – Loading the number list:

Request all the required ZSR/K numbers via the Numbers endpoint. The filter criteria employed and user authorisations affect the search results. The Numbers endpoint delivers all ZSR/K numbers that match the filter criteria and for which the customer is authorised. It does not deliver ZSR/K numbers that have been suspended for more than ten years.

Filter criteria:

  • filterOptions: limits the numbers returned to specific categories/certifiers. The modules available are as for the subscription options.
  • numberTypes: sets the type of number returned (ZSR or K number).
  • offset: paging value that skips a set number of numbers. As a rule, this can be set to 0.
  • limit: paging value that limits how many numbers are returned. To ensure that all numbers can be loaded at once with a request, a relatively high value can be set here, e.g. 200,000.
  • modifiedFrom: the “modified from” date; see How can changes be requested?

Step 2 – Loading the number details:

The result from step 1 is used to make a request via the appropriate detail endpoint for 500 numbers at a time. The response from the detail endpoint contains the complete number details for which the user is authorised. For performance reasons, it is important to avoid making large numbers of parallel individual requests.

Endpoints:

  • For ZSR numbers: ClearingNumbers endpoint
    For K numbers: EmployeeNumbers endpoint


What are subscription options?

The data delivered via the web service correspond in principle to the data delivered in the backwards-compatible subscriptions. The subscription options depend on the modules to which the customer has subscribed. See Subscription options.


How can the subscription options be changed?

Please contact us.


How is the ClearingNumbers endpoint used?

The ClearingNumbers endpoint delivers details of ZSR numbers.

See How can data on ZSR and K numbers be requested via the web service?


How is the EmployeeNumbers endpoint used?

The EmployeeNumbers endpoint delivers details of K numbers.

See How can data on ZSR and K numbers be requested via the web service?


How can deleted numbers be identified?

If a specialist value has been delivered (with a specific ID/ZSR/K number) but is no longer contained in the response at a later point in time, it is a deleted/cancelled value.


How can changes be requested?

A “modified from” date can be set as a parameter via the Numbers endpoint. The response then contains only numbers that have been changed since that date. Modifications can be specialist in nature or concern purely technical values. Numbers that have been suspended or cancelled for more than ten years are not delivered via the Numbers endpoint. To find out which numbers are affected, all active numbers must first be loaded via the Numbers endpoint. Any numbers that are still active in the client system but are not contained in the results should be cancelled or deleted from the client system.

Once all modified numbers have been loaded, their details can be requested in the usual way via the detail endpoints. The response from these endpoints always contains all available data on a ZSR/K number, not just the values that have been changed.
Changes can be processed from the client system, e.g. by comparing the JSON result from the last request with the JSON result from the new request. The following cases must be borne in mind:

  • An element with the technical ID x exists in the client system and is delivered in the JSON result: it is important to check whether a field value of the element that is relevant for the client system has changed.
  • An element with the technical ID y exists in the client system and is not delivered in the JSON result: all of the element’s field values are regarded as cancelled and must be removed.
  • An element with the technical ID z does not exist in the client system and is delivered in the JSON result: all of the element’s field values are new and must be entered.

The API should always be integrated such that it works regardless of the number of changes reported, i.e. threshold values set by the customer should not cause the data import to fail.


Is it possible to load only ZSR/K numbers that have been changed?

Yes. The filter criterion “modifiedFrom” makes it possible to request changes by date. See also How can changes be requested?


How are changes handled?

  • An element with the technical ID x exists in the client system and is delivered in the JSON result: it is important to check whether a field value of the element that is relevant for the client system has changed.
  • An element with the technical ID y exists in the client system and is not delivered in the JSON result: all of the element’s field values are regarded as cancelled and must be removed.
  • An element with the technical ID z does not exist in the client system and is delivered in the JSON result: all of the element’s field values are new and must be entered.

There are thus two different ways in which a change to an existing value can be delivered:

  • Option 1: with change history → an element with a new technical ID is created every time a field value is changed.
  • Option 2: without change history → the technical ID remains unchanged when a field value is changed.

The final version of the web service will only use Option 1. For the time being, however, integration must ensure that the client systems can handle both options.


Why are some entries suddenly no longer contained in the response?

If an element that was previously delivered in the JSON result no longer appears, this means that is has been cancelled (incorrect data entry/correction after the fact).

We recommend deleting the element from the client system.


Interpreting the data

How are ZSR number relationships delivered in the web service?

  • relatedClearingNumberscontains ZSR number relationships recorded manually by SASIS. These are only kept on record until data confirmed by the service provider are available.
  • ClearingNumberscontains ZSR number relationships confirmed by the service provider.
  • EmployeeNumberscontains K number relationships confirmed by the service provider (these are NOT employee relationships).

To receive all ZSR number relationships, therefore, it is essential to take account of both ClearingNumber.relatedClearingNumbers and CareProvider.ClearingNumbers

Expand
titleExamples


Code Block
titleClearingNumber.relatedClearingNumbers
    "relatedClearingNumbers": [
        {
          "clearingNumber": "B222222",
          "clearingNumberRelationType": "CHANGE_OF_HANDS",
          "clearingNumberRelationTypeTranslations": {
            "de": "Besitzerwechsel",
            "fr": "Changement de propriétaire",
            "it": "Cambiamento di proprietario"
          },
          "id": 520754
        }
      ]


Code Block
titleCareProvider.ClearingNumbers
"clearingNumbers": [
          {
            "number": "N111111"
          }
        ]


Code Block
titleCareProvider.EmployeeNumbers
 "employeeNumbers": [
          {
            "number": "999999K"
          }
        ]

Remarks: Relationship types are not recorded and can thus not be delivered for CareProvider.ClearingNumbers and CareProvider.EmployeeNumbers.

Employee relationships are delivered under clearingNumber.relatedEmployees or in the EmployeeNumbers endpoint under employeeNumber.relatedEmployers.


Questo articolo non è disponibile in italiano.

Panel
titleInhalt

Table of Contents

HTML
<div class="references">
Panel
titleLinks

ApiGateway/swagger/index.html

ApiGateway/swagger/1/swagger.json

Swagger Editor - editor.swagger.io

OpenID Connect - openid.net

OAuth - oauth.net

JSON Web Tokens - jwt.io

ReDoc - redocly.github.io

W3 Status Code Definition - w3.org

Service Level Agreement IT Services SASIS

Opzioni abbonamento

Release Notes

Contatto

Mapping Subscription Files- Webservice

HTML
</div>

Web service integration

Which data can be requested via the ZSR web service?

The data delivered via the web service correspond in principle to the data delivered in the backwards-compatible subscriptions. The modules to which the customer has subscribed thus determine which data can be requested. See Subscription options

Data can be requested on clearing numbers/employee numbers that have not been suspended for more than ten years.

Are the data delivered with the same structure as in the subscription files?

The web service uses a different data model from that of the subscription files. See also Mapping Subscription Files- Webservice.

The key entities are as follows:

  • CareProvider - service provider
  • CareProviderBusiness - location
  • ClearingNumber - ZSR number
  • EmployeeNumber - K number
Expand
titleMain ClearingNumber entities (simplified view)

clearingNumber

  • number (clearingNumber)
  • correspondenceParty (correspondence address)
  • account (bank account)
  • clearingNumberLaws
  • careProvider
    • careProviderParties (addresses)
    • qualifications
    • employeeNumbers
  • careProviderBusinesses (business location)
    • careProviderBusinessParties (addresses)
    • facilities (business facilities)
    • healthServices (certifier methods)
    • affiliations
  • businessScope (OG/UG)
  • businessActivity
  • relatedClearingNumbers
  • relatedEmployees
  • licenses (cantonal authorizations)
  • admissions (cantonal admissions)
  • tariffSystems

Remarks:
This is a highly simplified view – for details, see the Swagger-Schema.
It incorporates the changes set out in the Release Notes ZSR Webservice (24.06.22)

Why was the data model changed (compared with the subscription files)?

The reasons for changing the data model are as follows:

  • Reality check: The old data model allowed multiple sets of master data to be required for the same service provider. This led to a lack of clarity in the specialist data and made uniform identification harder. With the new data model, attention has been paid to ensuring that the legacy data can be collated over time so that a single data set can be delivered for each service provider. The English working title of the application is now CareProviderRegister – the term “paying agent” has been dropped.
  • Specialist data: The old data model could not create a specialist history in all areas. The new data model ensures that a specialist history containing all relevant data can be created and updated easily.
  • Future-proof: The old data model could not easily meet the requirements that will be placed on CareProviderRegister going forward. The new data model offers the flexibility to adapt more quickly to changes in the specialist workflows.

Which response format does the ZSR web service use?

Data are delivered in JSON format (XML is not supported).

Can reference data (master data) be loaded separately?

Reference/master data for ZSR/K number values (methods, qualifications, banks etc.) do not have to be loaded separately. All required data are delivered directly in the detailed response for the individual number.

If needed, reference/master data can be entered separately as follows:

  • All enum values (e.g. gender, canton etc.) are already contained in full in swagger.json (JSON). The Swagger Editor or other tools can be used to generate ZSR web service reference classes automatically, complete with the corresponding enum values.
  • The following values are not contained in swagger.json as enum values, but they can be requested via a dedicated ZSR web service endpoint:
    • Affiliations (association codes)
    • BusinessScopes (partner type groups/sub-groups)
    • ClearingNumberSuffixes (number groups)
    • Countries
    • Facilities (location features)
    • HealthServices (methods)
    • Qualifications
    • TariffSystems

Where can I find the technical API documentation?

An Open API Specification is available.

In addition to Swagger, (for example) ReDoc can be used to display the open API specification: ZSRN-API Live (ReDoc).

Is there a version history for the ZSR web service?

The ZSR web service is currently at version v1.x. For the time being, all changes to the ZSR web service will not be implemented via new versions in parallel operation but will instead be made directly in version v1.x. However, all changes will be published in release notes at the appropriate time and made available via the stage system. The SASIS SLAs apply.

As there will not be a version history for the ZSR web service for the time being, SASIS AG recommends that its integrators follow an adapter pattern that allows changes to the client-system interfaces to the ZSR web service via release-independent settings.

What are the current SASIS AG IT SLAs?

The SASIS IT Service Level Agreement applies to the web service.

Questions and support

Where can I request access to the ZSR web service?

Please contact us to request access to the ZSR web service.

Who can provide support if I have an issue with the ZSR web service?

Please contact us.

Authentication and submitting requests

How do I access the ZSR web service?

Please contact us to request access to the ZSR web service.

How does authentication work?

Authentication is based on OpenID Connect or OAuth 2.0 using password grant.

draw.io DiagrambordertrueviewerToolbartruefitWindowfalsediagramNameapi_access_sequencesimpleViewerfalsewidth600diagramWidth676revision2
  1. The API Client requests the token endpoint from the auth server.
  2. The token endpoint is returned to the API Client.
  3. Request an access token from the auth server by providing the following post request parameters:
    1. grant_type: set to 'password'
    2. client_id: provided individually by SASIS
    3. client_secret: provided individually by SASIS
    4. username: provided individually by SASIS
    5. password: provided individually by SASIS
    6. scope: set constantly to 'openid profile email offline_access roles c1s_profile cpr'
  4. The access token as well as the refresh token is returned to the API Client.
  5. The specific API resource is called providing the access token in as bearer in the Authorization http header:
    'Authorization: Bearer <access token>'
  6. The API responds to the request.
  7. 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:
    1. grant_type: set to 'refresh_token'
    2. client_id: provided individually by SASIS
    3. client_secret: provided individually by SASIS
    4. scope: set constantly to 'openid profile email offline_access roles c1s_profile cpr'
    5. refresh_token: The refresh token received with the last access token.
  8. A new access token as well as a new refresh token is returned to the API Client.
  9. The specific API resource is called providing the new access token in as bearer in the Authorization http header:
    'Authorization: Bearer <access token>'
  10. The API responds to the request.

Access token

The access token response contains additional information:

Code Block
languagejava
titleAccess token response
{
  "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): 

HTML
<div class="references">

CprApiAccessSample.zip

HTML
</div>

Authentication in other languages follows the same procedure.

The following code snippets explain the procedure on a step-by-step basis:

Code Block
languagec#
themeConfluence
title1./2. Retrieve the auth servers token endpoint
collapsetrue
        /// <summary>
        /// Loads the IAM configuration.
        /// </summary>
        private async Task<DiscoveryResponse> GetDiscoveryDocumentAsync(CancellationToken ct)
        {
            using (var client = new HttpClient())
            {
                var discoveryResponse = await client.GetDiscoveryDocumentAsync(new DiscoveryDocumentRequest
                {
                    Address = "[AuthorityUrl]"
                }, ct).ConfigureAwait(false);

                if (discoveryResponse.IsError)
                    throw new Exception(discoveryResponse.Error);

                return discoveryResponse;
            }
        }
Code Block
languagec#
themeConfluence
title3./4. Request access and refresh token
collapsetrue
        /// <summary>
        /// Gets a new token response with a username and password.
        /// </summary>
        private async Task<TokenResponse> RequestTokenAsync(CancellationToken ct)
        {
            using (var client = new HttpClient())
            {
                var discoveryResponse = await GetDiscoveryDocumentAsync(ct).ConfigureAwait(false);

                var tokenResponse = await client.RequestPasswordTokenAsync(new PasswordTokenRequest
                {
                    ClientId = "[ClientId]",
                    ClientSecret = "[ClientSecret]",
                    UserName = "[UserName]",
                    Password = "[Password]",
                    Address = discoveryResponse.TokenEndpoint,
                    GrantType = OidcConstants.GrantTypes.Password,
                    Scope = string.Join(" ", _scopes),
                }, ct).ConfigureAwait(false);

                if (tokenResponse.IsError)
                    throw new Exception(tokenResponse.Error);

                return tokenResponse;
            }
        }
Code Block
languagec#
themeConfluence
title7./8. Token refresh strategy based validity of cached token response and request new access token
collapsetrue
        /// <summary>
        /// Gets the access token by either requesting a new token or by using the refresh token of an already existing token.
        /// </summary>
        private async Task<string> GetAccessTokenAsync(CancellationToken ct)
        {
            if (_tokenResponse == null)
            {
                // Creates a new token response
                _tokenResponse = await RequestTokenAsync(ct).ConfigureAwait(false);
            }
            else
            {
                var jwtSecurityTokenHandler = new JwtSecurityTokenHandler();

                // Parses JWT access token
                var jwtSecurityToken = jwtSecurityTokenHandler.ReadToken(_tokenResponse.AccessToken) as JwtSecurityToken;

                // The access token might be valid now, but expired the very next millisecond.
                // Thus, add a reasonable reserve in minutes for the validity time comparison below.
                var comparisionCorrectionInMinutes = 1;

                // Compares the access token life time with the current time, modified by the comparison correction value.
                if (jwtSecurityToken.ValidTo < DateTime.UtcNow.AddMinutes(comparisionCorrectionInMinutes))
                {
                    // Updates the existing token response
                    _tokenResponse = await RefreshTokenAsync(_tokenResponse.RefreshToken, ct).ConfigureAwait(false);
                }
            }

            return _tokenResponse.AccessToken;
        }

        /// <summary>
        /// Gets an updated token response by using a refresh token.
        /// </summary>
        private async Task<TokenResponse> RefreshTokenAsync(string refreshToken, CancellationToken ct)
        {
            using (var client = new HttpClient())
            {
                var discoveryResponse = await GetDiscoveryDocumentAsync(ct).ConfigureAwait(false);

                var tokenResponse = await client.RequestTokenAsync(new TokenRequest
                {
                    ClientId = "[ClientId]",
                    ClientSecret = "[ClientSecret]",
                    Address = discoveryResponse.TokenEndpoint,
                    ClientCredentialStyle = ClientCredentialStyle.AuthorizationHeader,
                    GrantType = OidcConstants.GrantTypes.RefreshToken,
                    Parameters =
                    {
                        { "refresh_token", refreshToken },
                        { "scope", string.Join(" ", _scopes) }
                    }
                });

                if (tokenResponse.IsError)
                    throw new Exception(tokenResponse.Error);

                return tokenResponse;
            }
        }
Code Block
languagec#
themeConfluence
title5./6./9./10. API resource call using the access token in the Authorization http header
collapsetrue
        /// <summary>
        /// A simple CPR API number search request.
        /// </summary>
        private async Task<BulkResponse> CprApiSampleRequestAsync(string accessToken, CancellationToken ct)
        {
            BulkResponse bulkResponse = new BulkResponse();

            using (var client = new HttpClient())
            {
                client.SetBearerToken(accessToken);

                var response = await client.GetAsync($"https://[CprBaseUrl]/ApiGateway/api/v1/numbers?searchOptions=Okp&offset=0&limit=10", ct).ConfigureAwait(false);

                if (!response.IsSuccessStatusCode)
                    throw new Exception("There was a problem with the request");

                string content = await response.Content.ReadAsStringAsync();

                if (content != null && content.Length > 0)
                {
                    bulkResponse = JsonConvert.DeserializeObject<BulkResponse>(content);
                }
            }

            return bulkResponse;
        }
Code Block
languagec#
themeConfluence
titlePlain API Call (putting everything together)
collapsetrue
        var accessToken = await GetAccessTokenAsync(ct).ConfigureAwait(false);

        var cprApiResponse = await CprApiSampleRequestAsync(accessToken, ct).ConfigureAwait(false);

What are the limits on batch requests?

Batch requests are defined as involving more than 50 requests per minute for a given customer.
Requests from batch processes on online services provided by SASIS AG may only be carried out between 10.00 pm and 4.00 am.
SASIS AG’s online services have limits in place that cause batches of more than 1,000 requests per minute for a given customer to be rejected (http status code 503).

See also the SASIS IT Service Level Agreement.

Why can I only call up 500 numbers in the detail view?

Requests involving the endpoints ClearingNumbers and EmployeeNumbers are limited to 500 numbers for performance reasons. The request process must be planned such that no request contains more than 500 numbers.

Which status codes does the web service return?

The web service uses http status codes. The following codes may be returned:

Status Code

Description

200Success202Accepted; Request is valid and business process could be triggered successfully.400Bad Request; The request data is invalid.401Unauthorized; The caller does not have sufficient privileges to perform the call.403Forbidden;  The server is refusing the action.500Internal Server Error; Any unexpected internal failure.

How can 503 errors be avoided?

If the API is overloaded with large numbers of parallel requests, it returns 503 errors. To avoid these, it is very important to follow the instructions for loading the number list and the number details (see also How can data on ZSR and K numbers be requested via the web service?). The number of requests can be reduced further, for example, by requesting only changes via a daily change batch request (see also How can changes be requested?). When a 503 error occurs, it is advisable to wait five minutes before making another request. If possible, customers should check whether API requests can be deferred to a time slot during the night.

How can 400 errors be avoided?

When the client sends an invalid request to the API, it returns a 400 error. To avoid these, it is very important to follow the instructions for loading the number list and the number details (see also How can data on ZSR and K numbers be requested via the web service?). The request process must be planned such that no request contains more than 500 numbers.

ZSR and K number requests

How is the Numbers endpoint used?

The Numbers endpoint delivers ZSR and K numbers that match the filter criteria.

See also How can data on ZSR and K numbers be requested via the web service?

What are the possible filter criteria for the Numbers endpoint?

Filter criteria:

  • filterOptions: limits the numbers returned to specific categories/certifiers. The modules available are as for the subscription options.
  • numberTypes: sets the type of number returned (ZSR or K number).
  • offset: paging value that skips a set number of numbers. As a rule, this can be set to 0.
  • limit: paging value that limits how many numbers are returned. To ensure that all numbers can be loaded at once with a request, a relatively high value can be set here, e.g. 200,000.
  • modifiedFrom: the “modified from” date; see How can changes be requested?

Are extended search functions available?

Extended search queries with filter criteria at field level, e.g. by name and postcode, are not offered via the web service. The full version of ZSR is available for advanced search queries.

For the ZSR web service filter criteria, see the section on data requests.

How can data on ZSR and K numbers be requested via the web service?

Data are requested in two steps.

Step 1 – Loading the number list:

Request all the required ZSR/K numbers via the Numbers endpoint. The filter criteria employed and user authorisations affect the search results. The Numbers endpoint delivers all ZSR/K numbers that match the filter criteria and for which the customer is authorised. It does not deliver ZSR/K numbers that have been suspended for more than ten years.

Filter criteria:

  • filterOptions: limits the numbers returned to specific categories/certifiers. The modules available are as for the subscription options.
  • numberTypes: sets the type of number returned (ZSR or K number).
  • offset: paging value that skips a set number of numbers. As a rule, this can be set to 0.
  • limit: paging value that limits how many numbers are returned. To ensure that all numbers can be loaded at once with a request, a relatively high value can be set here, e.g. 200,000.
  • modifiedFrom: the “modified from” date; see How can changes be requested?

Step 2 – Loading the number details:

The result from step 1 is used to make a request via the appropriate detail endpoint for 500 numbers at a time. The response from the detail endpoint contains the complete number details for which the user is authorised. For performance reasons, it is important to avoid making large numbers of parallel individual requests.

Endpoints:

  • For ZSR numbers: ClearingNumbers endpoint
    For K numbers: EmployeeNumbers endpoint

What are subscription options?

The data delivered via the web service correspond in principle to the data delivered in the backwards-compatible subscriptions. The subscription options depend on the modules to which the customer has subscribed. See Subscription options.

How can the subscription options be changed?

Please contact us.

How is the ClearingNumbers endpoint used?

The ClearingNumbers endpoint delivers details of ZSR numbers.

See How can data on ZSR and K numbers be requested via the web service?

How is the EmployeeNumbers endpoint used?

The EmployeeNumbers endpoint delivers details of K numbers.

See How can data on ZSR and K numbers be requested via the web service?

WHow can deleted numbers be identified?

If a specialist value has been delivered (with a specific ID/ZSR/K number) but is no longer contained in the response at a later point in time, it is a deleted/cancelled value.

How can changes be requested?

A “modified from” date can be set as a parameter via the Numbers endpoint. The response then contains only numbers that have been changed since that date. Modifications can be specialist in nature or concern purely technical values. Numbers that have been suspended or cancelled for more than ten years are not delivered via the Numbers endpoint. To find out which numbers are affected, all active numbers must first be loaded via the Numbers endpoint. Any numbers that are still active in the client system but are not contained in the results should be cancelled or deleted from the client system.

Once all modified numbers have been loaded, their details can be requested in the usual way via the detail endpoints. The response from these endpoints always contains all available data on a ZSR/K number, not just the values that have been changed.
Changes can be processed from the client system, e.g. by comparing the JSON result from the last request with the JSON result from the new request. The following cases must be borne in mind:

  • An element with the technical ID x exists in the client system and is delivered in the JSON result: it is important to check whether a field value of the element that is relevant for the client system has changed.
  • An element with the technical ID y exists in the client system and is not delivered in the JSON result: all of the element’s field values are regarded as cancelled and must be removed.
  • An element with the technical ID z does not exist in the client system and is delivered in the JSON result: all of the element’s field values are new and must be entered.

The API should always be integrated such that it works regardless of the number of changes reported, i.e. threshold values set by the customer should not cause the data import to fail.

Is it possible to load only ZSR/K numbers that have been changed?

Yes. The filter criterion “modifiedFrom” makes it possible to request changes by date. See also How can changes be requested?

How are changes handled?

  • An element with the technical ID x exists in the client system and is delivered in the JSON result: it is important to check whether a field value of the element that is relevant for the client system has changed.
  • An element with the technical ID y exists in the client system and is not delivered in the JSON result: all of the element’s field values are regarded as cancelled and must be removed.
  • An element with the technical ID z does not exist in the client system and is delivered in the JSON result: all of the element’s field values are new and must be entered.

Interpreting the data

How are K numbers and ZSR numbers linked?

The CareProvider (service provider) is a property on the detail record for a ZSR/K number.

ClearingNumber → CareProvider (service provider)
EmployeeNumber → CareProvider (service provider)Employment relationships are shown as follows:
ClearingNumber → RelatedEmployees (all employees linked to a ZSR number)
EmployeeNumber → RelatedEmployers (all employers linked to a K number)

On which data is the displayed validity period of a ZSR/K number based?

The validity of a ZSR/K number is no longer defined only as a time period with a start date and an end date. It is now defined using multiple time periods (ValidityPeriods), which are delivered as a list. The list clearly shows gaps in validity.

Validity periods are defined as follows::

ClearingNumber

  • Mandatory health insurance: start date (S5) to end date (S6) minus any past or active suspension periods.
  • Partner type groups 52/56: all aggregated periods of the methods (HealthServices) plus any periods for location features (Facilities) such as FitnessClassification or SPAK recognition.

EmployeeNumber

  • All aggregated periods of the employment relationshipsperiods of the employment relationships.


What must be borne in mind when multiple validity periods exist (e.g. clearingNumber.validityPeriods)?

Unlike the subscription files, the web service can deliver multiple validity periods for the same element. In principle, all available validity periods should be carried over in order to maintain a complete history. If this is not possible, we recommend using the most up-to-date or most recent validity period.


How can I tell the difference between a bank account and a post office account?

The ZSR web service no longer distinguishes between bank and post office accounts.

The field “hasPaymentOrderReferenceNumber” under ClearingNumberAccount shows whether payments using a standard Swiss payment slip are possible.

Endpoint: ClearingNumbers; object: ClearingNumberAccount

a standard Swiss payment slip are possible.

Endpoint: ClearingNumbers; object: ClearingNumberAccount


What do the data items “0001-01-01” and “9999-12-31” mean?

The ZSR web service always delivers a start date and an end date for time periods, even if it is not possible to determine the exact dates due to the legacy data or for other reasons.

Placeholder values for the start and end date are therefore used. These are to be interpreted as follows:

  • “0001-01-01” is a placeholder value for the start date and means that the actual start date is not known (NULL).
  • “9999-12-31” is a placeholder value for the end date and means that the actual end date is not known (NULL).

A time period with the start date

What do the data items

“0001-01-01” and the end date “9999-12-31”

mean?

The ZSR web service always delivers a start date and an end date for time periods, even if it is not possible to determine the exact dates due to the legacy data or for other reasons.

Placeholder values for the start and end date are therefore used. These are to be interpreted as follows:

  • “0001-01-01” is a placeholder value for the start date and means that the actual start date is not known (NULL).
  • “9999-12-31” is a placeholder value for the end date and means that the actual end date is not known (NULL).

A time period with the start date “0001-01-01” and the end date “9999-12-31” is thus valid for any given point in time.

Are technical IDs delivered?

The IDs delivered in the detailed response have no specialist meaning and should not be used to interpret values. They are purely technical identifiers of the delivered data and can serve to process changes (see How can changes be requested? and How are changes handled?).

Ideally, technical IDs would not be used at all as permanence is not guaranteed. This applies to both volatile, technical IDs of allocations and technical IDs of “master data”, e.g. canton, country etc., even if these are in principle maintained.

In addition, no technical IDs whatsoever are delivered for the main ZSR/K number record. Identification is only possible using the ZSR/K number itself. A replacement for the old paying agent ID is not delivered.

How can dummy numbers be identified?

is thus valid for any given point in time.


Are technical IDs delivered?

Element id

The IDs delivered in the detailed response have no specialist meaning and should not be used to interpret values. They are purely technical identifiers of the delivered data and can serve to process changes (see How can changes be requested? and How are changes handled?). No logic should ever be coded to technical IDs.

In addition, no technical IDs whatsoever are delivered for the main ZSR/K number record. Identification is only possible using the ZSR/K number itself. A replacement for the old paying agent ID is not delivered.

Element key

Master/reference data, e.g. canton, country, qualification etc., are delivered with a permanent GUID as identifier. See also Can reference data (master data) be loaded separately?

Unique identification is possible using the element “key” (string) for the following entities: 

  • Affiliations
  • BusinessScopes
  • ClearingNumberSuffixes
  • Countries
  • Facilities
  • HealthServices
  • Qualifications
  • TariffSystems

Example: "key": "3fa85f64-5717-4562-b3fc-2c963f66afa6"


How can dummy numbers be identified?

So-called “dummy” numbers are a legacy construct. They are still in use and can be retrieved via the ZSR web service.

If a value for the property "clearingNumberDummy" is delivered on the ClearingNumber object, the number in question is a dummy number.

Example of structure:

Code Block
languagejs
{
	"clearingNumber": {
		"clearingNumberDummy": {
			"id": 912
			"name": "CH-Arzt",
		}
	}
}



How are partner type groups/sub-groups displayed in the web service?

All service providers apart from doctors

  • The partner type group value is always delivered in the field “parentBusinessScope”.
  • The partner type sub-group value, if available, is delivered in the field “businessScope”.
  • Otherwise, the partner type group value is delivered.

Doctors
Doctors are categorised in terms of business scope and business activity.


The “businessScope”/”parentBusinessScope” values can be queried in the web service via the BusinessScopes endpoint: /api/v1/businessscopes.

The “businessActivity” values appear as enum values in swagger.json (JSON).


So-called “dummy” numbers are a legacy construct. They are still in use and can be retrieved via the ZSR web service.

If a value for the property "clearingNumberDummy" is delivered on the ClearingNumber object, the number in question is a dummy number.

Example of structure:

Code Block
languagejs
{
	"clearingNumber": {
		"clearingNumberDummy": {
			"id": 912
			"name": "CH-Arzt",
		}
	}
}

General information on the paying agent register

How is a

valid 

valid number constructed?

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) = 90
90 mod 26 = 12
12th char in the alphabet = L


How is a valid K number constructed?

K numbers consist of a six-digit serial number followed by the letter K.






Sv translation
languageit

Questo articolo non è disponibile in italiano.