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.

Beispielhaft für diese und nachfolgende Abfragen sei ein Demo-Account (Kundennummer 13990) dargestellt:
https://www.advo-assist.de/api/status/?token=8cbcbe15728057fe70d63ba3bc00c0d7

◊ "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:

ParameterMögliche Werte
typg* (Gerichtstermin) / o (Ortstermin) / a (Akteneinsicht)
beweisaufnahme0 (keine Beweisaufnahme) / 1 (absehbare Beweisaufnahme)
honorar-1 (offen) / 0* (streitwertbasiert) / 50 / 100 (siehe Konditionen)
zuschlag0*-999 (ganze € Aufschlag zusätzlich zum Pauschalhonorar)
streitwert0-9999999 (ganze €)
tag*1-31 (Tag des Termins)
monat*1-12 (Monat des Termins)
jahr*2020-2021 (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)
dauerTextfeld, z.B. "nur 15min"
fachrichtung*Textfeld, z.B. "Verkehrszivilrecht"
rechtsgebietKennzeichen für "Massen-Rechtsgebiete"
Verkehrsordnungswidrigkeit /  Anwaltliches Inkasso /  Einvernehmliche Scheidung /  Bank/Kredit/Lebensversicherung /  Filesharing /  Abgasskandal
beschreibung*Textfeld, z.B. "Forderung aus Warenverkauf"
azTextfeld für Aktenzeichen, z.B. "123/16 mü"
parteienTextfeld für beteiligte Parteien, z.B. "Müller ./. Meier"
beschreibung2Textfeld für Informationen nur an den späteren Vertreter
anzahl1-99 (Anzahl Termine im Sammeltermin)
confirm0* (direkte Vergabe) / 1 (kontrollierte Vergabe)
bericht0* (klassischer Terminsbericht) / 1 (Textform per AdvoAssist)
gutschrift0* (Rechnung durch Vertreter) / 1 (Gutschrift durch Ausschreiber)

◊ "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:

ParameterBeschreibung
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:

ParameterBeschreibung
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:

ParameterMögliche Werte
nr*Nummer des Termins (6-stellig)
tag*1-31 (Tag des Termins)
monat*1-12 (Monat des Termins)
jahr*2020-2021 (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*

◊ "upload": Datei-Upload

Über diesen Endpunkt können Sie Dateien zu einem Termin hochladen.
Der Aufruf beinhaltet neben dem Token folgende Parameter:

ParameterBeschreibung
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:

ParameterBeschreibung
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:

ParameterBeschreibung
termin*Nummer des Termins
id*ID der Datei
base640* (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:

ParameterBeschreibung
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:

ParameterBeschreibung
termin*Nummer des Termins
sterne*Bewertung (1-5 Sterne)
kommentarKommentar (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:

ParameterBeschreibung
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:

ParameterBeschreibung
nr*Nummer des Termins (6-stellig)

◊ "termindetails": Detail-Daten eines Termin abrufen

Über diesen Endpunkt können Sie detaillierte Daten eines Termins abrufen.
Der Aufruf beinhaltet neben dem Token folgende Parameter:

ParameterBeschreibung
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:

ParameterBeschreibung
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:

ParameterBeschreibung
jahrInteger: Jahr der Ausschreibung (ansonsten alle)
monatInteger: 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:

ParameterBeschreibung
detail0* / 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:

ParameterBeschreibung
target*Nummer der Kanzlei (5-stellig)
pref*0 / 1 / 2 (0: Ausschluss, 1: normal, 2: Bevorzugung)