FIM-Konverter – API-Dokumentation

Authentifizierung

HTTP-Header

X-API-Key: 97612377732d405c37394978e1e9c846

401

Fehlt oder ungültig

Jede Anfrage braucht diesen Schlüssel. Ungültige Anfragen werden vor der Verarbeitung abgewiesen.

Endpoint

POST/convertXProzess in BPMN umwandeln

Anfrage

Methode: POST
Pfad: /convert
Header: X-API-Key: 97612377732d405c37394978e1e9c846
Körper: XProzess-Datei als Text
Maximalgröße: 10 MB

Ein Content-Type ist nicht erforderlich. application/xml ist dennoch sinnvoll, weil er den Inhalt beschreibt.

Beispiel

curl -X POST \
  -H "X-API-Key: 97612377732d405c37394978e1e9c846" \
  -H "Content-Type: application/xml" \
  --data-binary @prozess.xprozess.xml \
  https://fim-bpmn.onrender.com/convert

Antwort

200Konvertierung erfolgreich

{
  "bpmn": "<?xml version=\"1.0\" encoding=\"utf-8\"?>\n<definitions …>…</definitions>",
  "warnings": []
}

Feld	Typ	Bedeutung
bpmn	string	Vollständiges BPMN-2.0-Dokument als XML
warnings	array	Auffälligkeiten; leer, wenn alles glatt lief

Zuordnung der FIM-Daten

Prozessebene

<collaboration>, ersatzweise der einzige <process>

Aktivitätengruppe

<subProcess> mit passender ID, zugeordnet über subProcessId

<subProcess id="_27356b24-7f40-4bcd-b2c4-3453c37494e8" name="Fristwahrung prüfen">
  <extensionElements>
    <adonis:instance>…unverändert…</adonis:instance>
    <fim:id>05</fim:id>
    <fim:name>Fristwahrung prüfen</fim:name>
    <fim:referenzaktivitaetengruppeTyp code="3"
      listURI="urn:xoev-de:fim:codeliste:referenzaktivitaetengruppe"
      listVersionID="20230301"/>
    <fim:handlungsgrundlage>
      <fim:name>§ 5 (1) 21. BImSchV</fim:name>
      <fim:art code="111" listURI="urn:xoev-de:fim:codeliste:handlungsgrundlagenart" listVersionID="20230301"/>
      <fim:uri>https://www.gesetze-im-internet.de/bimschv_21/__5.html</fim:uri>
    </fim:handlungsgrundlage>
  </extensionElements>
</subProcess>

Namespace

xmlns:fim="http://fim-bpmn.org/schema/1.0"

Abbildungsregeln

Einfache Werte werden Elementinhalt.
Codelisten werden Attribute.
Verschachtelte Strukturen bleiben verschachtelt.

Die Umwandlung ist wiederholbar: Dieselbe Eingabe erzeugt dieselbe Ausgabe. Eine erneute Befüllung bereits konvertierter Daten verändert nichts.

Warnungen

Warnungen brechen die Umwandlung nicht ab. Für programmatische Reaktionen ist "code" maßgeblich; der Meldungstext kann sich ändern.

{
  "code": "empty-value",
  "message": "Das Element <gueltigkeitszeitraum> ist leer und wird uebersprungen.",
  "path": ["zustandsangaben", "gueltigkeitszeitraum"]
}

Code	Bedeutung
empty-value	Leeres Element wurde ausgelassen
version-signals-conflict	Versionsangaben widersprechen sich; verarbeitet wurde als 2.0
unexpected-embedded-content	Archiv enthielt mehr als die BPMN-Datei
missing-subprocess-id	Aktivitätengruppe ohne subProcessId wurde übersprungen
duplicate-subprocess-id	Doppelte subProcessId; nur die erste wurde übernommen
subprocess-not-found	Verwiesener subProcess existiert nicht im BPMN

Fehler

Alle Fehlerantworten haben dieselbe Form:

{ "error": "Beschreibung des Problems" }

Status	Bedeutung	Beispiel
400	Datei ist unbrauchbar	XML ist nicht wohlgeformt …
401	Schlüssel fehlt oder ist falsch	Kein oder falscher API-Schluessel.
413	Körper ist größer als 10 MB	Die Anfrage ist groesser als 10485760 Bytes.
500	Fehler im Dienst	Interner Fehler.

Bei 400 nennt die Meldung die Ursache so genau wie möglich, einschließlich Zeile und Spalte. Bei 500 bleibt sie bewusst unspezifisch.

Typische 400er

Körper leer
XML nicht wohlgeformt
Keine XProzess-2.0-Datei
Kein eingebettetes BPMN

404 — Unbekannte Pfade liefern den Klartext 404 Not Found, nicht JSON.

Grenzen

XProzess 2.0

Nur der Namespace http://www.regierung-mv.de/xprozess/2 wird verarbeitet. Andere Versionen werden mit 400 abgelehnt.

Codelisten

Codes werden nicht aufgelöst. Ihre Bedeutung bleibt über listURI referenziert.

BPMN-Referenzen

Kaputte Referenzen im eingebetteten BPMN werden nicht repariert.

bpmn-js

Ein moddle-Deskriptor wird nicht mitgeliefert und muss beim Einlesen separat bereitgestellt werden.