Billutant API

Rechnungen aus externen Tools erstellen

Die External API verbindet eigene Systeme, Automationen und Integrationen mit Billutant. Ein Token reicht, um Kunden, Artikel, Vorlagen und Rechnungen mandantensicher zu verwalten.

Endpunkte ansehen Token in Billutant erstellen

Quick start

POST /invoices
Authorization: Bearer bt_live_...
Content-Type: application/json

{
  "customerId": "customer_123",
  "itemIds": ["item_setup", "item_monthly"],
  "draft": false,
  "send": true,
  "emailTemplateId": "template_invoice"
}

Schnellstart

In wenigen Minuten zum ersten API-Request

Die Integration braucht keinen OAuth-Flow und keine lokale SDK-Installation. Ein Secret, eine Base URL und JSON reichen für den ersten Test.

1. Token erzeugen

Erstelle in Billutant einen API-Token und speichere ihn im externen System als Secret.

2. Test-Host nutzen

Starte gegen die Test-Umgebung, bis Payload, Status und Versand sauber funktionieren.

3. Request senden

Sende JSON mit customerId und itemIds an /invoices. Produktion braucht später nur die andere Base URL.

Zugriff

Base URLs und Authentifizierung

Tokens werden in Billutant in den Einstellungen erzeugt. Jede Anfrage verwendet den Header Authorization: Bearer TOKEN und wird automatisch rate-limited.

API Hosts

Produktion und Test nutzen jeweils denselben Pfad unter /api/v1.

Produktionhttps://app.billutant.com/api/v1

Testhttps://test.billutant.com/api/v1

Bearer Token

Der Token ist nur einmal sichtbar. Speichere ihn im externen Tool als Secret.

Header

Authorization: Bearer bt_live_...

JSON Requests

Schreibende Requests verwenden application/json. GET-Endpunkte brauchen keinen Body.

Header

Content-Type: application/json

Rate Limit

Standardmäßig sind 60 Requests pro Minute und Token vorgesehen. Bei Überschreitung antwortet die API mit 429.

Endpunkte

Rechnungen, Kunden, Artikel und Vorlagen

Die Rechnungs-API bleibt bewusst schlank: Kunden und Artikel werden per ID referenziert, das Rechnungsdatum setzt Billutant automatisch.

POST

/invoices

Rechnung erstellen

Erstellt eine Rechnung aus vorhandener Kunden-ID und Artikel-IDs. Optional direkt senden.

GET

/invoices

Rechnungen listen

Liefert die Rechnungen des verbundenen Billutant Mandanten.

GET

/invoices/{id}

Rechnung abrufen

Liest eine einzelne Rechnung, wenn sie zum Mandanten des Tokens gehört.

PATCH

/invoices/{id}

Entwurf aktualisieren

Aktualisiert nur Rechnungen im Status Entwurf. Finalisierte Rechnungen bleiben gesperrt.

POST

/invoices/{id}/send

Rechnung senden

Sendet eine bestehende, nicht als Entwurf gespeicherte Rechnung mit emailTemplateId.

DELETE

/invoices/{id}

Nicht erlaubt

Rechnungen können über die API nicht gelöscht werden.

Invoice Payload

Minimaler Request

customerId und itemIds sind Pflicht. send versendet automatisch, wenn eine gültige emailTemplateId übergeben wird und der Kunde eine gültige E-Mail-Adresse hat.

createDate wird nicht akzeptiert und von Billutant gesetzt.

draft: true erstellt einen Entwurf.

draft und send können nicht gleichzeitig true sein.

PATCH /invoices/{id} kann Entwürfe ändern, aber nicht senden.

POST /invoices/{id}/send braucht nur emailTemplateId im Body.

DELETE /invoices/{id} ist gesperrt.

curl

curl -X POST https://test.billutant.com/api/v1/invoices \
  -H "Authorization: Bearer bt_live_..." \
  -H "Content-Type: application/json" \
  -d '{"customerId":"customer_123","itemIds":["item_setup"],"send":false}'

Response

{
  "success": true,
  "data": {
    "id": "invoice_123",
    "invoiceNumber": "2026-0012",
    "status": "pending",
    "customerId": "customer_123",
    "files": ["2026-0012.pdf"],
    "sent": true,
    "draft": false
  }
}

Fehlerbehandlung

Statuscodes zuerst behandeln

Für robuste Integrationen sollte der Client zuerst den HTTP-Status auswerten und erst danach die JSON-Antwort weiterverarbeiten.

200 / 201

Erfolgreich

Der Request wurde verarbeitet. Bei POST /invoices enthält data die erstellte Rechnung.

400

Payload prüfen

Pflichtfelder fehlen oder Regeln wie draft und send wurden verletzt.

401

Token prüfen

Der Bearer Token fehlt, ist ungültig oder wurde im externen Tool falsch gespeichert.

403

Feature aktivieren

Die External Invoice API ist für den verbundenen Mandanten noch nicht freigeschaltet.

404

Ressource prüfen

Die angefragte ID existiert nicht oder gehört nicht zum Mandanten des Tokens.

405

Methode wechseln

Die Route existiert, aber die HTTP-Methode ist dort nicht erlaubt, zum Beispiel DELETE /invoices/{id}.

429

Retry später

Das Rate Limit wurde erreicht. Clients sollten verzögert erneut senden.

Fetch Beispiel

