weclapp API filtern: Operatoren, Felder, Seiten und die drei stillen Fallen
Kurz gesagt: Du filterst die weclapp API mit Suffix-Parametern wie eq, ge oder in, begrenzt die Felder mit properties und blätterst sortiert mit page und pageSize. Gib jedem neuen Filter eine Zählprobe mit /count, denn ein unbekanntes Filterfeld ignoriert die API still und liefert die volle Menge.
Dieser Teil der API-Reihe von wals.pro (Überblick im Hub zur weclapp API) richtet sich an alle, die Daten aus weclapp lesen: in Skripten, in n8n oder in einer eigenen Integration. Wie du ein Token erzeugst und den ersten Request schickst, steht in Kapitel 1. Hier geht es darum, nur die Datensätze und Felder abzufragen, die du brauchst, und zu merken, wenn ein Filter nicht wirkt.
Das Wichtigste in Kürze
-
Ein Filterparameter besteht aus Feldname, Minus und Operator. Mehrere Parameter sind UND-verknüpft, ODER bekommst du mit dem Präfix
or-oder mit benannten Gruppen. -
Datumsfelder filterst du mit Epoch-Millisekunden. Mit dem
filter-Ausdruck geht auch ein ISO-Zeitpunkt, dann aber mit Zeitzone. -
Ohne
propertieskommt das ganze Schema zurück. MitincludeReferencedEntitiesholst du verknüpfte Datensätze in derselben Antwort. -
Drei stille Fallen führen zu falschen Mengen ohne Fehlermeldung. Gegen alle drei hilft derselbe Test: Trefferzahl mit
/countprüfen und die Grenze verschieben.
Wie filterst du mit Suffix-Parametern?

