Zurück zur Anleitung

Erste Schritte mit der Bill Alps API

Was die REST-API v1 abdeckt, wie Sie gefahrlos in der Sandbox einen Schlüssel erhalten, und der erste Aufruf, der Ihnen sagt, auf welche Firmen Sie zugreifen können.

Entwickler6 Min. Lesezeit
Inhaltsverzeichnis+

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, und umgekehrt.

  • Konto und Firmen: /me, /companies, /mandates für Treuhänder.
  • Fakturierung: Kunden, Rechnungsvorlagen, Rechnungen, Offerten, wiederkehrende Rechnungen, mit ihren PDFs und dem E-Mail-Versand.
  • Lohn: Mitarbeitende, Lohnabrechnungen (einzeln und im Stapel), Abwesenheiten.
  • Ausgaben und Buchhaltung: Lieferantenrechnungen, importierte Banktransaktionen, Jahresabschluss.

Firmenbezogene Routen (/companies/{companyId}/…) setzen voraus, dass die Firma auf dem Plan Business ist und das betreffende Modul (Fakturierung, Lohn, Ausgaben, Jahresabschluss) aktiviert ist. 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 Free-Konto ö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.

3. Einen Schlüssel erstellen

  • Erstellen Sie den Schlüssel aus einer beliebigen Business-Firma heraus, die Sie verwalten — die Firma dient nur der Berechtigung bei der Erstellung; 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.
  • 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 dem Convex-Deployment, das sie ausliefert: eine .convex.site-Adresse, die im Panel API-Schlüssel direkt unter Ihren Schlüsseln steht. Das Sandbox-Panel zeigt die Sandbox-Adresse, das Produktions-Panel die Produktionsadresse; die Schlüssel sind 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/me

Die 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/companies

Eine Firma auf 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 ist der Origin, von dem Sie es geladen haben, Produktion und Sandbox zeigen also jeweils auf sich selbst. Fügen Sie die URL in editor.swagger.io ein, um zu blättern, oder erzeugen Sie daraus einen Client.

In der Sandbox bietet das Panel KontoAPI-Schlüssel zusätzlich den Link «Documentation DEV» 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 und, für die übergreifenden Regeln, Konventionen und Fehler. Die Swagger UI Ihres Deployments bleibt die Referenz für jedes Feld.