Holded anbinden: Zwei Zähler und zwei Status

Holded hat ein vollständiges Ereignissystem, und über uns ist es heute noch nicht nutzbar. Diese eine Tatsache entscheidet den Zuschnitt der Integration, weil sie die ganze Frage der Aktualität in Code verlagert, der Ihnen gehört: Was Sie über die Bücher eines Kunden wissen, ist das, wonach Ihr letzter Lesevorgang gefragt hat.

Beide Hälften sind dokumentiert. Holded veröffentlicht 18 Ereignisgruppen und 58 Ereignisse, von invoice.create bis stock.update, jede Zustellung signiert mit einem HMAC-SHA256-Digest über den Rohtext und mit exponentiellem Backoff wiederholt, bis Ihr Endpunkt mit einem 2xx antwortet.

Ein Header sagt schon, wie der Hersteller die Behandlung erwartet: x-holded-webhook-id ist beschrieben als „Eindeutige Ereignis-ID; nutzen Sie sie als Idempotenzschlüssel“.

Über maesn trägt heute kein Holded-Objekt ein freigeschaltetes Ereignis, und 26 Kombinationen aus Objekt und Operation stehen auf „auf Anfrage verfügbar“. Warum diese Lücke besteht, sagt keine unserer Quellen, und dieser Artikel stellt dazu keine Vermutung an. Was Objekt für Objekt freigeschaltet ist und was eine solche Anfrage umfasst, steht auf der Seite zur Holded-Schnittstelle.

Es gibt einen zweiten Grund, den Zeitplan ernst zu nehmen, und er kommt von Holded selbst. Seine Seite zu den Ratenlimits führt sechs Praktiken für Integratoren auf, und eine davon lautet „No hagas polling. Suscríbete a webhooks y recibe actualizaciones en tiempo real sin consumir tu cuota“: kein Polling, abonnieren Sie Webhooks und empfangen Sie Aktualisierungen in Echtzeit, ohne Ihr Kontingent zu verbrauchen.

Das Verfahren, das der Hersteller zum Schutz des Budgets empfiehlt, steht Ihnen hier nicht zur Verfügung, und ein Zeitplan muss das einrechnen.

Die Schleife ist also ein Delta-Lesevorgang, und unsere eigene Anleitung dazu ist knapp. Speichern Sie den Zeitstempel Ihres letzten erfolgreichen Abrufs, geben Sie ihn beim nächsten Aufruf als lastModified mit und „fragen Sie mit der niedrigsten tragfähigen Frequenz ab“, und beachten Sie dabei unsere Ratenlimits ebenso wie die des Zielsystems.

Bei Holded ist die zweite Hälfte die teure, und davon handelt der letzte Abschnitt dieses Artikels.

Was diese Schleife heute liest, ist die Stammdatenebene. Kontakte, Kunden und Lieferanten sind die drei Objekte, die maesn für Holded freigeschaltet hat, und dieselben drei laufen auch in die andere Richtung, eine Firma, die hier ankommt, lässt sich hier also auch korrigieren.

Das ist ein schmaler Zuschnitt mit einem schwierigen Kern: Kunden- und Lieferantendaten im Gleichstand zu halten ist das Problem, über das zwei Systeme am häufigsten streiten, weil jedes von beiden glaubt, die Firma zu besitzen, die es beschreibt.

Alles, was einen Betrag trägt, Rechnungen eingeschlossen, muss angefragt werden. Für jeden Abschnitt weiter unten heißt das konkret: Die Leseregeln dort sind Holdeds eigene, sie entscheiden, was eine Auswertung behaupten darf, und welche davon Ihr Produkt je trifft, hängt davon ab, welche Objekte Sie anfragen.

Eine strukturelle Anmerkung vor dem Detail. Was über das Event-Modell ankommt und was Sie nach Zeitplan abrufen, sind getrennte Wege in der Unified API, und ein System ohne Freischaltungen legt das ganze Gewicht auf den zweiten. Was unten steht, beschreibt, wie man ein System sauber liest, wenn Lesen der einzige Kanal ist.

