WERBAS REST API — Suchparameter q

Dieses Dokument beschreibt, wie der q-Parameter der WERBAS REST API für die Endpunkte GET /vehicle und GET /workorder verwendet wird.

Kurzübersicht

Alle Parameter sind optional. Wird q weggelassen, liefert der Endpunkt alle verfügbaren Datensätze (paginiert gemäß limit/skip).

Alle Abfrageparameter

Wichtig: Der q-Parameter funktioniert nur in Kombination mit einem positiven limit. Bei limit=0 oder einem negativen Wert wird q ignoriert oder die Anfrage schlägt mit einem Fehler fehl — je nach Endpunkt. Wird limit weggelassen, gilt der Default 10 und q funktioniert korrekt. limit immer auf einen positiven Wert setzen.

Wie funktioniert q?

Der Wert von q kann aus zwei Teilen bestehen, die beliebig kombiniert werden können:

1. Freitext — Suche über viele Felder gleichzeitig
2. Gezielte Feldsuche — Suche auf einem bestimmten Feld mit optionalem Vergleichsoperator

Mehrere Suchbedingungen werden durch Komma (,) getrennt. Alle Bedingungen müssen zutreffen (AND-Verknüpfung).

1. Freitextsuche

Ein Suchbegriff ohne : wird als Freitext über viele Felder des Datensatzes gesucht. Mehrere Wörter können angegeben werden — alle müssen vorkommen.

Felder der Freitextsuche bei /vehicle

Felder der Freitextsuche bei /workorder

Nicht in der Freitextsuche enthalten: Telefonnummer/PLZ des Kunden, Auftragspositionstexte, Arbeitsgänge, Artikel.

Beispiele Freitextsuche

# Fahrzeuge, bei denen "Mustermann" vorkommt (Halter, Bemerkung, etc.) — erste 25 Treffer
GET /vehicle?limit=25&q=Mustermann

# Aufträge mit "BMW" (im Fahrzeug, in Bemerkungen, etc.) — erste 25 Treffer
GET /workorder?limit=25&q=BMW

# Aufträge mit "Mustermann" UND "Golf" (beide Begriffe müssen vorkommen)
GET /workorder?limit=25&q=Mustermann,Golf

2. Gezielte Feldsuche

Mit der Syntax feldname:wert wird gezielt auf einem bestimmten Feld gesucht.

q=feldname:wert
q=feldname:[operator]wert

Vergleichsoperatoren

Mehrere erlaubte Werte (IN-Liste)

Mehrere Werte, von denen einer zutreffen soll, werden mit | (Pipe-Zeichen) getrennt:

q=feldname:wert1|wert2|wert3

Besonderheiten bei Datumsfeldern

Bei Datumsfeldern sucht eine einfache Gleichheitsangabe automatisch nach dem gesamten Tag (unabhängig von der Uhrzeit).

Besonderheit: Wert 0

Bei Nicht-Datumsfeldern schließt der Wert 0 auch Datensätze ein, bei denen das Feld leer ist.

Durchsuchbare Felder

/vehicle — Fahrzeuge

/workorder — Aufträge

Sonderzeichen im Suchwert

Einige Zeichen haben in URLs eine besondere Bedeutung und müssen durch Platzhalter ersetzt werden:

Sortierung

Der sort-Parameter akzeptiert denselben Feldnamen wie q. Ein vorangestelltes ! kehrt die Sortierreihenfolge um (absteigend).

# Aufträge nach Fertigstellungsdatum absteigend
GET /workorder?sort=!workorder.pickUpDateTime

# Fahrzeuge nach Marke aufsteigend
GET /vehicle?sort=vehicle.brand

Vollständige Beispiele

Fahrzeugsuche

# BMW mit Erstzulassung ab 2020 — erste 25 Treffer
GET /vehicle?limit=25&q=vehicle.brand:BMW,vehicle.dateOfFirstRegistration:>=2020-01-01

# Fahrzeuge mit Kennzeichen, das mit "M-" beginnt
GET /vehicle?limit=25&q=vehicle.registration:M-*

# Fahrzeuge nach Fahrgestellnummer
GET /vehicle?limit=25&q=vehicle.vin:WBA12345678901234

# Auch inaktive Fahrzeuge einschließen
GET /vehicle?limit=25&q=vehicle.brand:BMW&showinactive=true

# Paging: zweite Seite mit je 25 Ergebnissen, sortiert nach Marke
GET /vehicle?limit=25&skip=25&sort=vehicle.brand&q=vehicle.brand:BMW

Auftragssuche

# Offene Aufträge für Kunden "Mustermann"
GET /workorder?limit=25&q=workorder.contact.familyName:Mustermann

# Aufträge im Status "AIA" oder "STO"
GET /workorder?limit=25&q=workorder.workorderStatus:AIA|STO

# Aufträge, die heute fertiggestellt werden sollen
GET /workorder?limit=25&q=workorder.pickUpDateTime:today

# Aufträge der letzten 30 Tage, neueste zuerst
GET /workorder?limit=25&sort=!workorder.createdAt&q=workorder.createdAt:>=today-30

# Aufträge für ein bestimmtes Fahrzeug per Kennzeichen
GET /workorder?limit=25&q=workorder.vehicle.registration:M-AB1234

# Kombination: Aufträge für Kunden "Mustermann" mit BMW, Status nicht "STO"
GET /workorder?limit=25&q=workorder.contact.familyName:Mustermann,workorder.vehicle.brand:BMW,workorder.workorderStatus:!=STO

# Freitext: Aufträge, bei denen irgendwo "Inspektion" vorkommt
GET /workorder?limit=25&q=Inspektion

# Auftragsnummer größer gleich 10000, nach Nummer sortiert, 50 Treffer
GET /workorder?limit=50&sort=workorder.workorderid&q=workorder.workorderid:>=10000

Häufige Fragen

Was passiert bei einem unbekannten Feldnamen?
Der Filter wird stillschweigend ignoriert — es gibt keinen Fehler.

Was passiert, wenn ich bei einem Zahlenfeld einen ungültigen Wert übergebe?
Die API antwortet mit HTTP 400 (Bad Request).

Muss limit gesetzt sein, damit q funktioniert?
Ja. Der q-Filter greift nur bei limit > 0. Wird limit weggelassen, gilt automatisch der Default 10 — q funktioniert dann korrekt. Wer limit explizit auf 0 oder negativ setzt, um alle Datensätze auf einmal abzurufen, erhält je nach Endpunkt entweder keine Filterung (q wird ignoriert) oder einen Serverfehler. limit deshalb immer auf einen positiven Wert setzen.

Liefert /workorder auch abgeschlossene Aufträge?
Nein. Der Endpunkt liefert ausschließlich offene Aufträge, unabhängig von den Suchparametern.

Wie erhalte ich inaktive Fahrzeuge?
Mit &showinactive=true. Ohne diesen Parameter werden nur aktive Fahrzeuge zurückgegeben.