Ein Filter ist ein Query-Parameter nach dem Muster feld-operator=wert, zum Beispiel customerSalesChannel-eq=NET1 an der Ressource /party. Mehrere Filterparameter in einer Anfrage gelten zusammen (UND). Die Spezifikation kennt 14 Operatoren, nicht jeder passt zu jedem Datentyp:
| Operator | Bedeutung |
|---|---|
eq, ne
|
gleich, ungleich |
lt, gt
|
kleiner, größer |
le, ge
|
kleiner gleich, größer gleich |
null, notnull
|
Feld ist leer, Feld ist gefüllt (der Parameterwert wird ignoriert) |
like, notlike
|
Textmuster mit % und _
|
ilike, notilike
|
wie like, aber ohne Unterscheidung von Groß- und Kleinschreibung |
in, notin
|
Wert ist (nicht) in einer Liste, übergeben als JSON-Array |
Bei in kodierst du das Array nicht von Hand. Mit curl --get --data-urlencode übernimmt curl das Kodieren, so wie es auch die Spezifikation in ihren Beispielen macht:
curl --compressed --get "https://<TENANT>.weclapp.com/webapp/api/v2/party" \
-H "AuthenticationToken: <TOKEN>" \
-H "Accept: application/json" \
--data-urlencode 'customerNumber-in=["1006","1007"]' \
--data-urlencode 'properties=id,customerNumber'
Für ODER stellst du dem Parameter or- voran. ?or-lastName-eq=Meier&or-lastName-eq=Schulz liefert Datensätze, auf die eine der beiden Bedingungen passt. Mit Gruppen wie orGroup1-lastName-eq=Meier und orGroup2-responsibleUserId-eq=4567 bildest du mehrere ODER-Blöcke. Die Blöcke untereinander sind UND-verknüpft, or- ist die Gruppe mit leerem Namen.
Fazit: Suffix-Filter sind der Standardweg, und für Listen und Alternativen reichen in und or-.
Wann nimmst du den filter-Ausdruck?
Der Parameter filter nimmt einen ganzen Ausdruck. Die Spezifikation führt ihn selbst als noch nicht endgültig festgeschrieben, plane deshalb mit Änderungen. Du kannst den Parameter mehrfach angeben, die Ausdrücke gelten zusammen mit allen Suffix-Parametern (UND). Verfügbar sind unter anderem diese Bausteine:
- Rechnen und Vergleichen:
+ - * /sowie=,!=,<,>,<=,>=,~,in,contains,null,empty - Logik:
and,or,not - Funktionen:
trim,length,lower - Bedingungen mit dem ternären Operator
? :(laut API-Changelog seit 26.03.1 vom 12.02.2026)
curl --compressed --get "https://<TENANT>.weclapp.com/webapp/api/v2/party" \
-H "AuthenticationToken: <TOKEN>" \
--data-urlencode 'filter=(lower(lastName) = "müller") and (lastModifiedDate >= "2022-01-01T00:00:00Z")'
Der Ausdruck deckt auch ab, was Suffix-Filter nicht können. Ein Beispiel sind Tags: not (tags contains "standard") findet Datensätze ohne dieses Tag, tags empty die ohne jedes Tag. Das Changelog nennt diese Schreibweise unter 26.09.1 (07.05.2026) ausdrücklich nur für Tags. Ein allgemeines „enthält nicht“ ist damit nicht gemeint.
Beim Datum richtet sich die Auslegung nach dem Literal: Ein Integer wird als Epoch-Millisekunden gelesen, ein String als ISO-8601-Zeitpunkt mit Pflicht-Zeitzone, etwa 2024-10-13T10:39:12+02:00 oder mit Z. Seit 26.05.1 (12.03.2026) werden String-Literale als JSON-Strings gelesen, Anführungszeichen und Sonderzeichen maskierst du also nach JSON-Regeln.
Fazit: Nimm den Ausdruck für Verneinung, Tags und Bedingungen, und bleib für einfache Filter bei den Suffix-Parametern.
Wie filterst du Datum und Zusatzfelder?
Im Suffix-Filter steht bei Datumsfeldern eine Zahl: Epoch-Millisekunden, wie im Beispiel der Spezifikation createdDate-gt=1398436281262. Aus unseren Projekten kommt eine Regel dazu, die in der Spezifikation nicht steht: Wir rechnen Tagesgrenzen auf Berlin-Mitternacht und fragen halboffen ab. Für Oktober 2026 sieht das so aus:
orderDate-ge=1790805600000&orderDate-lt=1793487600000
Die erste Zahl ist der 1. Oktober 2026, die zweite der 1. November 2026, jeweils 0 Uhr in Berlin. Mische nicht Berlin-Grenzen und UTC-Grenzen in einem Projekt, sonst wandern Datensätze um einen Tag. Die Details zu Datumsfeldern und Zahlentypen findest du in Datum, Zahlen und Zusatzfelder.
Zusatzfelder filterst du über ihren Schlüssel mit der Definitions-ID des Mandanten, zum Beispiel customAttribute4587-eq=NEW. Bei Auswahllisten hängst du .value oder .id an, bei Referenzen .entityReferences.entityId. Die Definitionen liest du über GET /customAttributeDefinition. Die Zahl im Schlüssel unterscheidet sich von Mandant zu Mandant, lies sie aus den Definitionen und schreib sie nicht fest in den Code.
Fazit: Datum ist eine Zahl in Millisekunden, und die Tagesgrenzen rechnest du einmal sauber auf Berlin-Zeit.
Wie begrenzt du Felder und holst verknüpfte Daten?
Mit properties nennst du die Felder, die du brauchst, durch Kommas getrennt. Tiefere Ebenen gibst du als Pfad an, ein Beispiel aus der Spezifikation: /party?properties=id,customerNumber,contacts.id,contacts.lastName. Die Antwort hat die Form {"result":[…]} und enthält nur diese Felder.
Mit includeReferencedEntities löst du ID-Felder in vollständige Datensätze auf, ohne pro Zeile einen Einzelabruf zu schicken. includeReferencedEntities=unitId,articleCategoryId ergänzt die Antwort um ein Objekt referencedEntities. Aus unseren Projekten: Nimm für referenzierte Felder den Doppelpunkt (unit:name), nicht den Punkt.
additionalProperties liefert berechnete Werte, zum Beispiel additionalProperties=currentSalesPrice. Sie stehen in einem eigenen Block der Antwort, und die Position im Array entspricht der Position in result. Führe beide Teile also pro Seite über den Index zusammen.
Fazit: Frag mit properties nur Felder ab, die du verarbeitest, und hol Verknüpftes in derselben Antwort.
Wie sortierst und blätterst du richtig?
Mit sort=lastModifiedDate sortierst du aufsteigend, mit sort=-lastModifiedDate absteigend, mehrere Felder trennst du mit Komma. Der neuere Parameter orderBy nimmt Ausdrücke wie length(trim(lastName)) desc, firstName asc (laut Spezifikation ebenfalls noch nicht festgeschrieben). Du darfst nur einen der beiden Parameter angeben, sonst antwortet die API mit einem Fehler. Ein unbekanntes Sortierfeld führt ebenfalls zu einer Fehlerantwort.
Eine Liste liefert standardmäßig 100 Einträge. pageSize ist laut Spezifikation meist auf 1000 begrenzt, einzelne Ressourcen weichen ab. page zählt ab 1, zusätzlich gibt es seit Changelog 26.20.1 (05.11.2026) den Parameter offset. Beides ist Offset-Paging und liefert keinen Schnappschuss: Ändert sich ein Datensatz während des Blätterns, kann er über eine Seitengrenze rutschen. Sortiere deshalb immer, etwa mit sort=id. Als Abbruchbedingung nutzen wir eine Seite mit weniger Zeilen als pageSize.
Die Menge vorab liefert GET /party/count mit denselben Filtern, zum Beispiel /party/count?customerSalesChannel-eq=NET1. Die Antwort ist ein Objekt mit dem Feld result. Seit 26.20.1 gibt es für alle regulären Entitäten zusätzlich POST /<entity>/query, auch Count geht per POST. Laut Spezifikation hat POST weniger Einschränkungen als GET, empfohlen wird dort der filter-Ausdruck im Body. Wie das in der Praxis aussieht, zeigt der Artikel zu POST /query.
Fazit: Sortiere jede paginierte Abfrage, und zähl vorher, wie viele Datensätze dich erwarten.
Welche drei stillen Fallen kosten dich am meisten Zeit?

