Ich arbeite seit über 8 Jahren mit der Weclapp API. In dieser Zeit habe ich hunderte Requests geschrieben, dutzende Integrationen gebaut und so ziemlich jeden Endpoint kennengelernt — inklusive der undokumentierten Eigenheiten. Hier eine ehrliche Bestandsaufnahme: was die API gut kann, wo sie nervt und welche Tipps ich mir gewünscht hätte, als ich angefangen habe.
Was die API gut kann
Fangen wir mit dem Positiven an — und davon gibt es einiges. Die Weclapp API deckt praktisch alle wichtigen Geschäftsobjekte ab: Artikel, Kunden, Lieferanten, Aufträge, Rechnungen, Lieferscheine, Lagerbestände und mehr. Für jede dieser Entitäten stehen vollständige CRUD-Operationen zur Verfügung — Erstellen, Lesen, Aktualisieren, Löschen.
Die Filter-Syntax in der API v2 ist bemerkenswert mächtig. Sie können mit Operatoren wie eq, ne, like, gt, lt, ge, le arbeiten und diese kombinieren. Das ermöglicht präzise Abfragen direkt an der API, ohne grosse Datenmengen laden und lokal filtern zu müssen.
Die Pagination funktioniert zuverlässig — was nicht selbstverständlich ist. Bei vielen APIs erlebt man Duplikate oder übersprungene Datensätze wenn sich die Daten während des Paginierens ändern. Bei Weclapp hatte ich damit in der Praxis selten Probleme.
Ausserdem liefert die API immer Echtzeit-Daten. Es gibt kein Caching-Layer das veraltete Daten ausgibt. Wenn Sie einen Datensatz über die API ändern und sofort wieder abrufen, sehen Sie die aktualisierte Version.
Was sich mit v2 geändert hat
Der Wechsel von API v1 zu v2 brachte einige wichtige Verbesserungen — aber auch Breaking Changes, die bestehende Integrationen betreffen.
Die grösste Verbesserung ist ignoreMissingProperties. In v1 musste man bei einem Update alle Felder eines Objekts mitschicken — auch die, die man nicht ändern wollte. Fehlte ein Feld, wurde es auf null gesetzt. Das war nicht nur umständlich, sondern gefährlich. In v2 mit ignoreMissingProperties=true senden Sie nur die Felder die Sie ändern wollen. Alles andere bleibt unberührt. Das ist ein echter Gamechanger für die Zuverlässigkeit von Integrationen.
Die Filter-Syntax wurde ebenfalls modernisiert. In v1 wurden Filter teilweise im Request-Body übergeben, in v2 als Query-Parameter. Das macht die API-Aufrufe lesbarer und einfacher zu debuggen — man sieht die Filter direkt in der URL.
Fehlermeldungen wurden verbessert. In v1 bekam man manchmal kryptische Responses. V2 gibt in den meisten Fällen verständliche Fehlertexte zurück, die tatsächlich bei der Fehlersuche helfen.
Allerdings gab es auch Breaking Changes: Manche Feldnamen wurden geändert, Response-Strukturen angepasst, und einige Endpoints verhalten sich anders. Wer von v1 auf v2 migriert, muss seine Integrationen sorgfältig prüfen.
Die grössten Stolperfallen
Und jetzt zum Teil, der mir über die Jahre die meisten Nerven gekostet hat.
Optimistic Locking: Jedes Objekt in Weclapp hat ein version-Feld. Bei jedem Update muss die aktuelle Version mitgeschickt werden. Stimmt die Version nicht überein — weil jemand anderes das Objekt zwischenzeitlich geändert hat — schlägt der Request fehl. Das ist im Prinzip ein gutes Konzept, um konkurrierende Änderungen zu verhindern. In der Praxis bedeutet es aber: Sie müssen den Datensatz immer zuerst lesen, die aktuelle Version holen und dann erst updaten. Bei Massenoperationen kann das zu einer Kaskade von Fehlern führen, wenn zwischen dem Lesen und dem Schreiben ein anderer Prozess — oder ein Benutzer in der Oberfläche — etwas ändert.
Rate Limiting: Bei vielen gleichzeitigen Requests greift das Rate Limiting. Die genauen Limits sind nicht immer transparent dokumentiert und können je nach Tarif variieren. In der Praxis heisst das: Bei Massenimporten oder Synchronisationen müssen Sie Pausen einbauen und mit Retry-Logik arbeiten.
Custom Attributes: Weclapp erlaubt benutzerdefinierte Felder — sogenannte Custom Attributes. Diese sind mächtig, aber die Zuordnung funktioniert über interne IDs statt über sprechende Namen. Das bedeutet: Sie müssen zuerst die ID eines Custom Attributes herausfinden, bevor Sie es lesen oder schreiben können. Und diese IDs können sich zwischen Instanzen unterscheiden.
Schreibgeschützte Felder: Manche Felder die in der Weclapp-Oberfläche editierbar sind, lassen sich über die API nicht ändern. Das ist nicht immer sofort ersichtlich und führt zu Frustration, wenn man eine Integration baut und erst spät merkt, dass ein bestimmtes Feld über die API nur lesbar ist.
Meine wichtigsten Tipps
Aus 8 Jahren Erfahrung habe ich eine Handvoll Regeln destilliert, die mir viel Ärger erspart hätten, wenn ich sie von Anfang an gekannt hätte:
- Immer
ignoreMissingProperties=truenutzen. Ausnahmslos. Es gibt keinen guten Grund, das nicht zu tun. Es schützt Sie davor, versehentlich Felder zu überschreiben. - Das
version-Feld bei Updates nie vergessen. Bauen Sie Ihre Logik so, dass Sie immer zuerst lesen, dann schreiben. Und implementieren Sie Retry-Logik für den Fall, dass die Version zwischenzeitlich geändert wurde. - Bei Massenoperationen: Batches mit kurzen Pausen. Schicken Sie nicht 500 Requests auf einmal. Arbeiten Sie in Batches von 10–20 Requests mit einer kurzen Pause dazwischen. Das vermeidet Rate-Limiting-Fehler und schont die API.
- Error-Handling von Anfang an einbauen. Die API gibt in den meisten Fällen gute Fehlermeldungen zurück. Loggen Sie diese. Bauen Sie Alerts ein. Ich habe zu oft erlebt, dass eine Integration wochenlang still fehlschlug, weil niemand die Fehler mitbekam.
- Custom Attributes: IDs einmal sauber dokumentieren. Legen Sie eine Mapping-Tabelle an, die Custom-Attribute-Namen ihren IDs zuordnet. Das spart Ihnen bei jeder neuen Integration Stunden.
Was die API nicht kann
Kein System ist perfekt, und die Weclapp API hat klare Grenzen.
Keine Webhooks: Weclapp bietet keine nativen Webhooks. Wenn Sie auf Änderungen reagieren wollen — etwa "wenn ein neuer Auftrag erstellt wird, starte einen Workflow" — müssen Sie pollen. Das heisst: regelmässig die API abfragen und prüfen, ob sich etwas geändert hat. Das funktioniert, ist aber weniger elegant und weniger echtzeitnah als Webhooks.
Keine Echtzeit-Events: Eng verwandt mit dem Webhook-Problem. Es gibt keinen Event-Stream oder WebSocket-Endpunkt. Für Anwendungsfälle die Echtzeit erfordern, muss man kreativ werden — etwa mit sehr kurzen Polling-Intervallen oder mit der Weclapp-Oberfläche als Trigger über Custom Actions.
Statusübergänge: Manche Business-Logik, die in der Oberfläche einfach per Klick funktioniert — etwa das Ändern eines Auftragsstatus von "Offen" auf "In Bearbeitung" — ist über die API nicht immer vollständig abbildbar. Manchmal muss man Umwege gehen oder spezifische Endpoints nutzen, die nicht offensichtlich dokumentiert sind.
Dokumentation: Die offizielle Dokumentation deckt die Standardfälle ab, lässt aber bei Spezialfällen Lücken. Für Edge Cases — und davon gibt es viele in der echten Welt — bleibt oft nur Trial and Error.
Fazit
Die Weclapp API ist solide. Sie ist keine perfekte API, aber sie ist vollständig genug für die allermeisten Automatisierungen die ein KMU braucht. Wer die Eigenheiten kennt — Optimistic Locking, Rate Limiting, Custom Attributes — kann damit fast alles bauen, was das Standard-ERP nicht hergibt.
Mein Rat: Investieren Sie am Anfang Zeit in eine saubere Grundstruktur. Error-Handling, Logging, Retry-Logik, eine Mapping-Dokumentation für Custom Attributes. Das kostet ein paar Stunden mehr zu Beginn, spart aber Wochen an Debugging später.
Und wenn Sie vor einem konkreten API-Problem stehen und nicht weiterkommen — ich habe die meisten Stolperfallen schon gesehen.