async function createBillutantInvoice(token) {
  const response = await fetch('https://test.billutant.com/api/v1/invoices', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${token}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      customerId: 'customer_123',
      itemIds: ['item_setup'],
      send: false,
    }),
  });

  const payload = await response.json();

  if (!response.ok) {
    throw new Error(payload.error || `Billutant API request failed with ${response.status}`);
  }

  return payload.data;
}

Error Response

{
  "success": false,
  "error": "emailTemplateId is required when send is true."
}

CRUD

Stammdaten für externe Workflows

Kunden, Artikel und E-Mail-Vorlagen können direkt über die API gepflegt werden, damit externe Systeme keine manuellen Vorarbeiten in Billutant brauchen.

GET

/customers

Kunden listen

Liste vorhandener Kunden für die Auswahl in externen Tools.

POST

/customers

Kunden erstellen

Legt einen Kunden an. Firma, Name oder E-Mail ist als Identifikation erforderlich.

GET

/customers/{id}

Kunde abrufen

Liest einen einzelnen Kunden, wenn er zum Mandanten des Tokens gehört.

PATCH

/customers/{id}

Kunden aktualisieren

Ändert Stammdaten eines vorhandenen Kunden.

DELETE

/customers/{id}

Kunden löschen

Löscht Kunden, wenn externe Workflows das ausdrücklich brauchen.

GET

/items

Artikel listen

Liest Produkte und Leistungen, die als Rechnungspositionen genutzt werden.

POST

/items

Artikel erstellen

Speichert eine Leistung mit Name, Beschreibung, Preis, Steuer und Einheit.

GET

/items/{id}

Artikel abrufen

Liest ein einzelnes Produkt oder eine Leistung aus dem verbundenen Mandanten.

PATCH

/items/{id}

Artikel aktualisieren

Ändert Name, Beschreibung, Preis, Steuer oder Einheit eines Artikels.

DELETE

/items/{id}

Artikel löschen

Löscht einen Artikel, wenn externe Workflows ihn nicht mehr benötigen.

GET

/email-templates

Vorlagen listen

Liest E-Mail-Vorlagen, die beim automatischen Versand verwendet werden.

POST

/email-templates

Vorlagen erstellen

Erstellt eine Vorlage mit Typ, Label, Betreff und Body für den Rechnungsversand.

GET

/email-templates/{id}

Vorlage abrufen

Liest eine einzelne E-Mail-Vorlage aus dem verbundenen Mandanten.

PATCH

/email-templates/{id}

Vorlage aktualisieren

Aktualisiert Typ, Label, Betreff, Body oder Mahnparameter einer Vorlage.

DELETE

/email-templates/{id}

Vorlage löschen

Löscht eine E-Mail-Vorlage, wenn sie nicht mehr genutzt wird.

Startbereit

Token erstellen und ersten Test-Request senden

Nutze zuerst die Test-Umgebung. Wenn Payload und Versand passen, stellst du im externen Tool nur die Base URL auf Produktion um.

Zu den Einstellungen

POST /invoices Authorization: Bearer bt_live_... Content-Type: application/json { "customerId": "customer_123", "itemIds": ["item_setup", "item_monthly"], "draft": false, "send": true, "emailTemplateId": "template_invoice" }

Minimaler Request

customerId und itemIds sind Pflicht. send versendet automatisch, wenn eine gültige emailTemplateId übergeben wird und der Kunde eine gültige E-Mail-Adresse hat.

createDate wird nicht akzeptiert und von Billutant gesetzt.

draft: true erstellt einen Entwurf.

draft und send können nicht gleichzeitig true sein.

PATCH /invoices/{id} kann Entwürfe ändern, aber nicht senden.

POST /invoices/{id}/send braucht nur emailTemplateId im Body.

DELETE /invoices/{id} ist gesperrt.

curl -X POST https://test.billutant.com/api/v1/invoices \ -H "Authorization: Bearer bt_live_..." \ -H "Content-Type: application/json" \ -d '{"customerId":"customer_123","itemIds":["item_setup"],"send":false}'

{ "success": true, "data": { "id": "invoice_123", "invoiceNumber": "2026-0012", "status": "pending", "customerId": "customer_123", "files": ["2026-0012.pdf"], "sent": true, "draft": false } }

Statuscodes zuerst behandeln

Für robuste Integrationen sollte der Client zuerst den HTTP-Status auswerten und erst danach die JSON-Antwort weiterverarbeiten.

200 / 201

Erfolgreich

Der Request wurde verarbeitet. Bei POST /invoices enthält data die erstellte Rechnung.

400

Payload prüfen

Pflichtfelder fehlen oder Regeln wie draft und send wurden verletzt.

401

Token prüfen

Der Bearer Token fehlt, ist ungültig oder wurde im externen Tool falsch gespeichert.

403

Feature aktivieren

Die External Invoice API ist für den verbundenen Mandanten noch nicht freigeschaltet.

404

Ressource prüfen

Die angefragte ID existiert nicht oder gehört nicht zum Mandanten des Tokens.

405

Methode wechseln

Die Route existiert, aber die HTTP-Methode ist dort nicht erlaubt, zum Beispiel DELETE /invoices/{id}.

429

Retry später

Das Rate Limit wurde erreicht. Clients sollten verzögert erneut senden.

async function createBillutantInvoice(token) { const response = await fetch('https://test.billutant.com/api/v1/invoices', { method: 'POST', headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ customerId: 'customer_123', itemIds: ['item_setup'], send: false, }), }); const payload = await response.json(); if (!response.ok) { throw new Error(payload.error || `Billutant API request failed with ${response.status}`); } return payload.data; }