API Startseite

Getting Started

Dieser Confluence-Bereich soll als Ergänzung zur Swagger-Dokumentation dienen und das allgemeine Verständnis vermitteln, welches nicht einer Swagger-Dokumentation entnommen werden kann. Zum Beispiel wie die API-Aufrufe (und damit die Daten) zusammenhängen und in welcher Reihenfolge Aufrufe Sinn machen.

Swagger-Doku

Die Swagger-Dokumentation zur API ist auf zwei Wegen zu erreichen:

  • eine öffentliche Version, die den “stable release” widerspiegelt → https://demo.advo-net.net/swagger/index.html

  • eine lokale immer zu Ihrer Version passende Swagger-Doku → z.B. auf Ihrem Server http://127.0.0.1:CONNECTOR-PORT/swagger

    • CONNECTOR-PORT ist über die advoware Manager GUI einsehbar

Voraussetzungen zur Nutzung der API

Workflow zur richtigen Nutzung der API

So würde eine Kommunikation ablaufen:

  1. URL-Dienst mit dem Parameter “Kanzleikennung” aufrufen um die Basis-URL für die API-Aufrufe abzufragen, für Kanzlei “Mustermann” z.B.:

    https://www2.advo-net.net/AdvonetConfigurator/api/Url?Kanzlei=Mustermann
  2. Man erhält eine JSON-Struktur die z.B. so aussehen könnte:

    {"relayUrl":"https://www2.advo-net.net:90/","connectorUrl":"https://test.advo-net.org:88/"}
  3. Ist “connectorUrl” gesetzt MUSS diese auch als Basis-Adresse verwendet werden, ist diese null oder wird nicht übermittelt, wird die “relayUrl” verwendet!

  4. Man benötigt ein sogenanntes Token für API-Aufrufe, Anleitung für die https://advoware.atlassian.net/wiki/spaces/HANVERTINT/pages/69500929

  5. API-Aufruf z.B. an

    GET https://www2.advo-net.net:90/api/v1/Akten

Hilfe zu Problemen und Fehlern finden sie hier https://advoware.atlassian.net/wiki/spaces/HANVERTINT/pages/163741699

advoware Workflow (Beispiel Aktenanlage, Beteiligte prüfen und anlegen und Verknüpfung herstellen)

Um die API sinnvoll nutzen zu können muss man ein wenig über den “Workflow” wissen, also die Art und Weise, wie die advoware Datenstruktur aufgebaut ist.

Den meisten Daten liegt eine Akte zugrunde. Es gibt aber auch Ausnahmen. So sind zum Beispiel Beteiligte eigenständige Datensätze die erstmal ohne eine Akte auskommen, die aber mit einer Akte verknüpft werden können.

Ein beispielhafter Workflow (… = die Basisurl)

  1. Aktenanlage mit POST …/Akten

  2. Prüfung aller Beteiligten: Sind Datensätze bereits vorhanden (GET …/Beteiligte, Verwendung von Query-Parametern)

  3. Falls Beteiligte NICHT vorhanden sind: Anlage der Beteiligten via (POST …/Beteiligte)

    1. Das Feld “rechtsform” kann vorher via (GET …/Rechtsformen) abgerufen und dann entsprechend gefüllt werden → Hinweis: Die URL dieses Aufrufs wird sich in einer zukünftigen Version ändern.

  4. Verknüpfen der gefundenen oder angelegten Beteiligten (aus Punkt 2 und 3) via (POST …/Beteiligung) → Hinweis: Die URL dieses Aufrufs wird sich in einer zukünftigen Version ändern.

    1. Die Felder “art” sowie “kz” gehören zusammen und beschreiben die Art eines Beteiligten (Mandant, Gegner, Versicherung, Gutachter, etc.) und können via (GET …/BeteiligteArten) abgerufen werden

    2. Soll ein Beteiligter einem anderen Beteiligten untergeordnet werden kann man die Felder “master” sowie “ebene” nutzen; “master” enthält die BetNr des übergeordneten Beteiligten, wohingegen “ebene” mit 1,2,3, … die Ebene angibt

    3. Die Felder “betreff”, “betreff2”, “betreff3” können, müssen aber nicht befüllt werden; wenn sie befüllt werden sind sie wie folgt zu befüllen:

      1. bei “art” = “Rechtsschutzversicherung” oder “art” = “Haftpflichtversicherung”

        1. betreff = Versicherungsscheinnummer

        2. betreff2 = Schadennummer

        3. betreff3 = Betreff

      2. ansonsten

        1. betreff = Betreff

        2. betreff2 + betreff3 = nicht gesetzt oder “null”


Mehr Ideen?
  • Die “NR” steht immer für die Aktennummer, eine zehnstellige Zahl mit dem Jahr der Akte beginnend, aufgefüllt mit Nullen und die Aktennummer. 1/21 wäre 2021000001.

  • Die API wird nach und nach vereinheitlicht und von den Begriffen her modernisiert, d.h.

    • NR (für die Aktennummer) kann an einigen Stellen AkteId heißen oder in einem Aufruf wie GET …/Akten/{id} einfach nur “id”

    • BetNr (Für Beteiligtennummer) kann an einigen Stellen BetId heißen

  • Als Authentifizierung wird zukünftig nur noch die Token-Authentifizierung unterstützt.

  • Die “ROWID” dient zur Prüfung ob ein Datensatz geändert wurde (ähnlich eines Hashes). Die ROWID sollte nur bei GET-Endpunkten vorkommen, fälschlicherweise tauchen diese aktuell noch in einigen POST-Endpunkten auf, wo sie getrost ignoriert werden können.