Die öffentliche API von Bill Alps stellt per REST bereit, was die Anwendung am Bildschirm tut: Kunden, Rechnungen, Offerten, Mitarbeitende, Lohnabrechnungen, Ausgaben und Buchhaltung. Diese Anleitung führt Sie von null zum ersten erfolgreichen Aufruf, in der Sandbox, ohne Ihre Produktionsdaten anzurühren.
BASE=https://<deployment>.convex.site/api/v1
KEY=ba_...1. Was die API abdeckt
Die API v1 läuft auf demselben Code wie die Anwendung: Jede Route ruft die Geschäftslogik der App auf, mit denselben Prüfungen, denselben Kontingenten und denselben PDFs. Was am Bildschirm abgelehnt wird, lehnt auch die API ab.
- Konto und Firmen:
/me,/companies(Profil und Logo der Firma),/mandatesfür Treuhandbüros. - Rechnungsstellung: Kunden (einzeln oder im Stapel), Produktkatalog und Produktlisten, Rechnungsvorlagen, Rechnungen, Offerten, wiederkehrende Rechnungen, mit ihren PDFs und dem E-Mail-Versand.
- Lohn: Mitarbeitende, Absenzen, Lohnabrechnungen (einzeln oder im Stapel erstellen, validieren, senden, korrigieren, duplizieren, PDFs im Stapel), Feiertage und Vorschauen, Status der Links zum Mitarbeiterbereich.
- Ausgaben und Bank: Ausgaben und Belege, Entwürfe und KI-Extraktion, importierte Banktransaktionen.
Der Vertrag veröffentlicht auch die Routen für Hauptbuch, MWST und Jahresrechnung, doch in der Produktion antworten sie 403 LEDGER_DISABLED.
Firmenbezogene Routen (/companies/{companyId}/…) setzen voraus, dass die Firma auf dem Plan Business ist und dass das betreffende Modul (Rechnungsstellung, Lohn oder Buchhaltung) unter Mein KontoModule aktiviert ist. Deckt Ihr Business-Abonnement ein aktiviertes Modul nicht ab, antworten dessen Routen trotzdem, aber mit den Limiten des Plans Starter. Schlüssel sind Server-zu-Server-Zugangsdaten: Die Endpunkte haben bewusst kein CORS, also nie einen Schlüssel in einen Browser oder eine Mobile-App einbauen.
2. In der Sandbox beginnen
In der Sandbox gilt jede Firma als Business, unabhängig vom echten Plan, was alle Routen auch für ein Konto auf Starter öffnet. E-Mails werden nicht zugestellt, Stripe verrechnet nichts, Team-Einladungen gehen nicht raus. Alles andere läuft, auch die geplanten Jobs: der richtige Ort, um eine Integration zu bauen und zu testen.
Zwei Unterschiede zur Produktion. Das Hauptbuch ist dort offen, seine Routen antworten also nicht 403 LEDGER_DISABLED; Kontenplan und Buchungen werden jedoch nicht kopiert: Um sie zu nutzen, müssen Sie die Buchhaltung in der Sandbox aktivieren. Und in einer leeren Umgebung behält die erstellte Firma die Kontingente des Plans Starter, auch wenn ihr alle Routen offenstehen.
3. Einen Schlüssel erstellen
- Erstellen Sie den Schlüssel aus einer beliebigen Business-Firma heraus, die Sie verwalten: Die Firma dient nur dazu, die Erstellung zu autorisieren, der Schlüssel selbst ist persönlich und trägt keine Firma.
- Sie brauchen die Rolle Inhaber oder Admin auf der aktiven Firma, und diese muss auf Business sein (in der Sandbox ist das immer der Fall).
- Ein Schlüssel gehört der Person, die ihn erstellt hat, nicht der Firma: Er wirkt auf jede Firma, auf die diese Person Zugriff hat, mit ihren Berechtigungen. Bis zu 10 aktive Schlüssel pro Benutzer.
- Das Feld Ablauf steht standardmässig auf Kein Ablauf. Ein abgelaufener Schlüssel antwortet
401 INVALID_API_KEY, wie ein widerrufener. - Zum Rotieren: zweiten Schlüssel erstellen, Integration umstellen, dann den ersten im selben Bildschirm widerrufen.
4. Basis-URL und Header
Die API liegt nicht auf dem Host der Anwendung, sondern auf einer .convex.site-Adresse, die je nach Umgebung verschieden ist. Das Panel API-Schlüssel zeigt sie nicht im Klartext an: Sein Link API-Swagger öffnet https://<deployment>.convex.site/api/docs, und die Basis-URL ist derselbe Origin, gefolgt von /api/v1. Das Sandbox-Panel zeigt auf die Sandbox, das Produktions-Panel auf die Produktion; die Schlüssel sind zwischen den beiden nicht austauschbar, ein Sandbox-Schlüssel ist der Produktion unbekannt.
Jede Anfrage trägt den Schlüssel im Header Authorization:
Authorization: Bearer ba_...5. Erster Aufruf
Der erste Aufruf ist GET /me: Er sagt Ihnen, wem der Schlüssel gehört und worauf er wirken kann.
curl -H "Authorization: Bearer $KEY" $BASE/meDie Antwort enthält data.companies[], jede Firma mit ihrer id, Ihrer role, ihrem effektiven plan und ihren modules. Diese ids nehmen alle Routen /companies/{companyId}/… entgegen. Dieselbe Liste gibt es als einfaches Array:
curl -H "Authorization: Bearer $KEY" $BASE/companiesEine Firma auf Starter oder Team (plan ist free oder team) erscheint in der Liste, ihre Routen antworten aber 403 PLAN_NOT_ALLOWED. Wählen Sie eine Firma, bei der das gewünschte Modul aktiv ist, und Sie sind bereit für die nächsten Anleitungen.
6. Interaktive Dokumentation
Jedes Deployment beschreibt sich selbst. Unter https://<deployment>.convex.site/api/docs zeigt eine Swagger UI den gültigen Vertrag: auf Authorize klicken, einen ba_-Schlüssel einfügen, dann «Try it out» auf jeder Route. Der Schlüssel bleibt bis zum Logout im lokalen Speicher des Browsers, also lieber einen widerrufbaren Schlüssel und die Sandbox verwenden.
Das OpenAPI-3.1-Dokument wird unter https://<deployment>.convex.site/api/v1/openapi.json ausgeliefert, öffentlich, ohne Schlüssel, mit offenem CORS. Es wird bei Abruf aus der Routentabelle und den Anfrage- und Antwortschemas erzeugt: Was es beschreibt, ist genau das, was die API durchsetzt. servers[0].url übernimmt den Origin, von dem Sie es geladen haben, gefolgt von /api/v1; Produktion und Sandbox zeigen also jeweils auf sich selbst. Fügen Sie die URL in editor.swagger.io ein, um es zu durchblättern, oder erzeugen Sie daraus einen Client.
In der Sandbox bietet das Panel Mein KontoAPI-Schlüssel zusätzlich den Link DEV-Dokumentation zum Datenmodell der Anwendung (Entity-Relationship-Diagramm), nützlich, um zu verstehen, wie die Ressourcen zusammenhängen.
Der Rest lässt sich in beliebiger Reihenfolge lesen: Rechnungen per API, Lohn, Ausgaben und Buchhaltung per API, Lohnlauf per API und, für die übergreifenden Regeln, Konventionen und Fehler. Die Swagger UI Ihres Deployments bleibt die Referenz für jedes Feld.