Die naheliegende Abfrage für offene Forderungen liefert eine zu kleine Zahl. status=pending wählt Rechnungen aus, auf denen überhaupt keine Zahlung erfasst ist, jede teilweise bezahlte Rechnung steht also außerhalb des Ergebnisses und schuldet den Rest weiter.

Holded dokumentiert das selbst, in Großbuchstaben in der Beschreibung des Endpunkts und dann noch einmal in der Beschreibung des Parameters:

„WICHTIG, offene Forderungen (‚pendiente de cobro‘): status=pending trifft NUR Rechnungen ohne erfasste Zahlung; teilweise bezahlte Rechnungen stehen auf status=partial und schulden weiter Geld. Um das Offene zu zählen oder zu summieren, fragen Sie BEIDE Status ab (pending und partial) und summieren Sie payments_pending. Eine Abfrage allein auf status=pending zählt zu niedrig.“

Insgesamt sind sechs Statuswerte dokumentiert. Zwei davon bedeuten, dass Geld noch offen ist, einer ist eine Sicht über diese zwei, und die übrigen drei sind gar nicht als offen beschrieben.

status=overdue ist der Filter über beide, also eine Auswertung. Eine Rechnung erfüllt beide Beschreibungen gleichzeitig, ohne je von partial nach overdue zu wechseln, und eine als Zustandsmaschine gebaute Mahnlogik hat genau dort ihren ersten Fehler.

Es gibt eine zweite Ebene. Unser vereinheitlichter Filter status für Rechnungs-Lesevorgänge ist für neun verbundene Systeme dokumentiert und Holded gehört nicht dazu, und die Rechnungsobjekte selbst stehen für Holded auf „auf Anfrage“.

Die erste Frage in einem Projekt zur Debitorenbuchhaltung ist deshalb, ob die Objekte, die Ihre Auswertung braucht, für diese Verbindung überhaupt eingerichtet sind, und das ist ein Gespräch mit uns, bevor es ein Parameter ist.

Eine Holded-Rechnung trägt zwei Daten, und jedes hat sein eigenes Parameterpaar. start_date und end_date filtern nach dem Rechnungsdatum, due_date_start und due_date_end nach dem Fälligkeitsdatum, und alle vier sind optional.

Die Folge ist leicht gesagt und leicht übersehen: Was im letzten Monat hereinkam und was im nächsten Monat fällig wird, sind zwei verschiedene Abfragen gegen denselben Endpunkt, und keine davon beantwortet die andere. Eine Liquiditätssicht auf dem Rechnungsdatum wirkt monatelang plausibel und liegt jedes Mal falsch, wenn ein Zahlungsziel länger ist als der Berichtszeitraum.

Auch die Voreinstellung verdient Aufmerksamkeit, denn Holded ist dazu deutlich: „alle sind optional, und ungefiltert bedeutet das ganze Konto“. Vergessen Sie einen Datumsparameter, enthält die Antwort jede Rechnung, die der Mandant je gestellt hat, und auf einem Konto, dessen Aufrufe gezählt werden, ist das ein teurer Weg, einen Fehler zu finden.

Zwei kleinere Details aus derselben Referenz sind in der Praxis wichtig. Daten nehmen RFC 3339 mit Offset oder ein reines Kalenderdatum, 2026-01-01 und 2026-01-01T00:00:00+00:00 sind also beide gültig.

Das ist nicht das einzige Format, das Holded veröffentlicht, und es ist das Erste, was Sie prüfen sollten, bevor Sie einen Datumshelfer schreiben. Der Academy-Artikel zur Erzeugung eines Schlüssels sagt rundheraus, dass „Daten im Unix-Timestamp-Format gesendet werden müssen“. Zwei Herstellerseiten, zwei Formate.