Alle drei liefern eine Antwort mit Status 200 und sehen auf den ersten Blick richtig aus. Mehr zu dieser Fehlerklasse steht in Stille Fehler in der weclapp API.
| Falle | Was passiert | Gegenprobe |
|---|---|---|
| Unbekanntes Filterfeld | Die Spezifikation schreibt, dass solche Filter still ignoriert werden. Du bekommst die volle Menge. | Feldnamen gegen die Spezifikation prüfen, Trefferzahl mit /count vergleichen |
| Datum als ISO-Text im Suffix-Filter | Die Spezifikation zeigt im Suffix-Filter nur Epoch-Werte. Aus unseren Projekten: Wir setzen dort nie ISO-Text ein, sondern ausschließlich Epoch-Millisekunden. | Epoch-Wert einsetzen, Grenze um einen Tag verschieben, Zahl vergleichen |
| Suffix-Filter und filter-Ausdruck in einem Parameter gemischt | Mische die beiden Schreibweisen nicht in einem Ausdruck. In unseren Projekten hat das nicht zuverlässig funktioniert. Im Ausdruck heißt es not (customerNumber null). |
Pro Parameter eine Syntax, Ergebnis in beiden Schreibweisen gegenzählen |
Die Gegenprobe ist bei allen dreien dieselbe: Du zählst die Gesamtmenge, zählst mit Filter und verschiebst dann die Grenze. Ändert sich die Zahl nicht, wirkt der Filter nicht.
count() {
curl -s --compressed --get "https://<TENANT>.weclapp.com/webapp/api/v2/$1/count" \
-H "AuthenticationToken: <TOKEN>" "${@:2}" | jq .result
}
count salesOrder
count salesOrder --data-urlencode 'orderDate-ge=1790805600000'
count salesOrder --data-urlencode 'orderDate-ge=1793487600000'
Die zweite Zahl muss kleiner sein als die erste, die dritte kleiner als die zweite. Ein Tippfehler im Feldnamen liefert keinen Fehler, sondern je nach Fall die ungefilterte oder eine leere Menge. Prüfe das Ergebnis mit /count. Die Kundennummer filterst du an /party mit customerNumber. Wenn eine Abfrage null Zeilen zurückgibt, prüfe zuerst den Filter und dann die Daten. Unbekannte Felder in properties sind dagegen kein stiller Fall, sie führen zu einem Fehler.
Fazit: Jede neue Abfrage bekommt eine Zählprobe mit verschobener Grenze, bevor sie in den Dauerbetrieb geht.
Wie liest du große Mengen?
Bei großen Mengen lohnt sich ein zweistufiges Muster: Erst holst du nur die IDs mit properties=id, dann lädst du die Daten in Paketen mit id-in. So ist jeder Request kurz, und ein Fehler trifft ein Paket statt den ganzen Lauf. Prüfe bei jedem Paket, dass die zurückgegebenen IDs zur Anfrage passen, denn ein wirkungsloser Filter fällt so sofort auf. Wie du Pakete, Wartezeiten und Wiederholungen steuerst, beschreibt 429, Backoff und Timeouts. Wer Änderungen laufend braucht, liest besser nur das Delta: Webhooks und Delta-Sync. Fertige Requests zum Nachbauen enthält die Postman Collection 4 weclapp.
Fazit: Erst IDs, dann Pakete, und jedes Paket gegen die angefragten IDs prüfen.
Quellen und Grenzen
- weclapp OpenAPI-Spezifikation v2, Abschnitte Filtering, Or condition filtering, Filter Expressions, Ordering Expressions, Pagination, Counting, Querying, Return only specific properties, Referenced entities, Additional properties: https://www.weclapp.com/api/openapi_v2.yaml, abgerufen am 15.11.2026.
- weclapp API-Changelog (Einträge 26.03.1, 26.05.1, 26.09.1, 26.20.1): https://doc.weclapp.com/api-changelog/, abgerufen am 15.11.2026.
Aussagen mit „aus unseren Projekten“ beruhen auf Erfahrung von wals.pro im Dauerbetrieb und stehen nicht in der Spezifikation. Der Artikel zeigt nicht die Body-Form von POST /<entity>/query, nicht die Antwortzeiten verschiedener Abfragen und keine Richtwerte für Paketgrößen oder parallele Abrufe, weil wir sie nicht belegt haben. Teste Beispiele in einem Testmandanten, nicht im Produktivsystem. Stand: 15. November 2026.
Häufige Fragen
Warum liefert mein weclapp-Filter plötzlich alle Datensätze?
Laut Spezifikation werden Filter auf unbekannte oder nicht filterbare Felder still ignoriert. Prüfe den Feldnamen gegen die Spezifikation und vergleiche die Trefferzahl mit /count.
Wie kombiniere ich ODER-Bedingungen in der weclapp API?
Setze or- vor den Parameternamen, zum Beispiel or-lastName-eq=Meier&or-lastName-eq=Schulz. Für mehrere ODER-Blöcke nutzt du Gruppen wie orGroup1- und orGroup2-, die untereinander UND-verknüpft sind.
Wie filtere ich ein Datum in der weclapp API?
Im Suffix-Filter mit Epoch-Millisekunden, zum Beispiel createdDate-gt=1398436281262. Im filter-Ausdruck geht auch ein ISO-8601-String mit Zeitzone.
Wie viele Datensätze liefert eine Seite maximal?
Standard sind 100. pageSize ist laut Spezifikation meist auf 1000 begrenzt, einzelne Ressourcen können abweichen.
Seit wann gibt es POST /query für alle Entitäten?
Laut API-Changelog seit Version 26.20.1 vom 05.11.2026. Dort kamen auch der Parameter offset und Count per POST dazu.