Wofür taugt die weclapp-API?
Die weclapp-API taugt für fast alles, was über die Oberfläche von weclapp hinausgehen soll: eigene Ansichten und Erweiterungen, die Anbindung anderer Systeme, automatische Datenerfassung und Auswertungen. Sie ist eine REST-Schnittstelle, die Daten im JSON-Format austauscht. Jeder weclapp-Mandant hat seine eigene Adresse nach dem Muster https://<mandant>.weclapp.com/webapp/api/v2/, und jede Anfrage wird mit dem persönlichen API-Token eines Benutzers im Kopfzeilenfeld AuthenticationToken angemeldet.
Laut offizieller Dokumentation ist v2 die aktuelle Version der API; eine ältere Version bleibt nach Erscheinen einer neuen mindestens ein Jahr verfügbar (weclapp-API-Dokumentation). Typische Einsatzfelder sind:
| Einsatz | Beispiel | Zugriff |
|---|---|---|
| Zusätzliche Ansichten | Kundenakte mit Angeboten, Rechnungen und Aufgaben auf einen Blick | nur lesen |
| Auswertungen | Welche Module und Datensätze ein Mandant tatsächlich nutzt | nur lesen |
| Datenerfassung | Gesprächsnotiz als CRM-Ereignis mit Aufgabe und Wiedervorlage | schreiben |
| Anbindung anderer Systeme | Onlineshop, Konfigurator oder App übergibt Aufträge an weclapp | lesen und schreiben |
| Abrechnung | Rechnungen aus einem Fachsystem anlegen und buchen | schreiben |
Unsere Erfahrungen stammen aus eigenen weclapp-Erweiterungen: einer Kundenakte als Browser-Erweiterung, die ausschließlich liest, einem Werkzeug, das den Nutzungsumfang eines Mandanten ausliest, und einem Sprachassistenten, den wir als lauffähige Demo gebaut haben. Die folgenden Stolperfallen haben wir im September 2026 an einem laufenden weclapp-Mandanten geprüft und mit der offiziellen API-Beschreibung abgeglichen. Unsere Tests liefen gegen die API-Version v1. Die Felder und Werte aus den Stolperfallen 3 bis 5 stehen in den offiziellen Beschreibungen von v1 und v2 gleichermaßen; wo sich v2 unterscheidet, sagen wir es dazu (Stand Oktober 2026).
Stolperfalle 1: Der properties-Parameter ist streng – Filter sind es nicht
Steht im Parameter properties ein Feldname, den die Entität nicht kennt, antwortet weclapp mit einem Fehler und liefert überhaupt keine Daten. Mit properties legen Sie fest, welche Felder zurückkommen sollen – sinnvoll, um Datenmenge und Antwortzeit klein zu halten. Ein einziger Tippfehler in der Feldliste lässt aber die ganze Abfrage scheitern. Die offizielle Dokumentation bestätigt das: Bei einer unbekannten Eigenschaft oder einem unbekannten Pfad wird eine Fehlerantwort zurückgegeben.
Gefährlicher ist das umgekehrte Verhalten bei Filtern. Laut Dokumentation werden Filterparameter für unbekannte Eigenschaften oder für Eigenschaften, die keine Filterung unterstützen, stillschweigend ignoriert. Ein vertippter Filter führt also nicht zu einem Fehler, sondern zu einer ungefilterten Antwort – statt der offenen Rechnungen eines Kunden kommen dann alle Rechnungen zurück. Bei einer reinen Anzeige ist das ärgerlich, bei einer Massenänderung kann es teuer werden.
- Feldlisten gegen den Mandanten prüfen: Wir prüfen jede Feldliste und jeden Filter vor dem Einsatz mit einem kleinen Prüfskript gegen den Mandanten. Freifelder unterscheiden sich von Mandant zu Mandant.
- Filter mit dem Zähler kontrollieren: Der Endpunkt
/countakzeptiert dieselben Filter. Liefert die gefilterte Zählung dieselbe Zahl wie die ungefilterte, stimmt mit dem Filter etwas nicht. - Beim Versionswechsel aufpassen: Laut Änderungsprotokoll von v2 wurden Zusatzfelder wie Namen und Nummern referenzierter Datensätze entfernt; stattdessen gelten die ID-Felder (Changelog weclapp API v2). Feldlisten aus v1 können in v2 deshalb an genau dieser Strenge scheitern.
Stolperfalle 2: Liste und Einzelabruf antworten unterschiedlich
Eine Liste liefert die Datensätze verpackt in einem Feld result, ein Einzelabruf über /id/{id} liefert den Datensatz dagegen direkt. Auch die Zählung über /count steckt ihr Ergebnis in result. Code, der beide Formen verarbeitet, muss das berücksichtigen – sonst funktioniert die Liste, und der Einzelabruf liefert scheinbar „nichts“.
Ebenfalls leicht zu übersehen: Listen liefern ohne weitere Angabe nur die ersten 100 Datensätze. Über pageSize lässt sich die Seitengröße erhöhen, laut Dokumentation in der Regel bis 1000, und über page wird weitergeblättert. Wer das vergisst, wertet bei größeren Mandanten unbemerkt nur einen Ausschnitt aus.
Stolperfalle 3: Enums sind Schlüsselwörter, keine Anzeigetexte
Felder mit festen Auswahlwerten erwarten das technische Schlüsselwort, nicht den Text, der in der Oberfläche steht. Wer „Herr“ als Anrede schickt, erhält einen Fehler; richtig ist MR. Die Dokumentation beschreibt das allgemein: Auswahlwerte werden als Text mit dem Namen der Option übertragen. Die erlaubten Werte in der folgenden Tabelle stammen aus der offiziellen API-Beschreibung, die Hinweise in der rechten Spalte aus unseren eigenen Tests.
| Datensatz und Feld | Erlaubte Werte | Hinweis aus unseren Tests |
|---|---|---|
Kontakt bzw. Partei: salutation | MR, MRS, FAMILY, COMPANY, NO_SALUTATION | Anzeigetexte wie „Herr“ werden abgelehnt |
CRM-Ereignis: type | GENERAL, INCOMING_CALL, LETTER, OUTGOING_CALL | Beim Anlegen anzugeben |
Aufgabe: taskPriority | HIGH, MEDIUM, LOW | Beim Anlegen anzugeben |
Aufgabe: taskVisibilityType | ORGANIZATION, PRIVATE | Beim Anlegen anzugeben |
Ausgangsrechnung: status | NEW, ENTRY_COMPLETED, DOCUMENT_CREATED, OPEN_ITEM_CREATED, CANCELLED | Siehe Stolperfalle 4 |
Ein hilfreiches Detail: Bei einem ungültigen Auswahlwert liefert weclapp einen Validierungsfehler vom Typ enum, der laut Dokumentation die bekannten beziehungsweise erlaubten Werte mitliefern kann. Es lohnt sich, Fehlerantworten vollständig zu protokollieren, statt nur den Statuscode auszuwerten.
Stolperfalle 4: Rechnungen müssen gebucht werden
Eine per API angelegte Ausgangsrechnung ist zunächst nur ein Entwurf: Sie steht auf dem Status NEW und trägt eine vorläufige Nummer. Erst wenn der Status per PUT auf OPEN_ITEM_CREATED gesetzt wird, entsteht der offene Posten, und die Rechnung erhält ihre endgültige Nummer. Das haben wir so in unseren Tests beobachtet.
Die Folge für Auswertungen: Ohne offenen Posten kennt weclapp für diese Rechnung weder „unbezahlt“ noch „überfällig“. Wer Rechnungen per API anlegt und nicht bucht, sieht sie später in keiner Mahn- oder Forderungsliste.
- Bezahlt-Status nicht direkt setzen: Das Feld
paidist laut API-Beschreibung schreibgeschützt, und auchpaymentStatusergibt sich aus dem offenen Posten. - Zahlung über den offenen Posten: Eine Zahlung wird über
POST /salesOpenItem/id/{id}/updatePaymentStategemeldet – mitpaymentState(PAIDoderUNPAID) und optional dem ZahlungsdatumdatePaid.
Achtung bei Tests: Eine gebuchte Rechnung verbraucht eine echte Nummer aus Ihrem Nummernkreis. Probieren Sie das Buchen deshalb nie im Produktivmandanten aus, sondern in einem eigenen Testmandanten.
Stolperfalle 5: CRM-Ereignisse hängen an partyId, nicht an customerId
Angebote, Aufträge, Rechnungen und Aufgaben werden über das Feld customerId mit dem Kunden verknüpft, CRM-Ereignisse dagegen über partyId. Wer für eine Kundenansicht alle Datensätze mit demselben Filter abfragt, findet deshalb keine Notizen und Anrufe – und bemerkt es womöglich nicht, weil unbekannte Filter, wie oben beschrieben, stillschweigend ignoriert werden.
| Datensatz | Verknüpfung zum Kunden |
|---|---|
Angebot (quotation) | customerId |
Auftrag (salesOrder) | customerId |
Ausgangsrechnung (salesInvoice) | customerId |
Aufgabe (task) | customerId |
CRM-Ereignis (crmEvent) | partyId |
| Ansprechpartner | In unseren Tests kein Verweis auf den Kunden; die IDs stehen beim Kunden in contacts, dazu primaryContactId |
Bei den Ansprechpartnern war die Richtung in unseren Tests umgekehrt: Der Kontakt kannte seinen Kunden nicht, der Kunde kannte seine Kontakte. Verknüpft wird deshalb mit einer Änderung am Kunden, nicht am Kontakt. In v2 gibt es außerdem keine eigenen Endpunkte mehr für Kontakte, Kunden, Interessenten und Lieferanten; laut Änderungsprotokoll läuft alles über /party.
Welche weiteren Details sparen Zeit?
Viel Zeit sparen die Regeln zu Aktualisierungen, Zahlenformaten und Lastgrenzen, die in der offiziellen Dokumentation stehen, aber in vielen Projekten erst nach dem ersten Fehler gelesen werden. Die wichtigsten im Überblick:
| Thema | Was laut Dokumentation gilt | Unsere Empfehlung |
|---|---|---|
| Vollständige Aktualisierung per PUT | Nicht mitgeschickte Felder werden als leer interpretiert | Erst den aktuellen Datensatz abrufen und ändern – oder ignoreMissingProperties=true verwenden |
| Gleichzeitige Änderungen | Mit dem Feld version greift eine Sperre gegen Überschreiben | version immer mitschicken und bei Konflikt neu laden |
| Dezimalzahlen | Preise und Mengen kommen als Text, etwa "39.95" | Nicht in ungenaue Gleitkommazahlen umwandeln, wenn weitergerechnet wird |
| Datum und Uhrzeit | Millisekunden seit dem 1. 1. 1970 | Zeitzonen beim Umrechnen ausdrücklich behandeln |
| Leere Felder | Werden standardmäßig nicht mitgeliefert | Mit serializeNulls anfordern, wenn alle Felder gebraucht werden |
| Last | Keine festen Ratenlimits; überzählige Anfragen warten bis zu 30 Sekunden, danach Fehler 429 | Wiederholen mit wachsender Wartezeit, Zeitlimit ab einer Minute, Webhooks statt ungefiltertem Abfragen |
Wie testet man, ohne Produktivdaten zu gefährden?
Am sichersten testen Sie mit einem eigenen Testmandanten, dem Probelauf-Parameter dryRun und einer Erweiterung, die zunächst nur liest. Schreibende Zugriffe auf den Produktivmandanten kommen erst ganz am Schluss und nur mit klar gekennzeichneten Testdaten. So gehen wir vor:
- Erst lesen, dann schreiben: Unsere Kundenakte für weclapp hat genau eine Stelle, an der sie mit weclapp spricht, und die ist fest auf Lesezugriffe beschränkt. Ein versehentlicher Schreibzugriff ist damit technisch ausgeschlossen.
- Nachgebauter Mandant für automatische Tests: Für wiederholbare Tests bauen wir einen Mandanten mit erfundenen Daten nach, der die Antworten der API nachahmt. Die Kundenakte haben wir so und zusätzlich an einem Demo-Mandanten geprüft.
- Probelauf mit
dryRun: Laut Dokumentation unterstützen die allgemeinen POST-, PUT- und DELETE-Endpunkte den ParameterdryRun=true. Dabei wird, soweit möglich, die Geschäftslogik ausgeführt und die Eingabe geprüft, ohne dass etwas gespeichert wird. - Eigener Testmandant: Alles, was Nummernkreise verbraucht oder Buchungen auslöst – etwa Rechnungen –, gehört in einen separaten Mandanten, nie in den Produktivbetrieb.
- Eigener Benutzer mit minimalen Rechten: Ein API-Token trägt die Rechte seines Benutzers. Für Anbindungen empfiehlt sich daher ein eigener Benutzer, der nur darf, was die Anbindung braucht.
Token wie ein Passwort behandeln: Laut Dokumentation macht das Erzeugen eines neuen Tokens alle bisherigen Tokens dieses Benutzers ungültig. Planen Sie das ein, bevor Sie einen Token neu erzeugen – sonst steht jede Anbindung still, die noch den alten verwendet. Bei unserer Kundenakte trägt deshalb jeder Mitarbeiter seinen eigenen Token ein und sieht nur, was seine weclapp-Rolle ohnehin freigibt.
weclapp-Erweiterung entwickeln lassen: Worauf kommt es an?
Es kommt darauf an, dass die Erweiterung die Stolperfallen der API kennt, Ihre Daten nur so weit berührt wie nötig und ohne Eingriff in weclapp selbst auskommt. Eine gute Erweiterung ergänzt weclapp genau dort, wo Ihnen eine Funktion fehlt, statt das System zu ersetzen. Wann es sinnvoller ist, Standardsoftware zu erweitern, als eine eigene Lösung zu bauen, beschreiben wir im Ratgeber Individualsoftware oder Standardsoftware.
Wir entwickeln Erweiterungen auf Basis der weclapp-API – von reinen Leseansichten über Spracherfassung bis zur Anbindung anderer Systeme. Wichtig zur Einordnung: Wir sind ein unabhängiger Entwickler und kein offizieller weclapp-Partner. Für den weclapp Store bedeutet das eine Einschränkung, denn laut weclapp ist die Aufnahme neuer Plugins dort derzeit vorübergehend nur für Vertriebspartner möglich (weclapp Store: Verkaufen im Store, Stand Oktober 2026). Erweiterungen lassen sich aber auch ohne Store einsetzen, zum Beispiel als Browser-Erweiterung, die direkt mit Ihrem Mandanten spricht, oder als eigener Dienst.
Welche Erweiterungen wir bereits gebaut haben und wie ein Projekt abläuft, lesen Sie auf unserer Seite weclapp-Erweiterung entwickeln lassen.
Quellen
Häufige Fragen
Gibt es bei weclapp Webhooks?
Ja. Die API enthält eine eigene Ressource für Webhooks, mit der beim Anlegen, Ändern oder Löschen von Datensätzen eines Typs eine Adresse per GET oder POST aufgerufen wird. weclapp empfiehlt Webhooks in der Dokumentation ausdrücklich statt ungefiltertem, wiederholtem Abfragen.
Wie sicher ist der Zugriff über die weclapp-API?
Jede Anfrage wird mit dem persönlichen API-Token eines Benutzers angemeldet und hat genau dessen Rechte. Behandeln Sie den Token wie ein Passwort und nutzen Sie für Anbindungen einen eigenen Benutzer mit möglichst wenigen Rechten.
Kann ich eine Erweiterung im weclapp Store anbieten?
Laut weclapp ist die Aufnahme neuer Plugins in den Store derzeit vorübergehend nur für Vertriebspartner möglich (Stand Oktober 2026). Erweiterungen lassen sich aber auch ohne Store einsetzen, etwa als Browser-Erweiterung oder als eigener Dienst.
Sollte ich API-Version v1 oder v2 verwenden?
Für neue Anbindungen v2, denn sie ist laut offizieller Dokumentation die aktuelle Version. Eine ältere Version bleibt nach Erscheinen einer neuen mindestens ein Jahr verfügbar; bestehende v1-Anbindungen sollten Sie deshalb rechtzeitig prüfen und umstellen.