^{Integration des Webservices}

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

Welche Daten abgefragt werden können ist also abhängig von den Modulen die der Kunde abonniert hat. Siehe Abo-Optionen

Werden sistierte (inaktive) Nummern über den ZSR Webservice ausgeliefert?

ZSR Webservice liefert sistierte ZSR- wie auch K-Nummer aus, sofern die Sistierung nicht länger als 10 Jahre zurückliegt. 

Ein sistierter Leistungserbringer, bzw. Angestellter kann wie folgt identifiziert werden: Zum Abfragezeitpunkt besteht keine gültige validityPeriod.

Warum erhalte ich keine Response auf eine angefragte Nummer?

Wenn eine Nummer abgefragt wird und keine Werte geliefert werden, ist die Nummer:

• nicht bei SASIS AG vorhanden.
• storniert, weil sie irrtümlich erstellt wurde. Das heisst, sie war fachlich nie gültig.
• archiviert. Spätestens 10 Jahre nach Inaktivsetzung wird eine Nummer archiviert.

Wie sieht das Datenmodell beim ZSR Webservice aus?

Werden gelöschte Nummern über den Webservice geliefert?

Nummern werden gelöscht, wenn diese irrtümlicherweise erteilt wurden und nie fachlich gültig waren oder wenn diese vor mehr als 10 Jahren sistiert wurden (siehe sistierte Nummern).

Integratoren wird folgendes Vorgehen empfohlen, um gelöschte Nummern zu erkennen:

• Laden aller Nummern über den Endpoint Numbers ohne Wert in modifiedFrom und Offset 0 und Limit 150'000. Die Liste enthält alle publizierten Nummern abzüglich der gelöschten Nummern.  
• Vergleich des Outputs mit den im eigenen System geführten Nummern. Alle Nummer, die im eigenen System vorhanden nicht aber im Output enthalten sind, müssen als gelöscht verarbeitet werden. 

Warum erhalte ich keine Response auf eine angefragte Nummer?

Wenn eine Nummer abgefragt wird und keine Werte geliefert werden, ist die Nummer:

• nicht bei santéservices ag  vorhanden.
• storniert, weil sie irrtümlich erstellt wurde. Das heisst, sie war fachlich nie gültig.
• archiviert. Spätestens 10 Jahre nach Inaktivsetzung wird eine Nummer archiviert.

Wie sieht das Datenmodell beim ZSR Webservice aus?

Die wichtigsten Entitäten sind:

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

Hauptentitäten einer ClearingNumber (Zahlstelle):

• number (ZSR-Nummer)
• correspondenceParty (

Die wichtigsten Entitäten sind:

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

Hauptentitäten einer ClearingNumber (Zahlstelle):

• number (ZSR-Nummer)
• correspondenceParty (Korrespondenzadresse)
• clearingNumberSuffix (Nummernkreis = letzte beiden Ziffern einer ZSR-Nummer)
• 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 (PaOG/PaUG)
• businessActivity (Haupttätigkeit Ärztin/Arzt)
• relatedClearingNumbers (zugeordnete Zahlstellen/Zusätzliche Zahlstellen)
• relatedEmployees (Arbeitnehmer/Angestellte)
• licenses (Kantonale Bewilligung)
• admissions (Kantonale Zulassung)
• validityPeriods (Gültigkeit der Nummer)

Hinweise:
Es handelt sich um eine stark vereinfachte Darstellung - für Details siehe Swagger-Schema.

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)
  • BusinessActivities
  • BusinessScopes (PAOG/PAUG)
  • CareProviderCertification
  • ClearingNumberSuffixes (Nummernkreise)
  • Countries (Länder)
  • Distribution Types
  • Facilities (Standorteigenschaften)
  • FunctionalUnits
  • HealthServices (Methoden)
  • Qualifications (Qualifikationen)

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.

