API-Referenz (Beta)

Die API von To Bill ist dieselbe, die die App selbst verwendet: Kunden, Rechnungen, Offerten, Artikel, Ausgaben, Bank, Buchhaltung, MWST, Löhne und Zeit. Ein persönlicher API-Schlüssel öffnet sie für Ihre Skripte und Werkzeuge, mit Ihren Rechten. Die interaktive API-Referenz beschreibt jede Route, die ein Schlüssel aufrufen kann, ihre Parameter und Antworten, zeigt Beispiele in curl, JavaScript, Python und PHP und lässt Sie eine Anfrage mit Ihrem Schlüssel ausprobieren.

Die Referenz ist auf Englisch

Wie die meisten technischen Referenzen ist sie auf Englisch verfasst, in der Sprache der Entwicklerinnen und Entwickler. Diese Seite fasst das Wichtigste zusammen.

Eine Beta-Version

Die API ist in der Beta-Version (0.x). Ihre Routen und deren Antworten können sich ohne Vorankündigung ändern: Es gibt weder eine Kompatibilitätsgarantie noch Support für ihre direkte Nutzung. Um einen KI-Assistenten zu verbinden, verwenden Sie den MCP-Server, die stabile Schnittstelle: siehe KI-Assistenten verbinden.

Authentifizieren

Jede Anfrage trägt einen persönlichen API-Schlüssel im HTTP-Header Authorization:

curl https://app.tobill.ch/api/clients -H "Authorization: Bearer tb_pk_…"

Den Schlüssel erstellen Sie unter Einstellungen › KI- und API-Verbindungen: siehe Die API und die API-Schlüssel. Er handelt in Ihrem Namen, in dem Unternehmen, in dem Sie ihn erstellt haben, mit Ihren Rechten in diesem Unternehmen. Ein Schlüssel mit Nur lesen sendet nur Leseanfragen (GET); ein Schlüssel mit Lesen und ändern kann auch erstellen, ändern und löschen.

Fehler

Eine abgelehnte Anfrage erhält eine JSON-Antwort in dieser Form: { "statusMessage": "error", "message": "…", "error_code": "…", "fallback": "…" }. message ist ein stabiler Code, den Ihr Programm prüfen kann; fallback ist ein lesbarer Satz, der zum Beispiel das betroffene Feld nennt.

HTTP-Code	Bedeutung
400	Ungültige Daten.
401	Schlüssel fehlt, ist ungültig, abgelaufen oder widerrufen.
403	Abgelehnt: Schlüssel nur zum Lesen, fehlendes Recht, Abonnement ohne API-Zugang oder ein Teil von To Bill, der für Schlüssel geschlossen ist (not_available_with_api_token).
404	In diesem Unternehmen nicht gefunden.
429	Zu viele Anfragen: Warten Sie so viele Sekunden, wie der Header Retry-After angibt.

Grenzen

• 300 Anfragen pro Minute und Schlüssel; eine Änderung zählt doppelt.
• Ein Schlüssel öffnet weder die Anmeldung bei Ihrem Konto noch das Abonnement, die Zahlungen, die Verwaltung des Teams und der Schlüssel, ein anderes Unternehmen, das Cockpit eines Treuhänders oder Massenaktionen. Diese Routen stehen nicht in der Referenz.

Die OpenAPI-Spezifikation

Die Referenz wird aus dem OpenAPI-3.1-Dokument der API erzeugt. Sie können es in ein Werkzeug wie Postman importieren oder daraus einen Client generieren:

Was	Adresse
Interaktive Referenz	https://docs.tobill.ch/api
OpenAPI-3.1-Spezifikation	https://app.tobill.ch/api/openapi.json

Eine Anfrage ausprobieren

In der Referenz sendet die Schaltfläche Test Request die Anfrage aus Ihrem Browser direkt an https://app.tobill.ch, ohne Zwischenstation. Ihr Schlüssel geht nur an To Bill und wird nicht gespeichert: Er verschwindet, wenn Sie die Seite schliessen. Eine ändernde Anfrage ändert Ihre Daten tatsächlich: Um die API kennenzulernen, probieren Sie sie mit einem Schlüssel mit Nur lesen aus.