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

Wichtiger Hinweis:
Diese Dokumentation bezieht sich auf die aktuelle Version 3.0 der API.
Calls an sämtliche älteren Versionen werden in Kürze nicht mehr funktionsfähig sein - bitte updaten Sie ggf. Ihre Implementation.

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&...

Als Ergebnis liefert die AdvoAssist-API direkt ein JSON-Paket mit den angeforderten Informationen bzw. eine Erfolgs-/Fehlermeldung zurück. Der Inhalt der Antwort hängt vom jeweiligen Endpunkt ab und ist unten jeweils beispielhaft dargestellt.

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=286f8e91d7360920bcd9353c15a0221c

Das Ergebnis dieses Abrufs ist ein JSON-Paket der nachfolgenden Struktur:

[anstehend] =>
(
	[0] =>
	(
		[nr] => 000780
		[zeitpunkt] => 14.07.17 18:00
		[ort] => AG Döbeln
		[wahrnehmer] =>
		(
			[nr] => 13988
			[name] => Anwaltskanzlei Dr. Gerda Gerechtigkeit
			[anschrift] => Musterstr. 1
			[plz] => 06502
			[ort] => Neinstedt
			[telefon] => 012-34567
			[fax] => 012-34567
			[email] => demo@advo-assist.de
		)
		[tarif] => 1
		[honorar] => 65
		[typ] => GT
		[az] =>
	)

	[1] =>
	(
		[nr] => 019876
		[zeitpunkt] => 07.12.17 17:00
		[ort] => PLZ-Gebiet 27313
		[wahrnehmer] =>
		(
			[nr] => 13988
			[name] => Anwaltskanzlei Dr. Gerda Gerechtigkeit
			[anschrift] => Musterstr. 1
			[plz] => 06502
			[ort] => Neinstedt
			[telefon] => 012-34567
			[fax] => 012-34567
			[email] => demo@advo-assist.de
		)
		[tarif] => 1
		[honorar] => 110
		[typ] => AE
		[az] =>
	)

)

[ausgeschrieben] =>
(
	[0] =>
	(
		[nr] => 000773
		[zeitpunkt] => 21.02.17 12:00
		[deadline] => 01.02.17 16:00
		[abgelaufen] => 0
		[ort] => AG Schwalmstadt
		[tarif] => 1
		[honorar] => 75
		[typ] => GT
		[az] =>
	)

	[1] =>
	(
		[nr] => 000980
		[zeitpunkt] => 28.07.17 08:00
		[deadline] => 01.07.17 16:00
		[abgelaufen] => 0
		[ort] => ArbG Lingen (Ems)
		[tarif] => 1
		[honorar] => 0
		[typ] => GT
		[az] =>
		[angebote] => Array
			(
				[0] =>
				(
					[bewerber] => 14944
					[text] => Langjährige Erfahrung
					[honorar] => 70
					[sterne] => 4.9
					[termine] => 20
				)

				[1] =>
				(
					[bewerber] => 14955
					[text] => Bereits über 400 Terminsvertretungen
					[honorar] => 150
					[termine] => 420
				)
			)
	)

	[2] =>
	(
		[nr] => 001815
		[zeitpunkt] => 10.10.17 10:00
		[deadline] => 01.10.17 16:00
		[abgelaufen] => 0
		[ort] => LG Limburg/Lahn
		[tarif] => 2
		[honorar] => 260
		[typ] => GT
		[az] =>
	)

	[3] =>
	(
		[nr] => 000998
		[zeitpunkt] => 09.11.17 17:00
		[deadline] => 01.11.17 16:00
		[abgelaufen] => 0
		[ort] => AG Kenzingen
		[tarif] => 1
		[honorar] => 70
		[typ] => GT
		[az] =>
	)

)

◊ "vergabe": Neue Termin-Ausschreibung

Über diesen Endpunkt können Sie neue Termine ausschreiben.
Der Aufruf beinhaltet neben dem Token folgende Parameter:

ParameterMögliche Werte
typg (Gerichtstermin) / o (Ortstermin) / a (Akteneinsicht)
beweisaufnahme0 (keine Bweisaufnahme) / 1 (absehbare Bweisaufnahme)
honorar-1 (offen) / 0 (streitwertbasiert) / 50 / 100 (siehe Konditionen)
zuschlag0-999 (ganze € Aufschlag zusätzlich zum Pauschalhonorar)
streitwert0-9999999 (ganze €)
tag1-31 (Tag des Termins)
monat1-12 (Monat des Termins)
jahr2018-2019 (Jahr des Termins)
stunde6-22 (Stunde des Termins)
minute0-59 (Minute des Termins)
d_taganalog 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
gericht3-3188 (Nummer des Gerichtes aus der Gerichtsliste)
plz"01067"-"99998" (statt Gericht, NUR für Ortstermine und Akteneinsichten)
dauerTextfeld, z.B. "nur 15min"
fachrichtungTextfeld, z.B. "Verkehrszivilrecht"
beschreibungTextfeld, z.B. "Forderung aus Warenverkauf"
azTextfeld für Aktenzeichen, z.B. "123/16 mü"
parteienTextfeld für beteiligte Parteien, z.B. "Müller ./. Meier"
anzahl1-99 (Anzahl Termine im Sammeltermin)
confirm0 (direkte Vergabe) / 1 (kontrollierte Vergabe)
bericht0 (klassischer Terminsbericht) / 1 (Textform per AdvoAssist)

Das Ergebnis dieses Abrufs ist ein JSON-Paket der nachfolgenden Struktur:

[result] => 'OK' (bzw. Fehlermeldung)
[  nr  ] => zugeteilte Nummer des ausgeschriebenen Termins

