diff --git a/LICENSE b/LICENSE deleted file mode 100644 index c29ce2f83567a712d0cc285d0ced6668e455926a..0000000000000000000000000000000000000000 --- a/LICENSE +++ /dev/null @@ -1,287 +0,0 @@ - EUROPEAN UNION PUBLIC LICENCE v. 1.2 - EUPL © the European Union 2007, 2016 - -This European Union Public Licence (the ‘EUPL’) applies to the Work (as defined -below) which is provided under the terms of this Licence. Any use of the Work, -other than as authorised under this Licence is prohibited (to the extent such -use is covered by a right of the copyright holder of the Work). - -The Work is provided under the terms of this Licence when the Licensor (as -defined below) has placed the following notice immediately following the -copyright notice for the Work: - - Licensed under the EUPL - -or has expressed by any other means his willingness to license under the EUPL. - -1. Definitions - -In this Licence, the following terms have the following meaning: - -- ‘The Licence’: this Licence. - -- ‘The Original Work’: the work or software distributed or communicated by the - Licensor under this Licence, available as Source Code and also as Executable - Code as the case may be. - -- ‘Derivative Works’: the works or software that could be created by the - Licensee, based upon the Original Work or modifications thereof. This Licence - does not define the extent of modification or dependence on the Original Work - required in order to classify a work as a Derivative Work; this extent is - determined by copyright law applicable in the country mentioned in Article 15. - -- ‘The Work’: the Original Work or its Derivative Works. - -- ‘The Source Code’: the human-readable form of the Work which is the most - convenient for people to study and modify. - -- ‘The Executable Code’: any code which has generally been compiled and which is - meant to be interpreted by a computer as a program. - -- ‘The Licensor’: the natural or legal person that distributes or communicates - the Work under the Licence. - -- ‘Contributor(s)’: any natural or legal person who modifies the Work under the - Licence, or otherwise contributes to the creation of a Derivative Work. - -- ‘The Licensee’ or ‘You’: any natural or legal person who makes any usage of - the Work under the terms of the Licence. - -- ‘Distribution’ or ‘Communication’: any act of selling, giving, lending, - renting, distributing, communicating, transmitting, or otherwise making - available, online or offline, copies of the Work or providing access to its - essential functionalities at the disposal of any other natural or legal - person. - -2. Scope of the rights granted by the Licence - -The Licensor hereby grants You a worldwide, royalty-free, non-exclusive, -sublicensable licence to do the following, for the duration of copyright vested -in the Original Work: - -- use the Work in any circumstance and for all usage, -- reproduce the Work, -- modify the Work, and make Derivative Works based upon the Work, -- communicate to the public, including the right to make available or display - the Work or copies thereof to the public and perform publicly, as the case may - be, the Work, -- distribute the Work or copies thereof, -- lend and rent the Work or copies thereof, -- sublicense rights in the Work or copies thereof. - -Those rights can be exercised on any media, supports and formats, whether now -known or later invented, as far as the applicable law permits so. - -In the countries where moral rights apply, the Licensor waives his right to -exercise his moral right to the extent allowed by law in order to make effective -the licence of the economic rights here above listed. - -The Licensor grants to the Licensee royalty-free, non-exclusive usage rights to -any patents held by the Licensor, to the extent necessary to make use of the -rights granted on the Work under this Licence. - -3. Communication of the Source Code - -The Licensor may provide the Work either in its Source Code form, or as -Executable Code. If the Work is provided as Executable Code, the Licensor -provides in addition a machine-readable copy of the Source Code of the Work -along with each copy of the Work that the Licensor distributes or indicates, in -a notice following the copyright notice attached to the Work, a repository where -the Source Code is easily and freely accessible for as long as the Licensor -continues to distribute or communicate the Work. - -4. Limitations on copyright - -Nothing in this Licence is intended to deprive the Licensee of the benefits from -any exception or limitation to the exclusive rights of the rights owners in the -Work, of the exhaustion of those rights or of other applicable limitations -thereto. - -5. Obligations of the Licensee - -The grant of the rights mentioned above is subject to some restrictions and -obligations imposed on the Licensee. Those obligations are the following: - -Attribution right: The Licensee shall keep intact all copyright, patent or -trademarks notices and all notices that refer to the Licence and to the -disclaimer of warranties. The Licensee must include a copy of such notices and a -copy of the Licence with every copy of the Work he/she distributes or -communicates. The Licensee must cause any Derivative Work to carry prominent -notices stating that the Work has been modified and the date of modification. - -Copyleft clause: If the Licensee distributes or communicates copies of the -Original Works or Derivative Works, this Distribution or Communication will be -done under the terms of this Licence or of a later version of this Licence -unless the Original Work is expressly distributed only under this version of the -Licence — for example by communicating ‘EUPL v. 1.2 only’. The Licensee -(becoming Licensor) cannot offer or impose any additional terms or conditions on -the Work or Derivative Work that alter or restrict the terms of the Licence. - -Compatibility clause: If the Licensee Distributes or Communicates Derivative -Works or copies thereof based upon both the Work and another work licensed under -a Compatible Licence, this Distribution or Communication can be done under the -terms of this Compatible Licence. For the sake of this clause, ‘Compatible -Licence’ refers to the licences listed in the appendix attached to this Licence. -Should the Licensee's obligations under the Compatible Licence conflict with -his/her obligations under this Licence, the obligations of the Compatible -Licence shall prevail. - -Provision of Source Code: When distributing or communicating copies of the Work, -the Licensee will provide a machine-readable copy of the Source Code or indicate -a repository where this Source will be easily and freely available for as long -as the Licensee continues to distribute or communicate the Work. - -Legal Protection: This Licence does not grant permission to use the trade names, -trademarks, service marks, or names of the Licensor, except as required for -reasonable and customary use in describing the origin of the Work and -reproducing the content of the copyright notice. - -6. Chain of Authorship - -The original Licensor warrants that the copyright in the Original Work granted -hereunder is owned by him/her or licensed to him/her and that he/she has the -power and authority to grant the Licence. - -Each Contributor warrants that the copyright in the modifications he/she brings -to the Work are owned by him/her or licensed to him/her and that he/she has the -power and authority to grant the Licence. - -Each time You accept the Licence, the original Licensor and subsequent -Contributors grant You a licence to their contributions to the Work, under the -terms of this Licence. - -7. Disclaimer of Warranty - -The Work is a work in progress, which is continuously improved by numerous -Contributors. It is not a finished work and may therefore contain defects or -‘bugs’ inherent to this type of development. - -For the above reason, the Work is provided under the Licence on an ‘as is’ basis -and without warranties of any kind concerning the Work, including without -limitation merchantability, fitness for a particular purpose, absence of defects -or errors, accuracy, non-infringement of intellectual property rights other than -copyright as stated in Article 6 of this Licence. - -This disclaimer of warranty is an essential part of the Licence and a condition -for the grant of any rights to the Work. - -8. Disclaimer of Liability - -Except in the cases of wilful misconduct or damages directly caused to natural -persons, the Licensor will in no event be liable for any direct or indirect, -material or moral, damages of any kind, arising out of the Licence or of the use -of the Work, including without limitation, damages for loss of goodwill, work -stoppage, computer failure or malfunction, loss of data or any commercial -damage, even if the Licensor has been advised of the possibility of such damage. -However, the Licensor will be liable under statutory product liability laws as -far such laws apply to the Work. - -9. Additional agreements - -While distributing the Work, You may choose to conclude an additional agreement, -defining obligations or services consistent with this Licence. However, if -accepting obligations, You may act only on your own behalf and on your sole -responsibility, not on behalf of the original Licensor or any other Contributor, -and only if You agree to indemnify, defend, and hold each Contributor harmless -for any liability incurred by, or claims asserted against such Contributor by -the fact You have accepted any warranty or additional liability. - -10. Acceptance of the Licence - -The provisions of this Licence can be accepted by clicking on an icon ‘I agree’ -placed under the bottom of a window displaying the text of this Licence or by -affirming consent in any other similar way, in accordance with the rules of -applicable law. Clicking on that icon indicates your clear and irrevocable -acceptance of this Licence and all of its terms and conditions. - -Similarly, you irrevocably accept this Licence and all of its terms and -conditions by exercising any rights granted to You by Article 2 of this Licence, -such as the use of the Work, the creation by You of a Derivative Work or the -Distribution or Communication by You of the Work or copies thereof. - -11. Information to the public - -In case of any Distribution or Communication of the Work by means of electronic -communication by You (for example, by offering to download the Work from a -remote location) the distribution channel or media (for example, a website) must -at least provide to the public the information requested by the applicable law -regarding the Licensor, the Licence and the way it may be accessible, concluded, -stored and reproduced by the Licensee. - -12. Termination of the Licence - -The Licence and the rights granted hereunder will terminate automatically upon -any breach by the Licensee of the terms of the Licence. - -Such a termination will not terminate the licences of any person who has -received the Work from the Licensee under the Licence, provided such persons -remain in full compliance with the Licence. - -13. Miscellaneous - -Without prejudice of Article 9 above, the Licence represents the complete -agreement between the Parties as to the Work. - -If any provision of the Licence is invalid or unenforceable under applicable -law, this will not affect the validity or enforceability of the Licence as a -whole. Such provision will be construed or reformed so as necessary to make it -valid and enforceable. - -The European Commission may publish other linguistic versions or new versions of -this Licence or updated versions of the Appendix, so far this is required and -reasonable, without reducing the scope of the rights granted by the Licence. New -versions of the Licence will be published with a unique version number. - -All linguistic versions of this Licence, approved by the European Commission, -have identical value. Parties can take advantage of the linguistic version of -their choice. - -14. Jurisdiction - -Without prejudice to specific agreement between parties, - -- any litigation resulting from the interpretation of this License, arising - between the European Union institutions, bodies, offices or agencies, as a - Licensor, and any Licensee, will be subject to the jurisdiction of the Court - of Justice of the European Union, as laid down in article 272 of the Treaty on - the Functioning of the European Union, - -- any litigation arising between other parties and resulting from the - interpretation of this License, will be subject to the exclusive jurisdiction - of the competent court where the Licensor resides or conducts its primary - business. - -15. Applicable Law - -Without prejudice to specific agreement between parties, - -- this Licence shall be governed by the law of the European Union Member State - where the Licensor has his seat, resides or has his registered office, - -- this licence shall be governed by Belgian law if the Licensor has no seat, - residence or registered office inside a European Union Member State. - -Appendix - -‘Compatible Licences’ according to Article 5 EUPL are: - -- GNU General Public License (GPL) v. 2, v. 3 -- GNU Affero General Public License (AGPL) v. 3 -- Open Software License (OSL) v. 2.1, v. 3.0 -- Eclipse Public License (EPL) v. 1.0 -- CeCILL v. 2.0, v. 2.1 -- Mozilla Public Licence (MPL) v. 2 -- GNU Lesser General Public Licence (LGPL) v. 2.1, v. 3 -- Creative Commons Attribution-ShareAlike v. 3.0 Unported (CC BY-SA 3.0) for - works other than software -- European Union Public Licence (EUPL) v. 1.1, v. 1.2 -- Québec Free and Open-Source Licence — Reciprocity (LiLiQ-R) or Strong - Reciprocity (LiLiQ-R+). - -The European Commission may update this Appendix to later versions of the above -licences without producing a new version of the EUPL, as long as they provide -the rights granted in Article 2 of this Licence and protect the covered Source -Code from exclusive appropriation. - -All other changes or additions to this Appendix require the production of a new -EUPL version. \ No newline at end of file diff --git a/ReadMe.md b/README.md similarity index 100% rename from ReadMe.md rename to README.md diff --git a/docs/details/callbacks.mdx b/docs/details/callbacks.mdx index e9bac650c9c247e79b199450e7a7fcf382997cf7..4f5837c5d43957c3d75354321ef7fe3c67b9a8e8 100644 --- a/docs/details/callbacks.mdx +++ b/docs/details/callbacks.mdx @@ -26,7 +26,7 @@ Die Callback-URL **DARF NUR** über HTTPS erreichbar sein. Der Zustelldienst wird Callbacks nur über eine via HTTPS verschlüsselte Verbindung auslösen. ## Konfiguration von Callbacks -Eine Konfiguration von Callbacks ist [über das Self-Service-Portal](../getting-started/receiving/destination.mdx) und über die API-Endpunkte <ApiLink to="/destinations/{destinationId}" withMethod="put" /> bzw. <ApiLink to="/destinations/{destinationId}" withMethod="patch" /> möglich. +Eine Konfiguration von Callbacks ist [über das Self-Service-Portal](../getting-started/receiving/destination.mdx) und über die API-Endpunkte <ApiLink to="/v1/destinations/{destinationId}" withMethod="put" /> bzw. <ApiLink to="/destinations/{destinationId}" withMethod="patch" /> möglich. Bei der Konfiguration werden die *Callback-URL* und ein *Callback-Secret* vom API-Client festgelegt. Das *Callback-Secret* dient der Überprüfung der Echtheit (Authentizität) von eingehenden Callbacks (siehe nächster Abschnitt). Das angegebene *Callback-Secret* kann über die API nur geschrieben und aktualisiert, aber nicht gelesen werden und **DARF NICHT** an Dritte weitergegeben werden. @@ -59,7 +59,7 @@ $ curl -X PATCH \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $JWT_TOKEN" \ --data "{ \"callback\": { \"url\": \"$CALLBACK_URL\", \"secret\": \"$CALLBACK_SECRET\" }}" \ - "$SERVICE_URL/destinations/$DESTINATION_ID" + "$SERVICE_URL/v1/destinations/$DESTINATION_ID" ``` </TabItem> diff --git a/docs/details/destination-management.mdx b/docs/details/destination-management.mdx index c283e4240f23e72d614f102287fbbe9608376747..dbf02a7843e39124d03005ad159dad27e06cd941 100644 --- a/docs/details/destination-management.mdx +++ b/docs/details/destination-management.mdx @@ -13,12 +13,12 @@ import ApiLink from '@site/src/components/ApiLink'; Für die Aktualisierung eines Zustellpunktes existieren aktuell folgende Endpunkte: -* Vollständige Aktualisierung eines Zustellpunktes: <ApiLink to="/destinations/{destinationId}" withMethod="put" /> -* Partielle Aktualisierung eines Zustellpunktes: <ApiLink to="/destinations/{destinationId}" withMethod="patch" /> +* Vollständige Aktualisierung eines Zustellpunktes: <ApiLink to="/v1/destinations/{destinationId}" withMethod="put" /> +* Partielle Aktualisierung eines Zustellpunktes: <ApiLink to="/v1/destinations/{destinationId}" withMethod="patch" /> Für die Aktualisierung der Schlüssel des Zustellpunktes gibt es folgenden Endpunkt: -* <ApiLink to="/destinations/{destinationId}/keys" withMethod="post"/> +* <ApiLink to="/v1/destinations/{destinationId}/keys" withMethod="post"/> Die Details sind der API-Spec zu entnehmen. @@ -44,14 +44,14 @@ $ curl -X POST \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $JWT_TOKEN" \ --data '{"kty": "RSA", "kid": "new-encryption-key", "alg": "RSA-OAEP-256", "key_ops": ["wrapKey"], "x5c": ["..."], "e": "AQAB", "n": "..."}' \ - "$SERVICE_URL/destinations/$DESTINATION_ID/keys" + "$SERVICE_URL/v1/destinations/$DESTINATION_ID/keys" # Setzen der Schlüssel-ID als Verschlüsselungsschlüssel $ curl -X PATCH \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $JWT_TOKEN" \ --data '{"encryptionKid": "new-encryption-key"}' \ - "$SERVICE_URL/destinations/$DESTINATION_ID" + "$SERVICE_URL/v1/destinations/$DESTINATION_ID" ``` </TabItem> diff --git a/docs/details/jwk-creation.md b/docs/details/jwk-creation.md index bad3a80b42b70035c589f4b59ec4b20c645febb7..e82ac4024f1d30ef7a809093cf5554b286231fdb 100644 --- a/docs/details/jwk-creation.md +++ b/docs/details/jwk-creation.md @@ -3,24 +3,24 @@ FIT-Connect verwendet zur Übertragung von Antragsdaten und Metadaten mit direkt Im Folgenden soll die Erstellung von JWKs mithilfe eines einfachen in Python geschriebenen Skriptes unter Windows und Linux erläutert werden. ## Voraussetzungen -Die Ausführung des Skriptes setzt eine installierte Version von [Python]( https://www.python.org/) voraus. Zum Nachinstallieren von benötigten Paketen wird Paketverwaltungsprogramm **pip** benötigt. Bei Versionen vor 3.4 ist ggf. noch eine manuelle Installation erforderlich. +Die Ausführung des Skriptes setzt eine installierte Version von [Python](https://www.python.org/) voraus. Zum Nachinstallieren von benötigten Paketen wird Paketverwaltungsprogramm **pip** benötigt. Bei Versionen vor 3.4 ist ggf. noch eine manuelle Installation erforderlich. ### Windows -Eine Anleitung zur Installation und Einrichtung unter Windows finden Sie unter [Installationsanleitung Python Windows]( https://docs.microsoft.com/de-de/windows/python/beginners). +Eine Anleitung zur Installation und Einrichtung unter Windows finden Sie unter [Installationsanleitung Python Windows](https://docs.microsoft.com/de-de/windows/python/beginners). ### Linux -Der Ablauf und die Befehle zur Installation und Einrichtung von Python unter Linux unterscheiden sich je nach verwendeter Distribution. +Der Ablauf und die Befehle zur Installation und Einrichtung von Python unter Linux unterscheiden sich je nach verwendeter Distribution. -#### Für Ubuntu -[Installationsanleitung Python Ubuntu]( https://docs.python-guide.org/starting/install3/linux/) +#### Für Ubuntu +[Installationsanleitung Python Ubuntu](https://docs.python-guide.org/starting/install3/linux/) Installation von **pip** ```console foo@bar:~$ sudo apt install python3-pip ``` -#### Für Debian -[Installationsanleitung Python Debian]( https://linuxize.com/post/how-to-install-python-3-9-on-debian-10/) +#### Für Debian +[Installationsanleitung Python Debian](https://linuxize.com/post/how-to-install-python-3-9-on-debian-10/) Installation von **pip** ```console @@ -28,7 +28,7 @@ foo@bar:~$ sudo apt install python3-pip ``` #### Für Fedora -[Installationsanleitung Python Fedora]( https://developer.fedoraproject.org/tech/languages/python/multiple-pythons.html) +[Installationsanleitung Python Fedora](https://developer.fedoraproject.org/tech/languages/python/multiple-pythons.html) ```console foo@bar:~$ yum -y install python-pip @@ -76,7 +76,7 @@ Wrote JWK representation of signature validation public key (key_use=verify) to Please upload these keys when creating a destination in the self service portal. Wrote JWKS of Public Keys to C:\Users\username\AppData\Local\Temp\tmpx8gi90tq\set-public-keys.json -This key set can be used to update (rotate) keys via the Submission-API (PUT /destinations/\{destinationID\}) +This key set can be used to update (rotate) keys via the Submission-API (PUT /v1/destinations/\{destinationID\}) Wrote JWK representation of decryption private key (key_use=unwrapKey) to C:\Users\username\AppData\Local\Temp\tmpx8gi90tq\privateKey_decryption.json Wrote JWK representation of signing private key (key_use=sign) to C:\Users\username\AppData\Local\Temp\tmpx8gi90tq\privateKey_signing.json diff --git a/docs/details/schema-reference.md b/docs/details/schema-reference.md index d424f37af5abc438aa43584c57ba69639141c13c..54a4c826f02c513525fbffd80697c858f43efb01 100644 --- a/docs/details/schema-reference.md +++ b/docs/details/schema-reference.md @@ -3,7 +3,7 @@ Im Folgenden wird aufgezeigt, wie Fachschemarerenzen für Fachdatensätze auf bestehende Fachstandards und Rahmenwerke abgebildet werden. Aktuell werden folgende Fachstandards und Rahmenwerke beschrieben: - FIM Übertragungsschemata für Anträge auf Basis von FIM Datenfelder -- XÖV Nachrichten auf Basis von XÖV-konformen Fachstandards +- XÖV Nachrichten auf Basis von XÖV-konformen Fachstandards Soll ein anderer Fachstandard mit der FIT-Conect Submission API übermittelt werden, können wir gerne die Beschreibung dieser Schemareferenz hier aufnehmen, um diese Informationen einem breiteren Nutzerkreis zugänglich zu machen. Hierzu bitte einfach Issue [hier](https://git.fitko.de/fit-connect/docs) aufmachen diff --git a/docs/getting-started/event-log.mdx b/docs/getting-started/event-log.mdx index c12348ea2c51674974e73db1620cc9acba0eb97d..82fda349182baa4e8675e0306f4dda46cfeb15f3 100644 --- a/docs/getting-started/event-log.mdx +++ b/docs/getting-started/event-log.mdx @@ -248,7 +248,7 @@ Konkret sind das hier: #### Abruf des JWK zur Gültigkeitsprüfung des SET -Mit der `submissionId` kann über den Endpunkt <ApiLink to="/submissions/{submissionId}" /> die zugehörige `destinationId` ermittelt werden. +Mit der `submissionId` kann über den Endpunkt <ApiLink to="/v1/submissions/{submissionId}" /> die zugehörige `destinationId` ermittelt werden. Hier ist das konkret der Wert `92f2f581-c89d-44a5-b834-1fe3f6fa48d5`. ```http title="Abfrage der destinationId einer Submission" @@ -266,7 +266,7 @@ $ KID=... $ SERVICE_URL=... $ DESTINATION_ID=... $ curl -X GET \ - "$SERVICE_URL/destinations/$DESTINATION_ID/keys/$KID" + "$SERVICE_URL/v1/destinations/$DESTINATION_ID/keys/$KID" --- { "kty": "RSA", diff --git a/docs/getting-started/overview.md b/docs/getting-started/overview.md index 7886a3f042b5664128efb0761ee133edd6cc0313..8b8e1cf9bbbe84cfb70a4c51361b501f02510e07 100644 --- a/docs/getting-started/overview.md +++ b/docs/getting-started/overview.md @@ -4,9 +4,11 @@ Im folgenden "Getting Started"-Guide wird beschrieben, wie die ersten Interaktio In den nächsten Abschnitten wird beschrieben, wie man sich [gegenüber FIT-Connect authentifiziert](./authentication.mdx), Daten für die Übertragung [ver- und entschlüsselt](./encryption.mdx) werden, sowie welche Schritte für das [Einreichen](./sending/overview.mdx) bzw. [Empfangen](./receiving/overview.mdx) von Einreichungen notwendig sind. :::note Zielgruppe -Die folgenden Seiten beinhalten teils sehr technische Detailinformationen zur Umsetzung einer Anbindung an die FIT-Connect-Schnittstellen. Zielgruppe der folgenden Seiten sind vorangig Entwickler:innen. +Die folgenden Seiten beinhalten technische Details zur Umsetzung einer Anbindung an die FIT-Connect-Schnittstellen. +Zielgruppe sind vorrangig Entwickler:innen. ::: Kern von FIT-Connect ist der Zustelldienst, der sendende und empfangende Systeme einer Einreichung verbindet. -Jedes empfangende System (Fachverfahren / virtuelle Poststelle) verfügt über einen oder mehrere Zustellpunkte (Destinations), an die Einreichungen (Anträge oder Berichte) gesendet werden. Zustellpunkte können von empfangenden Systemen konfiguriert und von sendenden Systemen adressiert werden. +Jedes empfangende System (Fachverfahren / virtuelle Poststelle) verfügt über einen oder mehrere Zustellpunkte (Destinations), an die Einreichungen (Anträge oder Berichte) gesendet werden. +Zustellpunkte können von empfangenden Systemen konfiguriert und von sendenden Systemen adressiert werden. diff --git a/docs/getting-started/receiving/download-submission.mdx b/docs/getting-started/receiving/download-submission.mdx index c327409140c60d79ad288c97abeac70b927951be..45b9804356a50dac8e9579d615c6ef76fa2004d7 100644 --- a/docs/getting-started/receiving/download-submission.mdx +++ b/docs/getting-started/receiving/download-submission.mdx @@ -6,7 +6,7 @@ title: Einreichung herunterladen import ApiLink from '@site/src/components/ApiLink' ## Abruf von Metadaten und Fachdaten -Der Abruf einer Einreichung ist über den Endpunkt <ApiLink to="/submissions/{submissionId}" /> möglich. Liegen zur Einreichung neben den verschlüsselten Metadaten (`encryptedMetadata`) und Fachdaten (`encryptedData`) zusätzlich weitere Anlagen vor, so sind die IDs der Anlagen im Feld `attachments` zu finden. Anlagen müssen separat heruntergeladen werden (siehe nächster Abschnitt). +Der Abruf einer Einreichung ist über den Endpunkt <ApiLink to="/v1/submissions/{submissionId}" /> möglich. Liegen zur Einreichung neben den verschlüsselten Metadaten (`encryptedMetadata`) und Fachdaten (`encryptedData`) zusätzlich weitere Anlagen vor, so sind die IDs der Anlagen im Feld `attachments` zu finden. Anlagen müssen separat heruntergeladen werden (siehe nächster Abschnitt). Anschließend können die Metadaten und Fachdaten [entschlüsselt](./decrypt.mdx) sowie deren Schemata [validiert](./validate.mdx) werden. @@ -36,7 +36,7 @@ $ curl \ ``` ## Abruf von Anlagen -Anlagen können über den Endpunkt <ApiLink to="/submissions/{submissionId}/attachments/{attachmentId}" /> abgerufen werden. Anschließend können auch die Anlagen [entschlüsselt werden](./decrypt.mdx). +Anlagen können über den Endpunkt <ApiLink to="/v1/submissions/{submissionId}/attachments/{attachmentId}" /> abgerufen werden. Anschließend können auch die Anlagen [entschlüsselt werden](./decrypt.mdx). ```bash title="Herunterladen einer Anlage" diff --git a/docs/getting-started/receiving/process-and-acknowledge.mdx b/docs/getting-started/receiving/process-and-acknowledge.mdx index 291fac49e2f480314549f7fa99106480ff51afc9..13737db84644642dcea6e9101acf19c76103d244 100644 --- a/docs/getting-started/receiving/process-and-acknowledge.mdx +++ b/docs/getting-started/receiving/process-and-acknowledge.mdx @@ -78,13 +78,13 @@ Weiterhin ist es notwendig, dass die Id der Einreichung und des zugehörigen Vor </TabItem> </Tabs> -Dies kann dann über ein <ApiLink to="/submissions/{submissionId}/events" withMethod="post" /> erreicht werden. +Dies kann dann über ein <ApiLink to="/v1/submissions/{submissionId}/events" withMethod="post" /> erreicht werden. Hier wird das Event über den Request-Body übertragen und vom Zustelldienst syntaktisch und auf eine korrekte Signatur geprüft. Sind alle Prüfungen erfolgreich durchlaufen, wird das SET im Event Log abgespeichert und der Zustand der Einreichung abhängig vom Event geändert. ## Event Log abfragen -Der Event Log einer Einreichung kann über <ApiLink to="/submissions/{submissionId}/events" /> abgefragt werden. +Der Event Log einer Einreichung kann über <ApiLink to="/v1/submissions/{submissionId}/events" /> abgefragt werden. Hierbei wird der Event Log der Einreichung zurückgeliefert, der die verschiedenen Statusübergänge bzw. abgelegten Ereignisse beinhaltet. Das Ergebnis könnte wie folgt aussehen: diff --git a/docs/getting-started/receiving/query.mdx b/docs/getting-started/receiving/query.mdx index b56c19fb4c46f045c0303a12fa3845613d098092..9dfb6dc18e91bcae31de9b6437d60be9848c270b 100644 --- a/docs/getting-started/receiving/query.mdx +++ b/docs/getting-started/receiving/query.mdx @@ -6,12 +6,12 @@ title: Vorhandensein neuer Einreichungen prüfen import ApiLink from '@site/src/components/ApiLink' Empfangende Systeme können sich über den Eingang neuer Einreichungen entweder durch periodische Anfragen informieren (Polling) oder vom Zustelldienst über Callbacks aktiv benachrichtigen lassen. -Letzteres stellt die empfohle Umsetzungsvariante dar, da hierdurch unnötige Anfragen vermieden werden können, was zu einer insgesamt besseren Performance und zu einer schnelleren Benachrichtung empfangnder Systeme führt. +Letzteres stellt die empfohlene Umsetzungsvariante dar, da hierdurch unnötige Anfragen vermieden werden können, was zu einer insgesamt besseren Performance und zu einer schnelleren Benachrichtigung empfangender Systeme führt. ## Callback -Wenn eine Callback-URL im Zustellpunkt hinterlegt ist, kann der Zustelldienst den Zustellpunkt aktiv via Callback über neue Einriechungen informieren. -Das Format, in welchem der Callback übertragen wird, ist im Endpunkt <ApiLink to="/destinations/{destinationId}" withMethod="put" /> definiert. -Die Konfiguration und Prüfung von Callbacks ist im Aritkel [Verwendung von Callbacks](../../details/callbacks.mdx) beschrieben. +Wenn eine Callback-URL im Zustellpunkt hinterlegt ist, kann der Zustelldienst den Zustellpunkt aktiv via Callback über neue Einreichungen informieren. +Das Format, in welchem der Callback übertragen wird, ist im Endpunkt <ApiLink to="/v1/destinations/{destinationId}" withMethod="put" /> definiert. +Die Konfiguration und Prüfung von Callbacks ist im Artikel [Verwendung von Callbacks](../../details/callbacks.mdx) beschrieben. Callbacks zur Benachrichtigung über neue Einriechungen haben das folgende Format: @@ -26,7 +26,7 @@ callback-timestamp: 1672527599 Wenn das empfangende System über den Eingang neuer Einreichungen benachrichtigt wurde, dann kann es diese wie im Artikel [Einreichung herunterladen](./download-submission.mdx) beschrieben herunterladen. ## Polling -Über Polling, d.h. regelmäßiges Abfragen des Endpuntes <ApiLink to="/submissions" /> , können alle Einreichungen abgefragt werden, die zum Abholen bereitstehen. +Über Polling, d.h. regelmäßiges Abfragen des Endpunktes <ApiLink to="/v1/submissions" />, können alle Einreichungen abgefragt werden, die zum Abholen bereitstehen. Dies wird aus Performancegründen jedoch nicht empfohlen. Die abgerufene Liste der Submissions kann über den Parameter `destinationId` auf einzelne Zustellpunkte eingeschränkt werden. diff --git a/docs/getting-started/receiving/validate.mdx b/docs/getting-started/receiving/validate.mdx index 4a571318878a7544024841a7f4fe324a41489414..198b63284d834b10c8d182ddad6953a57f3cd1b2 100644 --- a/docs/getting-started/receiving/validate.mdx +++ b/docs/getting-started/receiving/validate.mdx @@ -20,8 +20,7 @@ Danach erfolgt eine Prüfung des Fachdatensatzes: - Entspricht der Fachdatensatz dem vereinbarten Medientyp (JSON oder XML)? - Entspricht der Fachdatensatz dem vereinbarten Schema? -Hierbei kann die im Metadatensatz enthaltene Schemareferenz genutzt werden, um das zu validierende Schema zu identifizieren, wenn im Zustellpunkt mehrere -Schemata für Fachdatensätze unterschützt werden. +Hierbei kann die im Metadatensatz enthaltene Schemareferenz genutzt werden, um das zu validierende Schema zu identifizieren, wenn im Zustellpunkt mehrere Schemata für Fachdatensätze unterstützt werden. Das Validierungsvorgehen wird im folgenden Anhand von Bespielen für FIM- und XÖV-Fachdatensätzen gezeigt. diff --git a/docs/getting-started/sending/encrypt.mdx b/docs/getting-started/sending/encrypt.mdx index 6abfdc1882d2e95e0bc500bf413bd3193418dde8..30b459a3a9408c290e0233c3798f4e514bbb0894 100644 --- a/docs/getting-started/sending/encrypt.mdx +++ b/docs/getting-started/sending/encrypt.mdx @@ -25,7 +25,7 @@ $ KID=... # Wert des Feldes `encryptionKid` $ SERVICE_URL=... $ DESTINATION_ID=... $ curl -X GET \ - "$SERVICE_URL/destinations/$DESTINATION_ID/keys/$KID" + "$SERVICE_URL/v1/destinations/$DESTINATION_ID/keys/$KID" --- { "kty": "RSA", diff --git a/docs/getting-started/sending/get-destination.mdx b/docs/getting-started/sending/get-destination.mdx index 09b063bae7db3fa408c000b0d6b29cdc56834f30..0f8a44a3e20e54743cdeb6cb67e20840814ef489 100644 --- a/docs/getting-started/sending/get-destination.mdx +++ b/docs/getting-started/sending/get-destination.mdx @@ -5,11 +5,10 @@ title: Zustellpunkt ermitteln import Tabs from '@theme/Tabs' import TabItem from '@theme/TabItem' -import ApiLink from '@site/src/components/ApiLink' ## Zustellpunkt und `destinationId` ermitteln -Um eine Einreichung an die fachlich korrekte Stelle sicherzustellen und die technischen Parameter des richtigen Zustellpunkt zu ermitteln, muss die `destinationId` der zuständigen Stelle ermittelt werden. Zukünftig wird die Ermittlung der `destinationId` und die Ermittlung der technischen Parameter über die FIT-Connect Routing API möglich sein. Sobald die Routing API umgesetzt ist (voraussichtlich Ende Q3 2021), wird diese Möglichkeit hier beschrieben. +Um eine Einreichung an die fachlich korrekte Stelle sicherzustellen und die technischen Parameter des richtigen Zustellpunkts zu ermitteln, muss die `destinationId` der zuständigen Stelle ermittelt werden. Zukünftig wird die Ermittlung der `destinationId` und die Ermittlung der technischen Parameter über die FIT-Connect Routing API möglich sein. Sobald die Routing API umgesetzt ist (voraussichtlich Ende Q3 2021), wird diese Möglichkeit hier beschrieben. ## Informationen des Zustellpunktes erhalten @@ -17,9 +16,9 @@ Um an einen Zustellpunkt eine Einreichung korrekt zu übermitteln, ist es notwen Diese Informationen sind: - Die Verwaltungsleistungen (`services`), die über diesen Zustellpunkt abgebildet werden, bestehend aus: - einem Identifikator der Verwaltungsleitung (`identifier`): Typischerweise entspricht dieser einem LeiKa-Schlüssel (siehe [Leistungskatalog im FIM-Portal](https://fimportal.de/kataloge#download-leistungen)). - - einer Liste an zulässigen Fachdatenschemata (`submissionSchemas`): Hiermit legt das empfangende System fest, welchem Schema die übergebenen Fachdatensätze entsprechen müssen. Welches der angebenen Schemata verwendet werden muss, bestimmt das sendende System aus dem eigenen fachlichen Kontext heraus. Wenn bspw. ein Antrag für einen Schwerbehindertenausweis gestellt wird, muss der Fachdatensatz aus den dort hinterlegten Schemata gemäß dem dortigen Schema für den Schwerbehindertausweis (bspw. ein FIM/XFall Schema) entsprechen. + - einer Liste an zulässigen Fachdatenschemata (`submissionSchemas`): Hiermit legt das empfangende System fest, welchem Schema die übergebenen Fachdatensätze entsprechen müssen. Welches der angegebenen Schemata verwendet werden muss, bestimmt das sendende System aus dem eigenen fachlichen Kontext heraus. Wenn bspw. ein Antrag für einen Schwerbehindertenausweis gestellt wird, muss der Fachdatensatz aus den dort hinterlegten Schemata gemäß dem dortigen Schema für den Schwerbehindertenausweis (bspw. ein FIM/XFall Schema) entsprechen. - einer Liste an Regionen (`regions`), für die die Verwaltungsleistung angeboten wird. -- Schlüssel-ID des öffentlichen Verschlüsselungsschlüssels (`encryptionKid`): Empfangende Systeme veröffentlichen die Schlüssel-ID ihres Verschlüsselungsschlüssels für die Verschlüsselung von Einreichungen. Der dazugehörige JSON Web Key (JWK) kann anschließend über den Endpunkt <ApiLink to="/destinations/{destinationId}/keys/{keyId}" /> abgefragt werden. +- Schlüssel-ID des öffentlichen Verschlüsselungsschlüssels (`encryptionKid`): Empfangende Systeme veröffentlichen die Schlüssel-ID ihres Verschlüsselungsschlüssels für die Verschlüsselung von Einreichungen. Der dazugehörige JSON Web Key (JWK) kann anschließend über den Endpunkt <ApiLink to="/v1/destinations/{destinationId}/keys/{keyId}" /> abgefragt werden. :::caution Hinweis Der Mechanismus zum Abruf der Verschlüsselungsschlüssel wird sich bis zur Veröffentlichung der finalen API-Spezifikation noch einmal ändern. @@ -44,7 +43,7 @@ $ export DESTINATION_ID=7a2668ad-3081-407c-9358-7ce4b6144b02 $ curl \ -H "Authorization: Bearer $JWT_TOKEN" \ -H "Content-Type: application/json" \ - -X GET $SERVICE_URL/destinations/$DESTINATION_ID + -X GET $SERVICE_URL/v1/destinations/$DESTINATION_ID > { "destinationId": "7881dba9-4055-4854-8b6d-11ea5b7f3047", diff --git a/docs/getting-started/sending/query-status.mdx b/docs/getting-started/sending/query-status.mdx index a4fc50e72444567d84f332ad7d31b1afc6fa6bf0..2a1883d0467d2edd6a30c2afb791af85debaf691 100644 --- a/docs/getting-started/sending/query-status.mdx +++ b/docs/getting-started/sending/query-status.mdx @@ -24,7 +24,9 @@ Das Statusmodell einer Einreichung ist in der folgenden Grafik dargestellt und e | `rejected` | Die Einreichung wurde durch den Empfänger zurückgewiesen. | | `accepted` | Die Einreichung wurde durch den Empfänger akzeptiert. | -Der Status wird über <ApiLink to="/submissions/{submissionId}/events" /> abgefragt. +Der Status wird über +<ApiLink to="/v1/submissions/{submissionId}/events"/> +abgefragt. Hierbei wird der Event Log der Einreichung zurückgeliefert, der die verschiedenen Statusübergänge bzw. abgelegten Ereignisse beinhaltet. Das Ergebnis könnte wie folgt aussehen: @@ -68,4 +70,4 @@ Die Überprüfung ist im Artikel zum [Event Log](../event-log.mdx#set-validation :::caution Hinweis Der Mechanismus zum Abrufen von kryptografischen Schlüsseln des empfangenden Systems zur Signaturprüfung wird sich bis zur Veröffentlichung der finalen API-Spezifikation noch einmal ändern. -::: \ No newline at end of file +::: diff --git a/docs/getting-started/sending/start-submission.mdx b/docs/getting-started/sending/start-submission.mdx index d6b8689b2f2794c5b50a3e3045bc485fdf95b21a..1ea1ae4e2d35b4f420e70ed268812391381672e5 100644 --- a/docs/getting-started/sending/start-submission.mdx +++ b/docs/getting-started/sending/start-submission.mdx @@ -12,7 +12,7 @@ Die Inhalte umfassen hierbei die Identifikatoren der Anlagen als UUIDs und die I Die UUIDs der Anlagen müssen eindeutig sein und werden vom sendenden System festgelegt. :::note Hinweis -Die Struktur von Einreichungen und die Referenzierung von Fachdatenschemata ist im Artikel [Aufbau einer Einreichung](../submission-structure.md) näher beschrieben. +Die Struktur von Einreichungen und die Referenzierung von Fachdatenschemata ist im Artikel [Aufbau einer Einreichung](../submission-structure.mdx) näher beschrieben. ::: <Tabs diff --git a/docs/getting-started/submission-structure.md b/docs/getting-started/submission-structure.mdx similarity index 72% rename from docs/getting-started/submission-structure.md rename to docs/getting-started/submission-structure.mdx index 9d423c3cc27eaba2bc4ace848ac96523273e76a1..1180e71f7546d5a35dee16c7a21b0a9d779669dc 100644 --- a/docs/getting-started/submission-structure.md +++ b/docs/getting-started/submission-structure.mdx @@ -1,31 +1,36 @@ +import ApiLink from '@site/src/components/ApiLink' + # Aufbau einer Einreichung Der zentrale Anwendungsfall der Submission API besteht darin, Daten im Rahmen von Verwaltungsverfahren an hoheitliche Stellen (Behörden, Handelskammern, etc.) zu übermitteln. Diese Daten werden durch Kunden und Verfahrenspartner übermittelt, um Verfahren (bspw. über einen Antrag) zu starten oder um Berichtspflichten zu erfüllen. -Diese Datenübermittlung wird in der Submission API als Einreichung (`submission`) bezeichnet und besitzt eine festgelegte Struktur aus Datenobjekten, die über die Ressourcen -der Submission API abgebildet werden. Mit dieser Struktur soll eine standardisierte Verarbeitung und Interpretation der einzelnen Bestandteile einer Einreichung ermöglicht werden. +Diese Datenübermittlung wird in der Submission API als Einreichung (`submission`) bezeichnet und besitzt eine festgelegte Struktur aus Datenobjekten, die über die Ressourcen der Submission API abgebildet werden. +Mit dieser Struktur soll eine standardisierte Verarbeitung und Interpretation der einzelnen Bestandteile einer Einreichung ermöglicht werden. -Einreichung können aus fachlicher Sicht Anträge (bspw. ein strukturierter Datensatz mit den Daten eines Wohngeldantrags und Anlagen in beliebigen Datenformaten wie einer Urkunde als PDF), Berichte (bspw. ein Datensatz wie eine elektronische Bilanz in einem festlegten Berichtsformat für Statistik- oder Sozialmeldenungen) oder sonstige prozessauslösende Datensätze sein, die an Systeme von hoheitlichen Stellen übermittelt werden. +Einreichung können aus fachlicher Sicht Anträge (bspw. ein strukturierter Datensatz mit den Daten eines Wohngeldantrags und Anlagen in beliebigen Datenformaten wie einer Urkunde als PDF), Berichte (bspw. ein Datensatz wie eine elektronische Bilanz in einem festlegten Berichtsformat für Statistik- oder Sozialmeldungen) oder sonstige prozessauslösende Datensätze sein, die an Systeme von hoheitlichen Stellen übermittelt werden. ## Wie ist eine Einreichung aufgebaut?  Eine Einreichung, die über die Submission API übermittelt wird, besteht aus drei Bestandteilen: + - Ein optionaler Fachdatensatz (`data`), der die Daten eines Antrags oder Berichts enthält und einem im Zustellpunkt vorgegebenen Datenschema (`submissionSchema`) entspricht. -- Eine oder mehrere optionale Anlagen (`attachments`) ergänzend zum Fachdatensatz. Die können Nachweise in Form von PDF-Urkunden, Bauanlagen wie XPlanGML-basierte Baupläne oder auch technische Laufzettel vom sendenden System sein. +- Eine oder mehrere optionale Anlagen (`attachments`) ergänzend zum Fachdatensatz. +Die können Nachweise in Form von PDF-Urkunden, Bauanlagen wie XPlanGML-basierte Baupläne oder auch technische Laufzettel vom sendenden System sein. - Ein obligatorischer Metadatensatz `metadata`), der die Einreichung beschreibt und zusammen mit der Submission API im Rahmen von FIT-Connect standardisiert wird. -Dieser enthält Strukturinformationen zum Fachdatensatz und Anlagen sowie prozessrelevante Informationen wie die Authentizierung des Absenders, Zahlungsinformationen (z.B. von Verfahrensgebühren) oder Rückkanalwünschen. +Dieser enthält Strukturinformationen zum Fachdatensatz und Anlagen sowie prozessrelevante Informationen wie die Authentisierung des Absenders, Zahlungsinformationen (z.B. von Verfahrensgebühren) oder Rückkanalwünschen. ## Wie stimmen sich sendende und empfangende Systeme beim Inhalt einer Einreichung ab? -In der Submission API wird durch das empfangende System über eine Schemaferenz im Zustellpunkt ein konkretes Schema für den Fachdatensatz festgelegt, den das sendende System übersenden darf. Eine Fachschemareferenz besteht aus zwei Angaben: +In der Submission API wird durch das empfangende System über eine Schemareferenz im Zustellpunkt ein konkretes Schema für den Fachdatensatz festgelegt, den das sendende System übersenden darf. Eine Fachschemareferenz besteht aus zwei Angaben: + - Die `schemaURI` referenziert das zu verwendende Fachschema. - Der `mimeType` gibt den Datentyp (JSON oder XML) des Fachdatensatzes vor. In den Angaben eines Zustellpunkts befindet sich die Fachschemareferenz immer innerhalb eines Service-Objekts innerhalb des `services` Arrays. -Die Fachschemarefenz ist im Zustellpunkt daher immer einer dazugehörigen Leistung zugeordnet. +Die Fachschemareferenz ist im Zustellpunkt daher immer einer dazugehörigen Leistung zugeordnet. ```json "services":[ @@ -60,7 +65,9 @@ Die Fachschemarefenz ist im Zustellpunkt daher immer einer dazugehörigen Leistu ``` -Wenn ein sendendes System die Angaben eines Zustellpunkts ermittelt (bspw. über [GET /destinations/{destinationId}](../apis/submission-api.mdx#get-/destinations/-destinationId-) oder zukünftig die Routing API), so muss der Fachdatensatz diesem Schema entsprechen. +Wenn ein sendendes System die Angaben eines Zustellpunkts ermittelt (bspw. über +<ApiLink to="/v1/destinations/{destinationId}" /> +oder zukünftig die Routing API), so muss der Fachdatensatz diesem Schema entsprechen. Wenn mehrere Schemata (bspw. innerhalb des `submissionSchemas` Array) im Zustellpunkt referenziert werden, so muss der Fachdatensatz einem dieser referenzierten Schemata entsprechen. ## Warum muss das sendende System über den Metadatensatz eine Fachschemareferenz mitliefern? @@ -78,16 +85,18 @@ Zusätzlich muss das sendende System eine identische Fachschemareferenz in den M } ``` -Insbesondere wenn ein empfangendes System viele unterschiedliche Schemata über den Zustellpunkt unterstützt, hilft diese Angabe bei der effizienten Validierung des Fachdatensatzes. Dies ist insbesondere dann relevant, wenn keine eindeutige Schemareferenz im Fachdatensatz enthalten ist. +Insbesondere wenn ein empfangendes System viele unterschiedliche Schemata über den Zustellpunkt unterstützt, hilft diese Angabe bei der effizienten Validierung des Fachdatensatzes. +Dies ist insbesondere dann relevant, wenn keine eindeutige Schemareferenz im Fachdatensatz enthalten ist. ## Sind Vorgaben für die Anzahl der Anlagen und deren Format möglich? -Aktuell sind keine konkreten Vorgaben für die Anzahl und das Format der Anlagen durch ein empfangendes Sytem über die Angaben im Zustellpunkt möglich. +Aktuell sind keine konkreten Vorgaben für die Anzahl und das Format der Anlagen durch ein empfangendes System über die Angaben im Zustellpunkt möglich. Aktuell existieren lediglich Vorgaben für die Gesamtgröße einer Einreichung (Fachdatensatz+Anlagen), die den Umfang der Anlagen hinsichtlich der Datengrößen begrenzen. -Für sonstige technische Vorgaben für Anlagen wird aktuell davon ausgegangen, dass die Fachstandards, zu denen ein genutzter Fachdatensatz gehört, technische Vorgaben für Anlagen machen. Ansonsten sollte ein empfangendes System im Mimimum PDF als Format für Anlagen akzeptieren. +Für sonstige technische Vorgaben für Anlagen wird aktuell davon ausgegangen, dass die Fachstandards, zu denen ein genutzter Fachdatensatz gehört, technische Vorgaben für Anlagen machen. +Ein empfangendes System sollte mindestens Anlagen im PDF-Format akzeptieren. Es wird für sendende Systeme empfohlen, auf den Versand eigener proprietärer Anlagen zu verzichten, wenn deren Nutzung nicht explizit mit den empfangenden Stellen abgestimmt wurde. ## Meine Software übermittelt oder empfängt nach Standard XYZ Fachdatensätze, wie kann ich das jeweils genutzte Fachschema korrekt referenzieren? -Eine Erläuerung der Schemareferenzen für die gängigsten Fachstandards der Verwaltung findet sich [hier](/details/schema-reference.md). +Eine Erläuterung der Fachschemareferenzen für die gängigsten Fachstandards der Verwaltung findet sich [hier](/details/schema-reference.md).