| 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 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. 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. draw.io Diagram | border | true | viewerToolbar | true | fitWindow | false | diagramName | api_access_sequence | simpleViewer | false | width | 600 | diagramWidth | 676 | revision | 2 |
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. 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:
Warum erhalte ich keine Response auf eine angefragte Nummer?Wenn eine Nummer abgefragt wird und keine Werte geliefert werden, ist die Nummer:
Wie sieht das Datenmodell beim ZSR Webservice aus?Die wichtigsten Entitäten sind:
Hauptentitäten einer ClearingNumber (Zahlstelle):
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 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. Wie lauten die aktuellen IT-SLA der santéservices agFür den Webservice kommt das Service Level Agreement SLA der santéservices 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:
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 santéservices ag dürfen ausschliesslich zwischen 22.00 und 4.00 Uhr durchgeführt werden. 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-NummernAbfrage von ZSR- und K-NummernWie 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. Endpoints:
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. Für die Filterkriterien des Webservice siehe Datenabfrage. 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öschteNummernEigenschaftswerte identifiziert werden?Wenn ein fachlicher Wert 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:
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. 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. 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
"Ä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_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). Nach welcher Logik werden die Qualifikationen zugeordnet?qualificationTitleType Wir weisen aus, ob es sich um eine eidgenössische oder durch MEBEKO anerkannte Qualifikation handelt. Diese Differenzierung ist möglich bei Diplomen (qualificationGroupeTyp "DIPLOMA") oder Weiterbildungstitel (qualificationGroupType "POSTGRADUATE_TITLE"). Bei den privatrechtlichen Weiterbildungstitel (qualificationGroupeTyp "PRIVATE_LAW_POSTGRADUATE_TITLE") handelt es sich immer um eidgenössische Titel. Wir führen aktuell "UNKNOWN". Mögliche Werte:
qualificationGroupType Analoge Struktur gemäss MedReg. Unterteilung der Qualifikationen in die Typen Diplom, Weiterbildungstitel und privatrechtliche Weiterbildungstitel. Mögliche Werte:
Im Unterschied zum qualificationGroupeTyp werden die privatrechtlichen Weiterbildungstitel (PRIVATE_LAW_POSTGRADUATE_TITLE) differenziert ausgewiesen in Fähigkeitsausweis (SIWF_CERTIFICATE) und Schwerpunkt (SIWF_SPECIALIZATION). Mögliche Werte:
Zusammenfassend entsprechen für im Medreg geführte Partnerartobergruppen (Doctor, Pharmacist, Chiropractor, Dentist) der QualificationType dem Medreg "Privatrechtliche WB Typ", der QualificationTitleType dem Medreg Diplom-/Weiterbildungstyp und der QualificationGroupType der Medreg Unterteilung in Diplom, Weiterbildungstitel und privatrechtliche Weiterbildungstitel. Für alle anderen OG's wird für QualificationGroupType und QualificationTitleType "Unknown" geführt. Bei QualificationType wird je nach OG noch zwischen Diploma, Certificate, Admission, LaboratoryPostgraduateTitle, LaboratorySpecialization, OrthopedicShoeTechnologyPostgraduateTitle unterschieden. 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 können Sie via Webservice über den Endpoint «BusinessActivities» abfragen: /api/v1/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). |
| Sv translation | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Web service integrationWhich data can be requested via the ZSR web service?The modules to which the customer has subscribed thus determine which data can be requested. See Subscription options Do inactive (suspended) numbers get delivered via the ZSR Webservice?The ZSR Webservice delivers suspended ZSR numbers as well as K numbers, provided that the suspension occurred no more than 10 years ago. Are deleted numbers delivered via the web service?Numbers are deleted if they were issued in error and were never valid, or if they were suspended more than 10 years ago (see Suspended Numbers). Integrators are advised to use the following procedure to identify deleted numbers:
Why do I not receive a response for a requested number?If a number is queried and no values are returned, the number is:
What does the data model of the ZSR Webservice look like?The most important entities are:
Main entities of a ClearingNumber (Clearing Number):
Notes: 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:
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. Swagger: Redocly: 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 Service Level Agreement SLAapply. Is an integration environment available to customers?An integration platform is available at int.zsrnext.ch/ for integrating the ZSR web service and for pre-testing new web service versions. What are the current santéservices ag IT SLAs?The santéservices IT Service Level Agreement SLA applies to the web service. Questions and supportWhere 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 requestsHow 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.
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:
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Sv translation | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Web service integrationWhich data can be requested via the ZSR web service?The modules to which the customer has subscribed thus determine which data can be requested. See Subscription options 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:
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. Is an integration environment available to customers?An integration platform is available at int.zsrnext.ch/ for integrating the ZSR web service and for pre-testing new web service versions. What are the current SASIS AG IT SLAs?The SASIS IT Service Level Agreement applies to the web service. Questions and supportWhere 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 requestsHow 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 | border | true | viewerToolbar | true | fitWindow | false | diagramName | api_access_sequence | simpleViewer | false | width | 600 | diagramWidth | 676 | revision | 2 |
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:
What are the limits on batch requests?Batch requests are defined as involving more than 50 requests per minute for a given customer. See also the SASIS IT Service Level Agreement. Why can I only call up 500 numbers in the detail view?
What are the limits on batch requests?Batch requests are defined as involving more than 50 requests per minute for a given customer. See also the santéservices IT Service Level Agreement SLA. 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:
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?)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: 400 errors may also occur if the query is sent from a sender that has not been configured in the WAF (Web Application Firewall) whitelist for the relevant user. In this case, please contact us and provide the IP address (or IP range) from which the query is being made. ZSR and K number requestsHow 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:
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. Endpoints:
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. Can I search for specific properties of a ClearingNumber or EployeeNumbers?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. 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? According to which logic are qualifications assigned?qualificationTitleType Possible values:
qualificationGroupType Analogous structure according to MedReg. Division of qualifications into the types diploma, postgraduate title, and private-law postgraduate title. Possible values:
qualificationType Possible values:
Summary: For all other parent groups, "Unknown" is used for QualificationGroupType and QualificationTitleType. For QualificationType, further distinctions are made depending on the parent group, such as Diploma, Certificate, Admission, LaboratoryPostgraduateTitle, LaboratorySpecialization, and OrthopedicShoeTechnologyPostgraduateTitle. Status Code Description 200 | Success | 202 | Accepted; Request is valid and business process could be triggered successfully. | 400 | Bad Request; The request data is invalid. | 401 | Unauthorized; The caller does not have sufficient privileges to perform the call. | 403 | Forbidden; The server is refusing the action. | 500 | Internal Server Error; Any unexpected internal failure. | 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 requestsHow 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:
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. Endpoints:
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. Can I search for specific properties of a ClearingNumber or EployeeNumbers?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. 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.
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?
There are thus two different ways in which a change to an existing value can be delivered:
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 dataHow are ZSR number relationships delivered in the web service?
To receive all ZSR number relationships, therefore, it is essential to take account of both ClearingNumber.relatedClearingNumbers and CareProvider.ClearingNumbers
Employee relationships are delivered under clearingNumber.relatedEmployees or in the EmployeeNumbers endpoint under employeeNumber.relatedEmployers. 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:
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?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:
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:
How are partner type groups/sub-groups displayed in the web service?All service providers apart from doctors
Doctors 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)can be queried in the web service via the BusinessActivities endpoint: /api/v1/businessactivities. General information on the paying agent registerHow is a valid number constructed?The clearing number has the following structure:
The leading char of the clearing number is created and validated as follows:
Example L248519: How is a valid K number constructed?K numbers consist of a six-digit serial number followed by the letter K. |
...