| Sv translation | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Integration des WebservicesWelche 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 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 MappingAboFiles_Webservice_2025_09_26.xlsx. Die wichtigsten Entitäten sind
Expand |
clearingNumber (Zahlstelle)
Es handelt sich um eine stark vereinfachte Darstellung - für Details siehe Swagger-Schema. Weshalb wurde das Datenmodell (im Vergleich zu den Abo-Files) verändert?Gründe für die Änderung des Datenmodells:
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:
Die eindeutige Identifikation der Stammdaten ist über das Element "key" (string) möglich. Siehe Werden technische Id's geliefert? 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. 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. 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. 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. Wie lauten die aktuellen IT-SLA der SASIS AGFür den Webservice kommt das Service Level Agreement der SASIS IT Services zur Anwendung. Anfragen und SupportWo 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 AbfragenWie 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:
The token itself is a JWT and can therefore be decoded on the JWT website. The expires_in field defines the validity period of the token in seconds. Afterwards, a new token must be retrieved. Code samples A complete c# sample shows how to access one specific API resource (numbers):
Authentication in other languages follows the same procedure. The following code snippets explain the procedure on a step-by-step basis:
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. 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:
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-NummernWie 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:
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:
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:
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:
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?
Es gibt somit zwei Varianten wie eine Veränderung eines bestehenden Wertes geliefert werden kann:
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 DatenWie werden ZSR-Nummern Beziehungen im Webservice geliefert?
Um die Gesamtheit der ZSR-Nummern Beziehungen zu erhalten, müssen somit sowohl ClearingNumber.relatedClearingNumbers wie auch CareProvider.ClearingNumbers berücksichtigt werden.
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
EmployeeNumber
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:
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:
Beispiel: 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:
Wie werden Partnerart-Obergruppe/Partnerart-Untergruppe im Webservice ausgewiesen?Alle Leistungserbringer ausser Ärzte und Ärztinnen
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_2025_09_26.xlsx,Tabs PAOG_BusinesssScope, PAOG_BusinesssScope, PAUG_BusinessActivities Allgemeine Informationen zum ZahlstellenregisterWie 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 Berechnung Prüfbuchstabe
(9*1)+(1*2)+(5*3)+(8*4)+(4*5)+(2*6)=90 Beispiel: Y274589 (9*1)+(8*2)+(5*3)+(4*4)+(7*5)+(2*6)=103 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). |
...