Die AdvoAssist-API
Für Ausschreiber großer Volumina von Gerichtsterminen oder Hersteller von Kanzleisoftware bietet AdvoAssist eine direkte Schnittstelle an. Nachfolgend finden Sie eine einleitende Dokumentation - Sie können Ihre Ansteuerung der Schnittstelle jederzeit mit Test-Nutzerdaten (auf Anfrage) testen. Bei Rückfragen wenden Sie sich bitte direkt an unsere technische Leitung unter kihm@advo-assist.de.
Technischer Aufbau
Authentifizierungs-Token
Jedem Account ist ein API-Token zugeordnet, der über den Link https://www.advo-assist.de/mitglieder/token/ abgerufen werden kann.
ACHTUNG: Der Token wird bei jeder Passwort-Änderung/Zurücksetzung neu erstellt!
Abfragen und Rückmeldungen der API
Sämtliche Abfragen werden als HTTPS-Request (GET oder POST, aus Kompatibilitätsgründen beide möglich) inkl. dem Authentifizierungs-Token an den jeweiligen Endpunkt gesendet und beinhalten optional übergebene weitere Variablen:
https://www.advo-assist.de/api/$endpoint/?token=$token&...
Bitte beachten Sie: Jede Endpoint-URL hat am Ende einen Slash (/) vor dem Fragezeichen und den Parametern.
Als Ergebnis liefert die AdvoAssist-API direkt ein JSON-Paket. Der Inhalt des Antwort-Pakets hängt vom jeweiligen Endpunkt ab, beinhaltet jedoch mindestens das Feld result mit den angeforderten Informationen bzw. einer Erfolgs-/Fehlermeldung. Im Fehlerfall wird zusätzlich ein HTTP-Headerfehler vorangeschickt (HTTP-Code 400 bzw. 401 bei fehlender Autorisierung).
Verfügbare Endpunkte
◊ "status": Anstehende und ausgeschriebene Termine
Über diesen Endpunkt können Sie die Gesamtliste aller Ihrer anstehenden und ausgeschriebenen Termine inkl. Vertretungsangeboten abrufen. Der Abruf beinhaltet neben dem Token keine zusätzlichen Parameter.
◊ "vergabe": Neue Termin-Ausschreibung
Über diesen Endpunkt können Sie neue Termine ausschreiben.
Parameter sind Pflicht, wenn sie mit * gekennzeichnet sind. Bei optionalen Wahlfeldern dient das Kennzeichen * als Default.
Der Aufruf beinhaltet neben dem Token folgende Parameter:
| Parameter | Mögliche Werte | ||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| typ | g* (Gerichtstermin) / o (Ortstermin) / a (Akteneinsicht) | ||||||||||||||||
| beweisaufnahme | 0 (keine Beweisaufnahme) / 1 (absehbare Beweisaufnahme) | ||||||||||||||||
| honorar | -1 (offen) / 0* (streitwertbasiert) / 80 / 110 (siehe Konditionen) | ||||||||||||||||
| zuschlag | 0*-999 (ganze € Aufschlag zusätzlich zum Pauschalhonorar) | ||||||||||||||||
| streitwert | 0-9999999 (ganze €) | ||||||||||||||||
| tag* | 1-31 (Tag des Termins) | ||||||||||||||||
| monat* | 1-12 (Monat des Termins) | ||||||||||||||||
| jahr* | 2024-2025 (Jahr des Termins) | ||||||||||||||||
| stunde* | 6-22 (Stunde des Termins) | ||||||||||||||||
| minute* | 0-59 (Minute des Termins) | ||||||||||||||||
| d_tag* | analog zu den Datums-/Zeitwerten des Termins (oben) wird die Vergabefrist (Deadline) festgelegt. Bitte beachten Sie, dass diese bei kontrollierter Vergabe in den nächsten 7 Tagen liegen muss. | ||||||||||||||||
| d_monat* | |||||||||||||||||
| d_jahr* | |||||||||||||||||
| d_stunde* | |||||||||||||||||
| d_minute* | |||||||||||||||||
| gericht* | 3-3188 (Nummer des Gerichtes aus der Gerichtsliste) | ||||||||||||||||
| plz | "01067"-"99998" (statt Gericht, NUR für Ortstermine und Akteneinsichten) | ||||||||||||||||
| dauer | Textfeld, z.B. "nur 15min" | ||||||||||||||||
| fachrichtung* | Textfeld, z.B. "Verkehrszivilrecht" | ||||||||||||||||
| rechtsgebiet | Kennzeichen für "Massen-Rechtsgebiete" 1 Verkehrsordnungswidrigkeit / 2 Anwaltliches Inkasso / 3 Einvernehmliche Scheidung / 4 Bank/Kredit/Lebensversicherung / 5 Filesharing / 6 Abgasskandal /
| ||||||||||||||||
| beschreibung* | Textfeld, z.B. "Forderung aus Warenverkauf" | ||||||||||||||||
| az | Textfeld für Aktenzeichen, z.B. "123/16 mü" | ||||||||||||||||
| parteien | Textfeld für beteiligte Parteien, z.B. "Müller ./. Meier" | ||||||||||||||||
| beschreibung2 | Textfeld für Informationen nur an den späteren Vertreter | ||||||||||||||||
| anzahl | 1-99 (Anzahl Termine im Sammeltermin) | ||||||||||||||||
| confirm | 0* (direkte Vergabe) / 1 (kontrollierte Vergabe) | ||||||||||||||||
| bericht | 0* (klassischer Terminsbericht) / 1 (Textform per AdvoAssist) | ||||||||||||||||
| gutschrift | 0* (Rechnung durch Vertreter) / 1 (Gutschrift durch Ausschreiber) | ||||||||||||||||
| video | 0* (Präsenztermin) / 1 (Videokonferenz) / 2 (Präsenz mit Video-Option) | ||||||||||||||||
| bundesweit | 0* (regionale Ausschreibung) / 1 (unbeschränkt, nur bei Videoterminen möglich) | ||||||||||||||||
◊ "confirm": Bewerberauswahl/-bestätigung
Über diesen Endpunkt können Sie Terminsvertreter bestätigen, die sich bei kontrollierter Vergabe für die Vertretung angeboten haben (vgl. Feld "angebote" im Statusabruf oben).
Der Aufruf beinhaltet neben dem Token folgende Parameter:
| Parameter | Beschreibung |
|---|---|
| nr* | Nummer des Termins |
| kanzlei* | Kundennummer der gewählten Kanzlei |
◊ "absage": Terminabsage
Über diesen Endpunkt können Sie einen Termin absagen.
Der Aufruf beinhaltet neben dem Token folgende Parameter:
| Parameter | Beschreibung |
|---|---|
| nr* | Nummer des Termins |
| grund* | Textfeld für eine kurze Begründung |
◊ "verschieben": Termin-Verlegung
Über diesen Endpunkt können Sie ausgeschriebene oder vergebene Termine verschieben.
Der Aufruf beinhaltet neben dem Token folgende Parameter:
| Parameter | Mögliche Werte |
|---|---|
| nr* | Nummer des Termins (6-stellig) |
| tag* | 1-31 (Tag des Termins) |
| monat* | 1-12 (Monat des Termins) |
| jahr* | 2024-2025 (Jahr des Termins) |
| stunde* | 6-22 (Stunde des Termins) |
| minute* | 0-59 (Minute des Termins) |
| d_tag* | analog zu den Datums-/Zeitwerten des Termins (oben) wird die Vergabefrist (Deadline) festgelegt. Bitte beachten Sie, dass diese bei kontrollierter Vergabe in den nächsten 7 Tagen liegen muss. |
| d_monat* | |
| d_jahr* | |
| d_stunde* | |
| d_minute* | |
| video* | 0-2 Kann optional benutzt werden. Bei Präsenzterminen kann diese Option nicht geändert werden und bei zwingenden Videoterminen kann nicht in Präsenztermin geändert werden, ansonsten bedeutet: 0: Präsenztermin 1: zwingender Videotermin 2: möglicher Videotermin |
◊ "folgetermin": Folgetermin eintragen
Über diesen Endpunkt können Sie Folgetermin zu einem Ursprungstermin eintragen.
Das Zusatzhonorar ist optional anzugeben, wenn im Ursprungstermin nichts dazu vereinbart wurde.
Der Aufruf beinhaltet neben dem Token folgende Parameter:
| Parameter | Mögliche Werte |
|---|---|
| nr* | Nummer des Termins, zu dem ein Folgetermin eingetragen werden soll (6-stellig) |
| tag* | 1-31 (Tag des Folgetermins) |
| monat* | 1-12 (Monat des Folgetermins) |
| jahr* | 2024-2025 (Jahr des Folgetermins) |
| stunde* | 6-22 (Stunde des Folgetermins) |
| minute* | 0-59 (Minute des Folgetermins) |
| zusatzhonorar | 0-999 (optional Zusatzhonorar des Folgetermins, falls nicht mit dem Ursprungstermin bereits abgegolten) |
◊ "upload": Datei-Upload
Über diesen Endpunkt können Sie Dateien zu einem Termin hochladen.
Der Aufruf beinhaltet neben dem Token folgende Parameter:
| Parameter | Beschreibung |
|---|---|
| termin* | Nummer des Termins |
| filename* | Name der Datei |
| base64* | Content (base64-encodiert) der Datei |
Bitte beachten Sie: POST-Requests an diesen Endpoint müssen zwingend im Format x-www-form-urlencoded stattfinden.
◊ "dateien": Datei-Auflistung
Über diesen Endpunkt können Sie Dateien zu einem Termin wieder auflisten.
Der Aufruf beinhaltet neben dem Token nur einen Parameter:
| Parameter | Beschreibung |
|---|---|
| termin* | Nummer des Termins |
◊ "download": Datei-Download
Über diesen Endpunkt können Sie Dateien zu einem Termin herunterladen.
Der Aufruf beinhaltet neben dem Token folgende Parameter:
| Parameter | Beschreibung |
|---|---|
| termin* | Nummer des Termins |
| id* | ID der Datei |
| base64 | 0* (binärer Download) / 1 (base64-Download) |
Das Ergebnis dieses Abrufs ist direkt die angeforderte Datei bzw. eine Fehlermeldung.
◊ "datei-entfernen": Datei-Löschung
Über diesen Endpunkt können Sie von Ihnen hochgeladene Dateien von einem Termin wieder löschen.
Bitte beachten Sie: Nach Ablauf einer Frist von min. 30 Tagen nach dem Termin geschieht dies aus Datenschutzgründen auch automatisch.
Der Aufruf beinhaltet neben dem Token folgende Parameter:
| Parameter | Beschreibung |
|---|---|
| termin* | Nummer des Termins |
| id* | ID der Datei |
◊ "bewertung": Terminsvertreter-Bewertung
Über diesen Endpunkt können Sie Vertreter vergangener Termine bewerten.
Der Aufruf beinhaltet neben dem Token folgende Parameter:
| Parameter | Beschreibung |
|---|---|
| termin* | Nummer des Termins |
| sterne* | Bewertung (1-5 Sterne) |
| kommentar | Kommentar (optionale Details zur Bewertung) |
◊ "bericht": Terminsbericht abrufen
Über diesen Endpunkt können Sie die neuesten eingetragenen Berichte vergangener Termine abrufen.
Terminsberichte gelten so lange als neu, bis die zugehörige Terminsvertretung bewertet wurde.
Der Aufruf beinhaltet neben dem Token nur einen Parameter:
| Parameter | Beschreibung |
|---|---|
| nr* | Nummer des Termins (6-stellig) |
◊ "reset": Termin wieder öffnen
Über diesen Endpunkt können Sie gelöschte, abgesagte oder vergebene Termine wieder zur Ausschreibung öffnen. Hierbei werden der gewählte Vertreter annuliert, der Status auf aktiv (nicht mehr gelöscht/abgesagt) gesetzt und alle infrage kommenden Kanzleien erneut benachrichtigt.
Der Aufruf beinhaltet neben dem Token folgende Parameter:
| Parameter | Beschreibung |
|---|---|
| nr* | Nummer des Termins (6-stellig) |
◊ "gutschrift": Termin per Gutschrift statt Rechnung abrechnen
Über diesen Endpunkt können Sie als ausschreibende Kanzlei einen Termin nach erfolgreicher Vertretung im Gutschriftverfahren abrechnen. Dies ersetzt die Rechnungsstellung durch den Terminsvertreter.
Der Aufruf beinhaltet neben dem Token folgende Parameter:
| Parameter | Beschreibung |
|---|---|
| nr* | Nummer des Termins (6-stellig) |
| honorar_final* | endgültiges Honorar (ganzzahlig, netto, für Korrekturen oder Folgetermine) |
| lfd_nr* | laufende Nummer (Rechnungs-/Gutschriftnummer) |
Die Rückgabewerte des Aufrufs beinhalten im Erfolgsfall dann IBAN, Kontoinhaber und Betrag und können direkt für Zahlungen weiterverarbeitet werden.
◊ "stats": Statistiken Ihrer Termine abrufen
Über diesen Endpunkt können Sie Ihre historische Vergabestatistik abrufen. Sie berücksichtigt alle Termine, die entweder einen gewählten Vertreter haben, bis zur Deadline keinen Vertreter erhalten haben oder von Ihnen gelöscht bzw. abgesagt wurden.
Der Aufruf beinhaltet neben dem Token zwei optionale Parameter:
| Parameter | Beschreibung |
|---|---|
| jahr | Integer: Jahr der Ausschreibung (ansonsten alle) |
| monat | Integer: Monat der Ausschreibung (ansonsten alle) |
Spezielle Endpunkte für Select-Kunden
Diese Endpunkte stehen nur Kunden zur Verfügung, die für AdvoAssist Select freigeschaltet sind.
◊ "select-liste": Select-Präferenzen
Über diesen Endpunkt können Sie Ihre Select-Präferenzen ggü. potentiellen Vertretern abrufen.
Der Aufruf beinhaltet neben dem Token nur einen optionalen Parameter:
| Parameter | Beschreibung |
|---|---|
| detail | 0* / 1 (Detaildarstellung statt nur Kanzleinummer) |
◊ "select": Select-Präferenz festlegen
Über diesen Endpunkt können Sie Kanzleien in Ihrem Select-Netzwerk ausschließen oder bevorzugen.
Der Aufruf beinhaltet neben dem Token folgende Parameter:
| Parameter | Beschreibung |
|---|---|
| target* | Nummer der Kanzlei (5-stellig) |
| pref* | 0 / 1 / 2 (0: Ausschluss, 1: normal, 2: Bevorzugung) |