Schnittstellen

MACH formsolutions stellt Schnittstellen zur Verfügung, um verschiedene Informationen über den Formularserver auszulesen, sowie Datensätze automatisiert abzurufen und zu aktualisieren.

Die Schnittstellen beruhen auf dem REST-Standard. Sie werden über eine URL angesprochen. Hierbei gibt es einen festen Basispfad und einen ergänzenden Endpunkt. Der Basispfad ist bei jedem Aufruf gleich, die Endpunkte unterscheiden sich je nach Funktion. Ein Endpunkt spricht eine Funktionalität der Schnittstelle an.

Um die API-Schnittstellen verwenden zu können, ist die Authentifizierung auf Mandantenbasis durch einen API-Key/Schlüssel erforderlich. Der API-Key kann beim Support Ihres Formularserverbetreibers beantragt werden.
Die Anleitung für Formularserverbetreiber finden Sie in der Dokumentation zum Anlegen von API-Keys.

Der Supermandant hat als übergeordnete Instanz Zugriff auf alle Mandanten.

Übersicht der APIs

Server-Information-API

Zweck allgemeine Informationen über den Server und die verfügbaren Schnittstellen

Ausgabeformat

JSON

weitere Informationen

Dokumentation

Dokumentation Server-Information-API

Search-API

Zweck Suchergebnisse, wie sie über die Benutzeroberfläche zu erlangen sind

Ausgabeformat

JSON

weitere Informationen

OpenAPI Spezifikation v3

Damit die Suchlogik abgebildet und die Suchergebnisse gefiltert werden können, bietet die Schnittstelle einige Query-Parameter an, die an die URL angefügt werden können.

Dokumentation

Dokumentation Search-API

Release-API

Zweck Veröffentlichungen auslesen; sowohl Assistenten als auch PDF-Formulare

Ausgabeformat

JSON; CSV

weitere Informationen

OpenAPI Spezifikation v3

Wir stellen mehrere Versionen der Release-API zur Verfügung.

Dokumentation

Dokumentation Release-API

Submission-API

Zweck Abruf von Informationen zu eingegangenen Formularen und von Formulardaten

Ausgabeformat

JSON

weitere Informationen

OpenAPI Spezifikation v3

Einreichungen zu einem Formular/Artikelnummer für den Mandanten

  • Übersicht der Einreichungen (nur Metadaten)

  • Einschränkung der Suche

    • nach Bearbeitungsstatus (z.B. "NEW")

    • nach Einreichungszeitpunkt

Spezifische Einreichungen

  • Abruf einer konkreten Einreichung

    • Metadaten

    • Inhalte

  • Änderung des Bearbeitungsstatus einer Einreichung

Wir stellen mehrere Versionen der Submission-API zur Verfügung.

Versionshistorie

Submission-API Release-Notes

Dokumentation

Dokumentation Submission-API

Error-API

Zweck Auflistung von Fehlern im Antragsprozess; alternativer Zugang zu Fehlerinformationen, ohne einen Formularserver-Administrator zu kontaktieren

Ausgabeformat

JSON

weitere Informationen

OpenAPI Spezifikation v3

Während des Antragsprozesses kann der Assistent unerwartet auf einen Fehler laufen.

Mit der Error-API stellt MACH formsolutions eine Lösung bereit, Fehlerursachen festzustellen, ohne einen Formularserver-Administrator zu kontaktieren.

Um die Schnittstelle verwenden zu können, ist es notwendig beim Assistentenstart eine "errorUrl" zu übergeben, wie unter Rücksprung-URLs beschrieben.
In Fehlerfällen während des Antragsprozesses wird dadurch der Parameter "errorId" an die URL angehängt. Mit dieser ID können Informationen zum Fehler über die Schnittstelle ausgelesen werden.

Dokumentation

Dokumentation Error-API

Unterstützung von Vorgängerversionen und abgekündigten APIs

Versionierung

Unsere APIs sind für eine lange Betriebsphase und Versionskompatibilität konzipiert.

Wir behalten immer zwei Versionen online, soweit technisch möglich. Sobald eine neue Version hinzukommt, wird die älteste Version mit einem zeitlichen Horizont von mindestens 6 Monaten abgekündigt. Nach dieser Frist sind die veraltete Version und alle ihre Minor-Versionen nicht mehr erreichbar.

Eine neue Major-Version (1.x) kann Änderungen beinhalten, die nicht abwärtskompatibel sind. Dies sind z.B.:

  • Authentifizierungsmethoden

  • Umbenennung und Löschung von Endpunkten

  • Löschung von HTTP-Methoden an vorhandenen Endpunkten

  • Umbenennung und Löschung von Parametern

  • Restrukturierung des Response-Objekts

Eine neue Minor-Version (x.1) ist definitionsgemäß abwärtskompatibel zur Major-Version. Änderungen wären z.B.:

  • Zusätzliche Endpunkte

  • Zusätzliche HTTP-Methoden an Endpunkten

  • Weitere (optionale) Parameter für eine Abfrage (z.B. Filterfunktion)

  • Erweitertes Response-Objekt

Beta-Version (x.x-beta)
Beta-Versionen dienen der frühzeitigen Bereitstellung neuer Funktionen vor der Überführung in eine reguläre Minor- oder Major-Version. Ihre Kompatibilität richtet sich nach dem zugrunde liegenden Versionsschema: Eine Minor-beta verhält sich abwärtskompatibel zur zugehörigen Major-Version, eine Major-beta kann – analog zu einer Major-Version – nicht abwärtskompatible Änderungen enthalten.

Innerhalb derselben Beta-Version erfolgen ausschließlich funktionale Erweiterungen (z.B. zusätzliche Endpunkte, optionale Parameter oder Erweiterungen des Response-Objekts). Bestehende Funktionalitäten werden innerhalb dieser Beta-Version nicht entfernt oder inkompatibel verändert; insofern ist sie für sich genommen kompatibilitätsstabil.