diff --git a/directoryAPI.yaml b/directoryAPI.yaml index e2b047d..b55a06b 100644 --- a/directoryAPI.yaml +++ b/directoryAPI.yaml @@ -1,218 +1,218 @@ -openapi: 3.0.1 -info: - title: Central Directory - version: 0.5.2-beta - # yamllint disable rule:indentiation - description: | - # Zentrales Verzeichnis API (deutsch) - - **** Deutsch (for English see below) **** - - Das Zentrale Verzeichnis API liefert Informationen zu allen beteiligten Parteien. Dies umfasst einerseits Pensionskassen, - die das OpenPK-API implementieren, und andererseits Applikationen, die über das OpenPK-API auf Daten zugreifen. - - Im Unterschied zu allen anderen APIs wird das Verzeichnis API nicht von jeder Pensionskasse, sondern nur einmal - von einem zentralen Dienst implementiert. - - **Applikationen** nutzen das Verzeichnis-API, um dem Benutzer eine Liste von Pensionskassen anzuzeigen, damit der - Benutzer seine Pensionskasse auswählen kann. Ist die Auswahl getroffen, so liefert das Verzeichnis-API alle - technischen Angaben, um auf die OpenPK-Implementierung der gewählten Pensionskasse zuzugreifen. Insbesondere - werden die Basis-URLs der API-Endpunkte geliefert. - - **Pensionskassen** nutzen das Verzeichnis-API, um Informationen über die Applikationen zu bekommen, die über das - OpenPK-API auf ihre Dienste zugreifen, zu bekommen. - - Verzeichnis-Daten ändern nur langsam. Applikationen und Pensionskasse werden ermuntert, diese Daten gesamthaft - herunterzuladen, zwischenzuspeichern und nur alle 12 bis 24 Stunden erneut abzufragen. - - - # Central Directory API (English) - - **** English (für Deutsch siehe weiter oben) **** - - The Central Directory API provides information about the participating parties. It includes pension funds implementing - the OpenPK API as well as application using the OpenPK API to access data. - - Unlike all other OpenPK APIs, this API is not implemented by several pension funds but only once by a central party. - - **Applications** use the Central Directory API to show a list of pension funds and have the user select his/her pension - fund. Once the selection is made, the directory API provides the technical details to contact the pension fund's - OpenPK implementation. In particular the base URLs of the API endpoints are provided. - - **Pension funds** use the directory API to get information about the applications accessing their OpenPK services. - - Directory data does not change often. Applications and pension funds are encouraged to download the directory data - in its entirety, cache it and refresh it every 12 to 24 hours. - # yamllint enable rule:indentiation - - contact: - name: OpenPK Project / Acrea AG - url: https://www.openpkproject.ch - email: openpkproject@acrea.com - - license: - name: Creative Commons Attribution 4.0 International License - url: http://creativecommons.org/licenses/by/4.0/ - - x-logo: - url: https://api-spec-dot-acrea-openpk.appspot.com/images/openpk_hori.svg - altText: OpenPK - -tags: - - name: pension-funds - description: Pension fund directory - -servers: - - url: https://directory-dot-acrea-openpk.appspot.com/v1 - -paths: - /pension-funds: - get: - operationId: getPensionFunds - tags: - - pension-funds - summary: Get list of pension funds - description: | - Provides the complete list of participating pension funds, incl. pension funds - that plan to participate soon and funds that have participated in the past. - responses: - '200': - description: | - List of pension funds with technical data for connecting to the OpenPK APIs - content: - application/json: - schema: - $ref: '#/components/schemas/PensionFunds' - examples: - ex1: - summary: Abbreviated pension fund list - value: - - - 'id': SG 0227, - - 'name': BVG-Stiftung der Plaston AG, - - 'nameDe': BVG-Stiftung der Plaston AG, - - 'address': c/o Alvisa Services AG, Seestrasse 6, 8027 Zürich, - - 'openpkStatus': active, - - 'openpkServices': - - 'authorizeUrl': https://iam.company.com/pensionfund/auth/authorize, - - 'grantUrl': https://star-fund-dot-acrea-openpk.appspot.com/consent, - - 'identityProvider': https://iam.company.com/pensionfund, - - 'tokenEndpoint': https://iam.company.com/pensionfund/auth/token, - - 'policyEndpoint': https://star-fund-dot-acrea-openpk.appspot.com/v1, - - 'consentEndpoint': https://star-fund-dot-acrea-openpk.appspot.com/v1 - - - 'id': SR-200127, - - 'name': Fonds de prévoyance en faveur du personnel du groupe SICPA en Suisse, - - 'nameFr': Fonds de prévoyance en faveur du personnel du groupe SICPA en Suisse, - - 'address': Avenue Florissant 41 Case postale, 1000 Lausanne 16, - - 'openpkStatus': active, - - 'openpkServices': - - 'authorizeUrl': https://identity.pensionfund.ch/auth/authorize, - - 'grantUrl': https://star-fund-dot-acrea-openpk.appspot.com/consent, - - 'identityProvider': https://identity.pensionfund.ch, - - 'tokenEndpoint': https://identity.pensionfund.ch/auth/token, - - 'policyEndpoint': https://star-fund-dot-acrea-openpk.appspot.com/v1, - - 'consentEndpoint': https://star-fund-dot-acrea-openpk.appspot.com/v1 - -components: - schemas: - PensionFunds: - type: array - description: List of pension funds - items: - $ref: '#/components/schemas/PensionFund' - - PensionFund: - type: object - description: Pension fund incl. technical service data - required: - - name - - id - - openpkStatus - properties: - id: - type: string - description: Pension fund ID - name: - type: string - description: Pension fund name in fund's preferred language - nameDe: - type: string - description: Pension fund name in German - nameEn: - type: string - description: Pension fund name in English - nameFr: - type: string - description: Pension fund name in French - nameIt: - type: string - description: Pension fund name in Itlian - nameRm: - type: string - description: Pension fund name in Rhaeto-Romanic - webUrl: - type: string - format: uri - description: URL of pension funds web site - logoUrl: - type: string - format: uri - description: | - Image URL of pension fund logo - (at least 200 by 200 pixels, suitable for display on white background, - JPEG or PNG format) - openpkStatus: - type: string - description: | - OpenPK API status: - * `active`: The APIs are active. - * `onboarding`: The APIs will soon be active. - * `paused`: The APIs have been paused. - * `notJoined`: The pension fund does not provide APIs. - enum: - - active - - onboarding - - paused - - notJoined - address: - type: string - description: Pension fund address. Text excl. name. - openpkServices: - description: Technical description of API service - $ref: '#/components/schemas/ServicesDescription' - - ServicesDescription: - type: object - description: Technical description of API service - required: - - authorizeUrl - - tokenEndpoint - - grantUrl - properties: - authorizeUrl: - type: string - format: uri - description: URL to initiate the user authentication interaction - grantUrl: - type: string - format: uri - description: URL to initate the user interaction for granting access - identityProvider: - type: string - format: uri - description: | - URL of identity provider and issuer of credentials. - Open ID Connect discovery URLs derived relative to this URL, - e.g. `https://iam.company.com/iam/.well-known/openid-configuration` - for the issuer URL `https://iam.company.com/iam`. - tokenEndpoint: - type: string - format: uri - description: Endpoint URI to request access token - policyEndpoint: - type: string - format: uri - description: Endpoint URI to query insured person and policy data - consentEndpoint: - type: string - format: uri - description: Endpoint URI to query the granted consents +openapi: 3.0.1 +info: + title: Central Directory + version: 0.5.2-beta + # yamllint disable rule:indentiation + description: | + # Zentrales Verzeichnis API (deutsch) + + **** Deutsch (for English see below) **** + + Das Zentrale Verzeichnis API liefert Informationen zu allen beteiligten Parteien. Dies umfasst einerseits Pensionskassen, + die das OpenPK-API implementieren, und andererseits Applikationen, die über das OpenPK-API auf Daten zugreifen. + + Im Unterschied zu allen anderen APIs wird das Verzeichnis API nicht von jeder Pensionskasse, sondern nur einmal + von einem zentralen Dienst implementiert. + + **Applikationen** nutzen das Verzeichnis-API, um dem Benutzer eine Liste von Pensionskassen anzuzeigen, damit der + Benutzer seine Pensionskasse auswählen kann. Ist die Auswahl getroffen, so liefert das Verzeichnis-API alle + technischen Angaben, um auf die OpenPK-Implementierung der gewählten Pensionskasse zuzugreifen. Insbesondere + werden die Basis-URLs der API-Endpunkte geliefert. + + **Pensionskassen** nutzen das Verzeichnis-API, um Informationen über die Applikationen zu bekommen, die über das + OpenPK-API auf ihre Dienste zugreifen, zu bekommen. + + Verzeichnis-Daten ändern nur langsam. Applikationen und Pensionskasse werden ermuntert, diese Daten gesamthaft + herunterzuladen, zwischenzuspeichern und nur alle 12 bis 24 Stunden erneut abzufragen. + + + # Central Directory API (English) + + **** English (für Deutsch siehe weiter oben) **** + + The Central Directory API provides information about the participating parties. It includes pension funds implementing + the OpenPK API as well as application using the OpenPK API to access data. + + Unlike all other OpenPK APIs, this API is not implemented by several pension funds but only once by a central party. + + **Applications** use the Central Directory API to show a list of pension funds and have the user select his/her pension + fund. Once the selection is made, the directory API provides the technical details to contact the pension fund's + OpenPK implementation. In particular the base URLs of the API endpoints are provided. + + **Pension funds** use the directory API to get information about the applications accessing their OpenPK services. + + Directory data does not change often. Applications and pension funds are encouraged to download the directory data + in its entirety, cache it and refresh it every 12 to 24 hours. + # yamllint enable rule:indentiation + + contact: + name: OpenPK Project / Acrea AG + url: https://www.openpkproject.ch + email: openpkproject@acrea.com + + license: + name: Creative Commons Attribution 4.0 International License + url: http://creativecommons.org/licenses/by/4.0/ + + x-logo: + url: https://api-spec-dot-acrea-openpk.appspot.com/images/openpk_hori.svg + altText: OpenPK + +tags: + - name: pension-funds + description: Pension fund directory + +servers: + - url: https://directory-dot-acrea-openpk.appspot.com/v1 + +paths: + /pension-funds: + get: + operationId: getPensionFunds + tags: + - pension-funds + summary: Get list of pension funds + description: | + Provides the complete list of participating pension funds, incl. pension funds + that plan to participate soon and funds that have participated in the past. + responses: + '200': + description: | + List of pension funds with technical data for connecting to the OpenPK APIs + content: + application/json: + schema: + $ref: '#/components/schemas/PensionFunds' + examples: + ex1: + summary: Abbreviated pension fund list + value: + - - 'id': SG 0227, + - 'name': BVG-Stiftung der Plaston AG, + - 'nameDe': BVG-Stiftung der Plaston AG, + - 'address': c/o Alvisa Services AG, Seestrasse 6, 8027 Zürich, + - 'openpkStatus': active, + - 'openpkServices': + - 'authorizeUrl': https://iam.company.com/pensionfund/auth/authorize, + - 'grantUrl': https://star-fund-dot-acrea-openpk.appspot.com/consent, + - 'identityProvider': https://iam.company.com/pensionfund, + - 'tokenEndpoint': https://iam.company.com/pensionfund/auth/token, + - 'policyEndpoint': https://star-fund-dot-acrea-openpk.appspot.com/v1, + - 'consentEndpoint': https://star-fund-dot-acrea-openpk.appspot.com/v1 + - - 'id': SR-200127, + - 'name': Fonds de prévoyance en faveur du personnel du groupe SICPA en Suisse, + - 'nameFr': Fonds de prévoyance en faveur du personnel du groupe SICPA en Suisse, + - 'address': Avenue Florissant 41 Case postale, 1000 Lausanne 16, + - 'openpkStatus': active, + - 'openpkServices': + - 'authorizeUrl': https://identity.pensionfund.ch/auth/authorize, + - 'grantUrl': https://star-fund-dot-acrea-openpk.appspot.com/consent, + - 'identityProvider': https://identity.pensionfund.ch, + - 'tokenEndpoint': https://identity.pensionfund.ch/auth/token, + - 'policyEndpoint': https://star-fund-dot-acrea-openpk.appspot.com/v1, + - 'consentEndpoint': https://star-fund-dot-acrea-openpk.appspot.com/v1 + +components: + schemas: + PensionFunds: + type: array + description: List of pension funds + items: + $ref: '#/components/schemas/PensionFund' + + PensionFund: + type: object + description: Pension fund incl. technical service data + required: + - name + - id + - openpkStatus + properties: + id: + type: string + description: Pension fund ID + name: + type: string + description: Pension fund name in fund's preferred language + nameDe: + type: string + description: Pension fund name in German + nameEn: + type: string + description: Pension fund name in English + nameFr: + type: string + description: Pension fund name in French + nameIt: + type: string + description: Pension fund name in Itlian + nameRm: + type: string + description: Pension fund name in Rhaeto-Romanic + webUrl: + type: string + format: uri + description: URL of pension funds web site + logoUrl: + type: string + format: uri + description: | + Image URL of pension fund logo + (at least 200 by 200 pixels, suitable for display on white background, + JPEG or PNG format) + openpkStatus: + type: string + description: | + OpenPK API status: + * `active`: The APIs are active. + * `onboarding`: The APIs will soon be active. + * `paused`: The APIs have been paused. + * `notJoined`: The pension fund does not provide APIs. + enum: + - active + - onboarding + - paused + - notJoined + address: + type: string + description: Pension fund address. Text excl. name. + openpkServices: + description: Technical description of API service + $ref: '#/components/schemas/ServicesDescription' + + ServicesDescription: + type: object + description: Technical description of API service + required: + - authorizeUrl + - tokenEndpoint + - grantUrl + properties: + authorizeUrl: + type: string + format: uri + description: URL to initiate the user authentication interaction + grantUrl: + type: string + format: uri + description: URL to initate the user interaction for granting access + identityProvider: + type: string + format: uri + description: | + URL of identity provider and issuer of credentials. + Open ID Connect discovery URLs derived relative to this URL, + e.g. `https://iam.company.com/iam/.well-known/openid-configuration` + for the issuer URL `https://iam.company.com/iam`. + tokenEndpoint: + type: string + format: uri + description: Endpoint URI to request access token + policyEndpoint: + type: string + format: uri + description: Endpoint URI to query insured person and policy data + consentEndpoint: + type: string + format: uri + description: Endpoint URI to query the granted consents diff --git a/purchasesAPI.yaml b/purchasesAPI.yaml index b031324..0879cf1 100644 --- a/purchasesAPI.yaml +++ b/purchasesAPI.yaml @@ -4,7 +4,6 @@ info: version: 0.6.1-beta # yamllint disable rule:indentiation description: | - # Einkaufs-API (deutsch) **** Deutsch (for English see below) **** @@ -38,15 +37,15 @@ info: - In Prüfung: Die Pensionskasse ist dabei, den Antrag zu prüfen. Dies ist der erste Zustand eines neuen Antrags. - Unterlagen erforderlich: Die Prüfung hat ergeben, dass die versicherte Person weitere Unterlagen einreichen oder - direkt mit der Pensionskasse Kontakt aufnehmen muss. + direkt mit der Pensionskasse Kontakt aufnehmen muss. - Abgelehnt: Der Einkaufsantrag wurde abgelehnt. Dies ist ein Endzustand. - Bewilligt: Der Einkaufsantrag wurde bewilligt. Die versicherte Person kann nun die Zahlungen vornehmen - (einmalige oder wiederkehrende). + (einmalige oder wiederkehrende). - Abgeschlossen: Der Einkaufsantrag ist abgeschlossen. Eine oder mehrere Zahlungen sind erfolgt, und es sind keine - weiteren Zahlungen mehr möglich. Dies ist ein Endzustand. + weiteren Zahlungen mehr möglich. Dies ist ein Endzustand. Der Antrag kann über das API abgefragt werden und hat neben dem Antragszustand noch viele weitere Attribute, z.B. die bewilligte Einkaufssumme, die Summe der erfolgten Zahlungen etc. @@ -107,10 +106,10 @@ info: Die Instruktionen bestehen aus einer Liste von Sätzen. Diese werden von der Applikation als unnummerierte Liste angezeigt, z.B: - *Der Einkaufsbetrag reduziert sich um die Höhe des Guthabens auf den Freizügigkeitskonti / -policen. Bitte senden Sie uns - Kopien von Konto-/Policienauszügen, die den Stand per Ende letzten Jahres zeigen.* + Kopien von Konto-/Policienauszügen, die den Stand per Ende letzten Jahres zeigen.* - *Senden Sie die Dokumente an: Personalfürsorge der Firma Heierli AG, Bahnhofstrasse 13, 9000 St. Gallen.* - *Alternativ können Sie die Dokumente an einkauf@heierli-pk.ch senden. Bitte beachten Sie, dass Emails einen Weg über Server - im Ausland nehmen können und die Vertraulichkeit auf dem Weg nicht gewährt ist.* + im Ausland nehmen können und die Vertraulichkeit auf dem Weg nicht gewährt ist.* Sind weitere Unterlagen nötig, so müssen diese direkt an die Pensionskasse (und nicht über die Applikation) eingereicht werden. Entsprechend gibt es kein API dafür. @@ -132,16 +131,16 @@ info: Wurde der Einkauf über einen bestimmten Betrag bewilligt, so kann der Betrag wie folgt überwiesen werden: - **Einmalige Einzahlung mit Einzahlungsschein (QR-Rechnung)**: Die Pensionskasse stellt die Zahlungsdaten (Adresse, Kontonummer, - Referenznummer etc.) aus, die per API an die Applikation geliefert werden. + Referenznummer etc.) aus, die per API an die Applikation geliefert werden. - **Einmalige Einzahlung über eBill**: Die Pensionskasse sendet eine eBill ans eBill-Konto der versicherten Person. - **Regelmässige Einzahlungen per eBill**: Es wird ein Zahlungsrhythmus vereinbart, gemäss dem die Pensionskasse eBills ans - eBill-Konto der versicherten Person sendet. + eBill-Konto der versicherten Person sendet. - **Unregelmässige Einzahlungen per Einzahlungsschein (QR-Rechnung)**: Die Pensionskasse stellt die Zahlungsdaten (Adresse, - Kontonummer, Referenznummer etc.) aus, die die Applikation nutzt, um Zahlungen auszulösen, z.B. über eine E-Banking-Schnittstelle. - Es wird für alle Zahlungen die gleiche Referenznummer verwendet. + Kontonummer, Referenznummer etc.) aus, die die Applikation nutzt, um Zahlungen auszulösen, z.B. über eine E-Banking-Schnittstelle. + Es wird für alle Zahlungen die gleiche Referenznummer verwendet. Eine Pensionskasse muss nicht alle vier Zahlungsmethoden unterstützen. Die unterstützen Zahlungsmethoden können über das API abgefragt werden. @@ -198,7 +197,7 @@ info: - Approved: The purchase application was approved. The insured person can now make payments (once or repeating). - Completed: The purchase application has been completed. One or more payments have been received, and no further payments - are possible. This is a final state. + are possible. This is a final state. The application can be queried using the API. It will return the application state and many additional attributes, such as the approved purchase amount, the amount of received payments. @@ -258,10 +257,10 @@ info: Structurally, the instructions are a list of sentences. The application will display them as bullet list, e.g.: - *Your purchasing potential will be reduced by your further claims from pillar 2 (vested benefits account or policy). Please - send us a copy of the current account statement for your vested benefit accounts.* + send us a copy of the current account statement for your vested benefit accounts.* - *Please send the documents to: Personalfürsorge der Firma Heierli AG, Bahnhofstrasse 13, 9000 St. Gallen.* - *Alternatively, you can send the documents to einkauf@heierli-pk.ch. Please not that emails can take a route via servers abroad, - and confidentially on this path cannot be guaranteed.* + and confidentially on this path cannot be guaranteed.* If additional documents are required for the purchase, they must be sent directly to the pension fund (and not via the application). Thus, there is no API to upload documents. @@ -283,19 +282,19 @@ info: Once the voluntary purchase has been approved, the amount can paid in one four ways: - **Single payment using a payment slip (QR bill)**: The pension fund provides the payment details (address, - account number, reference number etc.) via API to the application used by the insured person. He/she makes - a payment using the provided data. + account number, reference number etc.) via API to the application used by the insured person. He/she makes + a payment using the provided data. - **Single payment by eBill**: The pension fund sends an eBill to the insured person's eBill account. - The insured person provides the eBill email address via the API to the pension fund. + The insured person provides the eBill email address via the API to the pension fund. - **Periodic payments by eBill**: The insured person chooses a payment periodicity, which is sent - to the pension fund via the API. The pension fund will later send an eBill for each payment to - the insured person's eBill account. + to the pension fund via the API. The pension fund will later send an eBill for each payment to + the insured person's eBill account. - **Irregular payments using a payment slip (QR bill)**: The pension fund provides the payment details (address, - account number, reference number etc.) via API to the application. The application then triggers payments - (e.g. via an E-Banking-API). All payments use the same reference number. + account number, reference number etc.) via API to the application. The application then triggers payments + (e.g. via an E-Banking-API). All payments use the same reference number. A pension fund does not need to support a four payment methods. An application can query the supported methods with an API call.