◊ "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
nrNummer des Termins
kanzleiKundennummer der gewählten Kanzlei

Das Ergebnis dieses Abrufs ist ein JSON-Paket der nachfolgenden Struktur:

[result] => 'OK' (bzw. Fehlermeldung)

◊ "absage": Terminabsage

Über diesen Endpunkt können Sie einen Termin absagen.
Der Aufruf beinhaltet neben dem Token folgende Parameter:

ParameterBeschreibung
nrNummer des Termins
grundTextfeld für eine kurze Begründung

Das Ergebnis dieses Abrufs ist ein JSON-Paket der nachfolgenden Struktur:

[result] => 'OK' (bzw. Fehlermeldung)

◊ "upload": Datei-Upload

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

ParameterBeschreibung
terminNummer des Termins
filenameName der Datei
base64Content (base64-encodiert) der Datei

Das Ergebnis dieses Abrufs ist ein JSON-Paket der nachfolgenden Struktur:

[result] => 'OK' (bzw. Fehlermeldung)

◊ "datei-entfernen": Datei-Löschung

Über diesen Endpunkt können Sie von Ihnen hochgeladene Dateien von einem Termin wieder löschen.
Der Aufruf beinhaltet neben dem Token folgende Parameter:

ParameterBeschreibung
terminNummer des Termins
filenameName der Datei

Das Ergebnis dieses Abrufs ist ein JSON-Paket der nachfolgenden Struktur:

[result] => 'OK' (bzw. Fehlermeldung)

◊ "bewertung": Terminsvertreter-Bewertung

Über diesen Endpunkt können Sie Vertreter vergangener Termine bewerten.
Der Aufruf beinhaltet neben dem Token folgende Parameter:

ParameterBeschreibung
terminNummer des Termins
sterneBewertung (1-5 Sterne)
kommentarKommentar (optionale Details zur Bewertung)

Das Ergebnis dieses Abrufs ist ein JSON-Paket der nachfolgenden Struktur:

[result] => 'OK' (bzw. Fehlermeldung)

◊ "berichte": Neue Terminsberichte

Ü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 außer dem Token kein Parameter.

Das Ergebnis dieses Abrufs ist ein JSON-Paket der nachfolgenden Struktur:

(
    [000780] => Alles gut gelaufen, Mandant hat kein Fahrverbot mehr
    [000781] => Widerruflichen Vergleich i.H.v. 2.000 € geschlossen, wie besprochen
)

◊ "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
nrNummer des Termins (6-stellig)

Das Ergebnis dieses Abrufs ist ein JSON-Paket der nachfolgenden Struktur:

[result] => 'OK' (bzw. Fehlermeldung)

◊ "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
nrNummer des Termins (6-stellig)

Das Ergebnis dieses Abrufs ist ein JSON-Paket der nachfolgenden Struktur:

(
    [az] => 343/12 Müller
    [Termin] => 2018-12-19 15:00:00
    [Deadline] => 2018-12-01 16:00:00
    [Gericht] => 2759
    [Wahrnehmer] => 13999
    [geloescht] => 0
    [abgesagt] => 0
    [Einstellzeit] => 2018-11-01 16:00:00
    [Annahmezeit] => 2018-11-02 16:00:00
    [Honorar] => 280
    [anzahl] => 1
    [opt_select] => 0
    [opt_confirm] => 1
)

◊ "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 einen optionalen Parameter:

ParameterBeschreibung
tageZeitraum (vergangene Tage)

Das Ergebnis dieses Abrufs ist ein JSON-Paket der nachfolgenden Struktur:

(
    [tage] => 28
    [insgesamt] => 600
    [erfolgreich] => 580
    [erfolglos] => 2
    [abgesagt] => 8
    [geloescht] => 10
)

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)

Das Ergebnis dieses Abrufs ist ein JSON-Paket der nachfolgenden Struktur:

[0] =>
(

    [0] => 13997
    [1] => 13998

)

[2] =>
(

    [0] => 13999

)

Hinweis: Das erste Array [0] (immer auf oberster Hierarchie betrachtet) beinhaltet die ausgeschlossenen Kanzleien, das Zweite [2] hingegen die Bevorzugten. Alle anderen Kanzleien werden automatisch nachrangig nach den Bevorzugten in Betracht gezogen.

Mit dem Parameter detail=1 ist die Ausgabe entsprechend ähnlich, aber umfangreicher:

[0] =>
(

    [0] =>
    (
        [Nr] => 13997
        [Name] => Prof. Dr. Volker Vertreter
        [Anschrift] => Musterstr. 1
        [PLZ] => 92345
        [Ort] => Pfenninghof
        [Telefon] => 012-34567
        [Fax] => 012-34567
        [Email] => demo@advo-assist.de
    )

    [1] =>
    (
        [Nr] => 13998
        [Name] => Dr. Carl Clever
        [Anschrift] => Musterstr. 1
        [PLZ] => 80333
        [Ort] => München
        [Telefon] => 012-34567
        [Fax] => 012-34567
        [Email] => demo@advo-assist.de
    )

)

[2] =>
(

    [0] =>
    (
        [Nr] => 13999
        [Name] => Oskar Offline
        [Anschrift] => Musterstr. 1
        [PLZ] => 40545
        [Ort] => Düsseldorf
        [Telefon] => 012-34567
        [Fax] => 012-34567
        [Email] => demo@advo-assist.de
    )

)

◊ "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
targetNummer der Kanzlei (5-stellig)
pref0 / 1 / 2 (0: Ausschluss, 1: normal, 2: Bevorzugung)

Das Ergebnis dieses Abrufs ist ein JSON-Paket der nachfolgenden Struktur:

[result] => 'OK' (bzw. Fehlermeldung)