Der wahrscheinliche Grund ist, dass Holded zwei Generationen seiner Schnittstelle im Umlauf hat. Die oben zitierte Referenz dokumentiert die aktuelle, und derselbe Academy-Artikel nennt für Schlüssel zur älteren Generation einen eigenen Weg. Senden Sie, was der Endpunkt dokumentiert, den Sie tatsächlich aufrufen, und tragen Sie keinen Datumshelfer von einer Generation in die andere.

Und die Freigabe läuft über einen eigenen Filter. approval_status nimmt draft für nicht freigegebene Belege und approved für freigegebene, ein Lesevorgang ohne diesen Parameter ist also nicht auf freigegebene Belege beschränkt.

Auch die Sortierung ist als feste Menge dokumentiert, mit einem führenden Minus für absteigende Reihenfolge: date, dueDate und total, jeweils in beide Richtungen. Nützlich, wenn Sie bei einem wiederaufgenommenen Lauf die neueste Seite zuerst wollen, und eine Erinnerung daran, dass die Reihenfolge einer Ergebnismenge hier etwas ist, worum Sie bitten.

Ein Filter auf der Rechnungsliste ist spanische Buchhaltungspraxis, zu einem Parameter gemacht. accounting_account_num wählt Rechnungen aus, die mindestens eine Zeile auf ein bestimmtes Konto gebucht haben, und es bezeichnet dieses Konto über seinen numerischen Code aus dem Plan General de Contabilidad.

Holded dokumentiert beide Fehlerfälle, und sie sagen Verschiedenes. Ein Wert, der keine Zahl ist, kommt als 400 zurück, mit der Meldung, der Parameter „must be a positive integer (PGC code)“. Eine Nummer, die kein Sachkonto dieses Mandanten trägt, beantwortet Holded mit 404, wo ein Client eine leere Liste erwartet.

Das Erste ist ein Fehler in Ihrer Anfrage, das Zweite eine Tatsache über den Kontenrahmen Ihres Kunden, und ein Client, der beides gleich behandelt, verbirgt einen Zuordnungsfehler so lange, bis jemand von Hand abstimmt.

Die Referenz nennt als Beispiel 70000000 für „Ventas de mercaderias“, und sie hält fest, dass der Name eines Kontos nur dann zu seinem Code aufgelöst wird, wenn der Aufruf über Holdeds eigenen Assistenten kommt. Ihre Integration übergibt den Code.

So wird ein spanischer Kontenrahmen Teil Ihrer Konfigurationsfläche, je Mandant, und es ist die Art von Zuordnung, die beim Onboarding günstig zu speichern und später teuer zu rekonstruieren ist.

Steuern fallen in dieselbe Kategorie. Holded gruppiert Steuerarten mit Produkten und Kontakten als Stammdaten, die sich selten ändern und lokal vorgehalten werden sollten, und unsere eigene Coverage führt Tax rates für Holded als eigenständiges Objekt, auf Anfrage verfügbar. Ein Steuersatz ist hier mehr als eine Prozentzahl auf einer Rechnungszeile: ein eigener Datensatz, den Sie auflösen und vorhalten.

Holded blättert über einen Cursor. Eine Listenantwort trägt einen Wert cursor und ein Flag has_more, und Sie geben den Cursor zurück, um die folgende Seite zu holen. Der Cursor ist als undurchsichtig dokumentiert und als „Null auf der letzten Seite“.

Zweierlei folgt daraus. Das Ende des Durchlaufs hat ein dokumentiertes Signal, die Schleife endet also an has_more und an einem Cursor, der null ist; die Größe der Antwort ist dafür kein Signal. Und weil der Cursor undurchsichtig ist, bezeichnet er eine Position in einer Ergebnismenge, die sich nicht nachbauen lässt, ein wiederaufgenommener Lauf muss den Cursor also behalten, den er bekommen hat, oder die Abfrage neu stellen.