• Swagger: Das Swagger UI ermöglicht, Einzelabfragen zu testen. Die Darstellung mittels Swagger ist jedoch bezüglich Property-Darstellung von mehrfach vererbten Entitäten nicht abschliessend, d.h. es werden nicht alle Properties von Entitäten in Swagger-UI angezeigt,
• Redocly: Als alternatives GUI wird Redocly zusätzlich zu Swagger-UI zur Verfügung gestellt. Entitäten von json werden hier immer mit allen Properties dargestellt. Die Ansicht des json kann unter /ApiGateway/docs aufgerufen werden: Live-System: https://zsrnext.ch/ApiGateway/docs

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 https://www.sasis.ch/sharepoint/public/service-level-agreement.pdf Service Level Agreement SLA.

Steht den Kunden eine Integrationsumgebung zur Verfügung?

Für die Integration des ZSR-Webservices sowie für vorgängiges Testing von neuen Webservice-Versionen steht unter int.zsrnext.ch/ eine Integrationsplattform bereit.
Der Datenstand der Integrationsplattform wird wöchentlich jeden Mittwoch Morgen mit einer Kopie von Live aktualisiert. Aufgrund der Datenaktualisierung sowie Wartungsarbeiten ist auf der Integrationsplattform jeden Mittwoch von 06:00 bis 12:00 mit Unterbrüchen zu rechnen.

Wie lauten die aktuellen IT-SLA der

santéservices ag

Für den Webservice kommt das  Service Level Agreement  der SASIS IT SLA der santéservices 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.

Access token

The access token response contains additional information:

{
  "access_token": "MTQ0NjOkZmQ5OTM5NDE9ZTZjNGZmZjI3",
  "refresh_token": "GEbRxBNZmQOTM0NjOkZ5NDE9ZedjnXbL",
  "token_type": "bearer",
  "expires_in": 300,
  "scope": "openid profile email offline_access roles c1s_profile cpr"
}

The token itself is a JWT and can therefore be decoded on the JWT website.

The expires_in field defines the validity period of the token in seconds. Afterwards, a new token must be retrieved.

Code samples

A complete c# sample shows how to access one specific API resource (numbers): 

<div class="references">

CprApiAccessSample.zip

</div>

Authentication in other languages follows the same procedure.

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

        /// <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;
            }
        }

        /// <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;
            }
        }

        /// <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;
            }
        }

        /// <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;
        }

        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 santéservices ag dürfen ausschliesslich zwischen 22.00 und 4.00 Uhr durchgeführt werden.
Die Online-Dienste der SASIS AG sind santéservices 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 ServicesSLAder santéservices ag 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:

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. 400er-Fehler können ebenfalls auftreten wenn die Abfrage von einem Absender gesendet wird, der nicht in der Whitelist der WAF (Web Application Firewall) für den entsprechenden User konfiguriert wurde! Bitte nehmen sie in diesem Fall mit uns Kontakt auf und teilen sie uns die IP (oder den IP-Range) mit, von wo die Abfrage erfolgt.

^{Abfrage von ZSR- und K-Nummern}

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. 

Endpoints:

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

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.

 Kann ich nach bestimmten Eigenschaften einer ZSR- oder K-Nummer suchen?

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. 

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 Eigenschaftswerte identifiziert werden?

Wenn ein Eigenschaftswerte einer ZSR-Nummer 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.

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.

^{Interpretation der Daten}

Wie werden ZSR-Nummern Beziehungen im Webservice geliefert?

• ClearingNumber.relatedClearingNumbers enthält durch die SASIS manuell santéservices 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.

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

"clearingNumbers": [
          {
            "number": "N111111"
          }
        ] 

 "employeeNumbers": [
          {
            "number": "999999K"
          }
        ] 

Wie werden Angestelltenverhältnisse im Webservice geliefert?

Angestelltenverhältnisse werden unter clearingNumber.relatedEmployees geliefert.

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
• Distribution Types
• Facilities
• FunctionalUnits
• HealthServices
• Qualifications

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

Wie können Dummy-Nummern identifiziert werden?

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