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
Es wird eine “Kanzleikennung” benötigt sowie einen laufenden advoware Manager → Kanzleikennung https://advoware.atlassian.net/wiki/spaces/HANVERTINT/pages/388235265 und https://advoware.atlassian.net/wiki/spaces/HANVERTINT/pages/154664961
Bevor man die API nutzen möchte, benötigen wir die “Kanzleikennung”, um sogenannte “App-ID” sowie einen “API-Key” auszustellen→ erhält man durch advoware GmbH: api@advoware.de
(Info für Drittanbieter) Jede App-ID muss für jede Kanzleikennung freigeschaltet werden → durch advoware GmbH
Workflow zur richtigen Nutzung der API
So würde eine Kommunikation ablaufen:
-
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
-
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/"}
Ist “connectorUrl” gesetzt MUSS diese auch als Basis-Adresse verwendet werden, ist diese null oder wird nicht übermittelt, wird die “relayUrl” verwendet!
Man benötigt ein sogenanntes Token für API-Aufrufe, Anleitung für die https://advoware.atlassian.net/wiki/spaces/HANVERTINT/pages/69500929
-
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)
Aktenanlage mit POST …/Akten
Prüfung aller Beteiligten: Sind Datensätze bereits vorhanden (GET …/Beteiligte, Verwendung von Query-Parametern)
-
Falls Beteiligte NICHT vorhanden sind: Anlage der Beteiligten via (POST …/Beteiligte)
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.
-
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.
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
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
-
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:
-
bei “art” = “Rechtsschutzversicherung” oder “art” = “Haftpflichtversicherung”
betreff = Versicherungsscheinnummer
betreff2 = Schadennummer
betreff3 = Betreff
-
ansonsten
betreff = Betreff
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.