An der Seitengröße entscheidet sich, was ein erster vollständiger Lesevorgang kostet. limit steht voreingestellt auf 50 und nimmt höchstens 200, und auf einem Konto mit einem monatlichen Aufrufbudget ist die Voreinstellung die teure Wahl für einen Erstabzug. Sie ist zugleich die, die Sie bekommen, wenn Sie nichts übergeben.

Über maesn ist derselbe Durchlauf kürzer, und genau darum geht es bei einer vereinheitlichten Schnittstelle: Sie schreiben überhaupt keine Cursor-Behandlung. Lesevorgänge nehmen limit und page, und ein Weg, zu filtern und zu paginieren, deckt jedes verbundene System ab, die Schleife für Holded ist also die Schleife, die Sie für das System davor schon geschrieben haben.

Ein Detail übersieht man leicht: die Zählung in page beginnt bei 1.

Holded führt zwei Ratenzähler parallel, und beide zählen auf dem Konto. Einer ist ein Burst-Schutz je Minute, der andere ein monatliches Aufrufkontingent, und in den Worten des Herstellers: „El primero que se llena es el que devuelve 429“, was zuerst voll ist, antwortet mit 429.

Der Zuschnitt auf das Konto hat eine Folge, die man genau einmal zu umgehen versucht: „Todas las claves API de la misma cuenta comparten los mismos contadores, así que añadir más claves no aumentará tu presupuesto“. Alle Schlüssel eines Kontos teilen sich beide Zähler, ein zweiter Schlüssel verschafft also keinen zusätzlichen Spielraum. Der dokumentierte Weg zu mehr Spielraum ist ein höherer Tarif.

Das Kontingent wächst mit dem Tarif, den Ihr Kunde bezahlt, womit die Obergrenze Ihres Abgleichs eine kaufmännische Größe ist, die beim Kunden liegt.

Es ist eine Größe, die Ihr Kunde nachsehen kann. Holded dokumentiert eine Ansicht zur API-Nutzung in demselben Developers-Bereich, in dem der Token angelegt wird, und sie zeigt „die getätigten Aufrufe und das Limit, das Sie auf Ihrem Konto haben“. Die Frage, wie nah ein Abgleich an der Obergrenze läuft, hat damit eine Antwort, die er ablesen kann, und das ist eine bessere Grundlage für ein Intervall als eine Schätzung auf einer der beiden Seiten.

Was die Antwort Ihnen sagt, zählt hier mehr als die Zahlen. Ein 429 trägt Retry-After in Sekunden und die üblichen X-RateLimit-Limit, X-RateLimit-Remaining und X-RateLimit-Reset.

Ein weiterer Header wird leicht übersehen und leistet die eigentliche Arbeit: X-RateLimit-Window, sein Wert ist minute oder month. Er sagt Ihnen, ob Warten hilft. Bei minute hilft es: halten Sie die Zeit aus Retry-After ein, und das nächste Fenster hebt die Sperre von selbst auf. Bei month hilft es nicht, weil das erschöpfte Kontingent das Monatsbudget des Kontos ist, die Antwort ist also ein größerer Tarif oder weniger Aufrufe. Zwei 429 mit demselben Rumpf bedeuten zwei verschiedene Dinge, und dieser Header trennt sie.

Dass dieser Abschnitt Header beschreibt und keine feste Obergrenze je Minute nennt, hat einen Grund: Holded dokumentiert diese Obergrenze zweimal, und die zwei Angaben stimmen nicht überein.

Seine Seite zu den Ratenlimits nennt 60 bis 600 Anfragen je Minute abhängig vom Tarif und rechnet sie je Konto; seine Fehlerseite schreibt „La API permite 100 peticiones por minuto por clave API“, also 100 je Minute und je Schlüssel. Andere Zahl und anderes Modell.

Die Beispielantwort auf der Seite zu den Ratenlimits trägt dann noch eine dritte Zahl, nämlich den Wert aus dem Ausschnitt oben.

