Verwendung von Filter in Actaport

Aufbau der Filter

Filter werden als Query-Parameter geschickt. Der dafür verwendete Parameter heisst filter. Der Parameter kann mehrmals benutzt werden, um mehrere Filterkriterien mitzugeben.

Das Filter Kriterium wird wie folgt aufgebaut: operator(Feld, 'Wert'). Um beispielsweise auf den Namen (name) mit dem Wert Smith zu filtern: eq(name,'Smith')

Kombination von Filtern

Grundsätzlich sind alle Filter mit UND verknüpft. Nur wenn zwei Filter auf den selben Feld angewandt werden, werden diese mit ODER verknüpft. Die Anfrage mit den Filtern ?filter=eq(name, 'Müller')&filter=eq(vorname, 'Jan') bedeutet: gib mir alle Entitäten mit name Müller und vorname Jan. Hingegen bedeutet die Anfrage mit den Filtern ?filter=eq(name, 'Müller')&filter=eq(name, 'Schmidt'): gib mir alle Entitäten mit name Müller oder Schmidt.

Möglichen Operatoren

Folgende Operatoren sind möglich:

Operator Beschreibung Beispiel Bemerkung

eq

Filtert auf Werten die exakt gleich sind (equals)

eq(vorname,'Urs') um Kontakte mit dem Vornamen Urs zu filtern.

Ein Kontakt mit dem Vornamen Ursula ist nicht Teil der Antwort

ne

Filtert auf Werten die nicht gleich sind (not equals)

ne(vorname,'Urs') um Kontakte die nicht den Vornamen Urs haben zu filtern.

Ein Kontakt mit dem Vornamen Ursula ist Teil der Antwort

has

Filtert ob ein Wert vorhanden ist oder wahr

has(vorname) um Kontakte die einen Vornamen haben zu filtern

Bei Boolean Werte werden alle Elemente mit Wert true gefiltert

hasNot

Filtert ob ein Wert nicht vorhanden ist oder falsch

hasNot(vorname) um Kontakte die keinen Vornamen haben zu filtern

Bei Boolean Werte werden alle Elemente mit Wert false gefiltert

startsWith

Filtert wie ein Wert anfängt

startsWith(vorname,'Urs') liefert alle Kontakte, die einen Vorname was mit Urs anfängt haben

Liefert sowohl Kontakte mit Vorname Urs und Ursula

contains

Filtert ob ein Wert eine bestimmte Zeichenkette enthält

contains(name, 'GmbH') liefert alle Kontakte deren Name GmbH enthält

Liefert Kontakte mit Name, Gmbh, dokSAFE GmbH, X Gmbh & Co kg

containsNot

Filtert ob ein Wert eine bestimmte Zeichenkette nicht enthält

containsNot(name, 'GmbH') liefert alle Kontakte deren Name GmbH nicht enthält

Filterbare Endpunkte

Liste der Endpunkte wo Filter angewendet werden können:

  • GET /v1/kontakte

  • GET /v1/akten

  • GET /v1/rechnungen

Kontakte

Folgende Werte von Kontakten sind filterbar

  • vorname contains(vorname,'Jan')

  • name contains(name, 'Müller')

  • ort (auf die postalische Adresse angewandt) eq(ort, 'Leipzig')

  • postleitzahl (auf die postalische Adresse angewandt) eq(postleizahl, '04109')

  • personTyp eq(personTyp, 'JURISTISCHE_PERSON')

Akte

Folgende Werte von Akten sind filterbar

  • alternativesAktenzeichen eq(alternativesAktenzeichen,'Aktenzeichen')

  • sachbearbeiter eq(sachbearbeiter, '{uuid des Sachbearbeiters}')

  • assistenzen in(assistenzen, '{uuid des Assistant}')

  • rechtsgebiete in(rechtsgebiete, 'Strafrecht')

  • schlagworte in(schlagworte, 'Tag1')

  • status eq(status, 'AKTIV')

Beispiele

https://app.actaport.de/v1/kontakte?filter=contains(name,%27Müller%27)&filter=contains(vorname,%27Jan%27)

https://app.actaport.de/v1/kontakte?filter=startsWith(name,%27M%27)

Actaport API - Authentifizierung

Die Authentifizierung an der Actaport API basiert auf Openid Connect. An der Stelle wird der Client Direct FLow verwendet. Dies bedeutet, dass Sowohl einen Client und einen Benutzer in einer Anfrage authentifiziert werden.

Anfrage zum Auhtentifizieren

Die Anfrage erfolgt als url-form-data. Folgende Parameter werden benötigt:

Name Beschreibung

client_id

Die Id des benutzten Clients

client_secret

Das Passwort für den Client

grant_type

Definiert wie der Benutzer authentifiziert wird, hier muss immer password stehen.

username

Benutzer der Authentifiziert wird, hier wird die Emailadresse verwendet.

password

Passwort des Benutzers

Die Anfrage soll als POST-Anfrage an die Url https://app.actaport.de/auth/realms/<tenant>/protocol/openid-connect/token.

cURL Beispiel
curl --location 'https://app.actaport.de/auth/realms/<tenant>/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Accept: application/json' \
--data-urlencode 'client_id=<clientId>' \
--data-urlencode 'client_secret=<clientSecret>' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'password=<Password>' \
--data-urlencode 'username=<Email>'
Antwort
{
    "access_token": "<accessToken>",
    "expires_in": 300,
    "refresh_expires_in": 10800,
    "refresh_token": "<refreshToken>",
    "token_type": "Bearer",
    "not-before-policy": 1651569000,
    "session_state": "01385398-6126-477e-a892-63d76ab9dcee",
    "scope": "profile email"
}

Die Property access_token enthält den gerbauchten Token.

Der AccessToken ist 5 Minuten gültig. Einen neuen Token kann über den vorher beschriebenen Verfahren erzeugt werden oder über den refreshToken mit folgenden Anfrage.

cURL
curl --location 'https://app.actaport.de/auth/realms/<tenant>/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Accept: application/json' \
--data-urlencode 'client_id=<clientId>' \
--data-urlencode 'client_secret=<clientSecret>' \
--data-urlencode 'grant_type=refresh_token' \
--data-urlencode 'refresh_token=<refreshToken>'

Benutzen des Access-Tokens

Bei jede weitere Anfrage muss der AccessToken mitgegeben werden. Das passiert über dem Header Authentication der als Wert Bearer <accessToken> bekommt.

cURL Beispiel
curl --location 'https://app.actaport.de/v1/benutzer' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <accessToken>'