Weclapp API: Was geht, und was nicht
Über die Schnittstelle lässt sich fast alles lesen und schreiben, was in Weclapp steckt. Damit Anbindungen im Alltag halten, lohnt es sich, ein paar Eigenheiten zu kennen.
Auf einen Blick
- REST-Schnittstelle, Version 2 für neue Anbindungen
- Zugriff mit persönlichem Token, mit den Rechten des Benutzers
- Webhooks melden Änderungen an andere Systeme
- Vor jedem Schreiben lesen: jedes Objekt hat eine Version
Die Grundlagen
Weclapp hat eine REST-Schnittstelle, auch API genannt. Über sie können andere Programme Daten lesen und schreiben, so wie ein Mensch in der Oberfläche. Für neue Anbindungen ist die Version 2 der richtige Weg, die ältere Version 1 wird abgekündigt.
Der Zugriff läuft über einen persönlichen Token, den jeder Benutzer in seinen Einstellungen erzeugt. Die Schnittstelle darf genau das, was dieser Benutzer darf. Für Anbindungen lohnt sich deshalb ein eigener technischer Benutzer mit passenden Rechten (Dokumentation).
Was die Schnittstelle gut kann
Fast alle Geschäftsobjekte
Artikel, Kunden und Lieferanten, Angebote, Aufträge, Rechnungen, Lieferungen, Wareneingänge und Lagerbestände.
Genaue Filter
Abfragen mit Operatoren wie gleich, grösser, kleiner, enthält oder in einer Liste, auch auf Zusatzfeldern. Gefiltert wird in Weclapp, nicht hinterher.
Nur benötigte Felder
Mit dem Parameter properties kommen nur die Felder zurück, die gebraucht werden. Das macht Abfragen deutlich schneller.
Gezielte Änderungen
Mit ignoreMissingProperties=true wird nur geändert, was mitgeschickt wird. Alle anderen Felder bleiben unberührt.
Die wichtigsten Stolperfallen
Aus vielen Anbindungen sind das die Punkte, die am häufigsten Zeit kosten:
Versionen beim Schreiben
Jedes Objekt hat eine Version. Wer schreibt, schickt die aktuelle Version mit. Hat jemand anderes den Datensatz inzwischen geändert, schlägt die Änderung fehl. Also: lesen, dann schreiben, und bei Konflikten neu lesen.
Zusatzfelder über IDs
Zusatzfelder werden über interne IDs angesprochen, nicht über ihren Namen, und diese IDs unterscheiden sich zwischen Mandanten. Sicherer ist es, die Definitionen zur Laufzeit zu laden.
Berechnete Felder
Manche Felder, die in der Oberfläche erscheinen, werden nur berechnet. Sie lassen sich nicht abfragen, und eine Abfrage mit ihnen bleibt leer.
Aktionen brauchen einen Inhalt
Aktionen wie das Anlegen eines Wareneingangs aus einer Bestellung erwarten immer einen Inhalt im Aufruf, notfalls ein leeres Objekt.
Webhooks: Weclapp meldet sich selbst
Weclapp kann andere Systeme aktiv benachrichtigen, wenn ein Datensatz angelegt, geändert oder gelöscht wird. Statt ständig nachzufragen, ob es etwas Neues gibt, reagiert eine Anbindung dann sofort. Schlägt eine Benachrichtigung fehl, versucht Weclapp es laut Dokumentation mehrmals erneut und deaktiviert den Webhook nach einem Tag (Dokumentation).
Für stabile Abläufe heisst das: Ein Webhook ist der schnelle Weg, ein regelmässiger Abgleich im Hintergrund ist das Sicherheitsnetz, falls einmal etwas verloren geht.
Tipps für stabile Anbindungen
Zuerst in einem Testmandanten
Schreibende Abläufe nie blind gegen die echten Daten testen. Ein zweiter Weclapp-Mandant zum Ausprobieren spart viel Ärger.
Immer nur ändern, was sich ändern soll
Gezielte Änderungen mit ignoreMissingProperties, damit keine Felder versehentlich überschrieben werden.
In Portionen arbeiten
Grosse Datenmengen seitenweise lesen und in kleinen Paketen schreiben, mit Pausen und Wiederholung bei Fehlern.
Fehler sichtbar machen
Jede Anbindung protokolliert, was sie tut, und meldet sich, wenn etwas hängen bleibt. Sonst läuft sie wochenlang still ins Leere.
Wo die Grenzen liegen
Nicht alles, was in der Oberfläche geht, geht auch über die Schnittstelle. Einzelne Felder sind nur lesbar, und manche Abläufe gibt es nur in der Oberfläche. Das zeigt sich oft erst beim Bauen, deshalb prüfe ich kritische Punkte früh an einem kleinen Beispiel.
Änderungen an der Schnittstelle veröffentlicht Weclapp im API-Changelog. Wer Anbindungen betreibt, sollte ihn im Blick behalten.
Erzählen Sie mir, wo es hakt.
Im Erstgespräch schauen wir uns Ihren Ablauf an. Danach wissen Sie, ob Weclapp das schon kann oder was eine eigene Lösung kosten würde.