Das Monatskontingent erscheint dagegen genau einmal und ohne Widerspruch, es ist also die Zahl, gegen die ein Zeitplan bemessen werden kann. Alles zum Minutenfenster gehört in Code, der sich an den Headern ausrichtet. Eine Konstante im Quelltext müsste jemand einer Herstellerseite nachführen.

Und wenn der Aufruf von vornherein abgewiesen wird, bedeuten die vier Codes vier verschiedene Dinge. Ein 401 heißt, der Schlüssel fehlt oder ist ungültig, ein 403 heißt, der Schlüssel ist gültig und hat für diesen Endpunkt keine Berechtigung, ein 400 heißt, die Anfrage selbst ist fehlerhaft, und ein 422 heißt, das JSON war gültig und die semantische Prüfung ist fehlgeschlagen.

Über uns kommen diese vier in einem Fehlermodell an, Sie schreiben also keinen Holded-eigenen Zweig neben einem Zweig für jedes andere System.

Eine vereinheitlichte Schnittstelle nimmt das meiste von dem ab, was die Abschnitte oben beschreiben. Was sie nicht abnehmen kann, sind die fünf Entscheidungen unten, und jede davon ist früh günstig zu treffen und später teuer zu ändern.

Was die Verbindung von Ihrem Tisch nimmt:

• Der Schlüssel, je Mandant verwahrt. Holded zeigt einen API-Schlüssel genau einmal, und Unified Authentication übernimmt die Erfassung, die Verwahrung und die gebrandete Einstiegsseite einmal, für jedes System.
• Eine Form für Stammdaten. Kontakte, Kunden und Lieferanten kommen in demselben gemeinsamen Datenmodell an wie die Daten jedes anderen verbundenen Systems, ein Lieferant aus Holded wird also genau so zugeordnet wie ein Lieferant von anderswo.
• Ein Modell für Blättern und Filtern. Cursor, undurchsichtige Token und die Voreinstellung von 50 Zeilen bleiben hinter der Schnittstelle, und Ihre Schleife nutzt dieselben zwei Parameter wie überall.
• Ein Fehlermodell. Das 403 auf einen fehlenden Scope und das 429 auf einen der beiden Zähler kommen in der Form an, die Sie ohnehin behandeln.
• Eine Umgebung zum Bauen. Holded bietet eine kostenlose Testphase, für die Sie sich selbst registrieren können, und wir stellen auf Anfrage eine Sandbox mit Testdaten bereit.

Was bei Ihnen bleibt:

• Die Abfragefrequenz, und ihr Budget. Das Kontingent gehört zum Tarif Ihres Kunden. Wie aktuell Ihr Produkt dessen Daten braucht, entscheiden nur Sie, und auf diesem System hängt daran ein Preisschild.
• Welche Objekte die Verbindung braucht. Drei sind freigeschaltet, der Rest wird freigeschaltet, wenn ein Anwendungsfall ihn braucht. Das vor dem Zuschnitt der Arbeit anzusprechen, ist ein Gespräch; es danach anzusprechen, ist eine Neuplanung.
• Die spanischen Besonderheiten, die Sie vorhalten. Sachkontonummern und Steuersätze gelten je Mandant, und wo sie in Ihrem Datenmodell landen, ist Ihr Entwurf.
• Was ein 429 auf dem Monatsfenster für Ihr Produkt bedeutet. Einen Abgleich anzuhalten, den Kunden zu warnen oder ihn um ein Upgrade zu bitten, ist eine Produktentscheidung.
• Der Tarif, und wer den Token anlegt. Holded stellt die Schnittstelle in allen bezahlten Tarifen bereit und sagt, sie sei „im Free-Tarif nicht verfügbar“, und wer einen Token anlegt, braucht Zugang zum Developers-Bereich, den auch eine selbst angelegte Rolle tragen kann. Die Berechtigungen des Tokens werden bei der Erstellung gewählt und bleiben unabhängig von der Rolle der Person.