API & Integrationen

Die API von Blina Desk

Blina Desk muss nicht Ihr einziges Programm sein. Über die REST-API lesen und schreiben Ihre anderen Systeme dieselben Daten, die Sie in der Oberfläche sehen, mit denselben Regeln.

Was Sie damit machen können

Dokumente & Suche

Dokumente auflisten, herunterladen und hochladen, Ordner durchgehen, im Volltext suchen. Was Sie hochladen, wird wie jeder andere Upload verarbeitet: Virenprüfung, OCR, Indizierung.

Kunden & Kontakte

Firmen und Ansprechpartner lesen, anlegen und ändern, dieselben Pflichtfelder und dieselbe Historie wie im CRM.

Aufträge & Rechnungen

Anlegen, Positionen hinzufügen, Status setzen. Die Belegnummer vergibt der Server, die Summen rechnet die Datenbank: kein Client kann sie überschreiben.

Eingangsrechnungen auslesen

Lieferantenrechnungen und ihre Positionen lesen Sie über die API. Angelegt werden sie von der EN-16931-Prüfung mit Dublettenerkennung, damit jede Rechnung denselben Weg nimmt wie im Programm.

BASE="https://api.blina-desk.com/api/v1"

curl -s "$BASE/documents?limit=5" -H "Authorization: Bearer $BDK"
curl -s "$BASE/accounts?q=gmbh"   -H "Authorization: Bearer $BDK"
curl -s "$BASE/search?q=vertrag"  -H "Authorization: Bearer $BDK"

Sehen statt lesen

Aufgenommen im laufenden Programm, mit echten Daten — keine Animation.

Schlüssel und BerechtigungenDie Schlüssel erzeugt das Unternehmen selbst, im Klartext genau einmal, mit einzeln gewählten Rechten.
Webhooks, Archiv, VerbrauchSignierte Ereignisse mit der Uhrzeit in der Signatur, und eine Warteschlange, die es erneut versucht.

So fangen Sie an

  1. Im Verwaltungsbereich unter „API und Integrationen" einen Schlüssel erstellen und die Rechte vergeben, die er haben soll. Den Schlüssel im Klartext sehen Sie genau einmal, wir speichern nur seinen Hash.
  2. Den Schlüssel als Bearer-Token mitschicken. Der erste Aufruf, der antwortet, sagt Ihnen, für welches Unternehmen er gilt.
  3. Lesen, schreiben, und für alles Weitere Webhooks abonnieren statt zu pollen.
# Kopf, die Belegnummer vergibt der Server
curl -s -X POST "$BASE/invoices" \
  -H "Authorization: Bearer $BDK" -H "Content-Type: application/json" \
  -d '{"account_id":"...","issue_date":"2026-07-29"}'
# {"id":"...","invoice_no":"INV-000042","status":"draft","total":0.0}

# Positionen, die Summen rechnet die Datenbank
curl -s -X POST "$BASE/invoices/$ID/lines" \
  -H "Authorization: Bearer $BDK" -H "Content-Type: application/json" \
  -d '{"name":"Beratung","qty":3,"unit_price":100,"vat_rate":19}'
# {"id":"...","total":357.0}   <- 3 x 100 + 19%

Webhooks: Sie erfahren es, ohne zu fragen

Statt regelmäßig nachzusehen, ob sich etwas geändert hat, lassen Sie sich benachrichtigen. Jede Zustellung ist signiert, prüfen Sie die Signatur, bevor Sie den Inhalt verwenden.

  • Die Adresse muss öffentliches https sein: private, Loopback- und Link-local-Adressen werden abgelehnt, bei der Registrierung und erneut bei jeder Zustellung.
  • Antworten Sie 2xx, sobald Sie das Ereignis gespeichert haben. Alles andere gilt als Fehlschlag und wird wiederholt: 0s → 30s → 5m → 30m → 2h.
  • Nach fünf erschöpften Zustellungen in Folge wird der Endpunkt ausgesetzt und von Ihnen wieder aktiviert.
  • Eine Zustellung kann mehrfach ankommen: entscheiden Sie anhand der Ereignis-ID, ob Sie sie schon kennen.

Signatur prüfen, nicht optional

Rechnen Sie über den rohen Body, vor jedem JSON-Parsing: neu serialisieren ändert die Bytes und der Vergleich schlägt fehl. Weisen Sie ab, was nicht verifiziert, und was älter als fünf Minuten ist, auch bei korrektem MAC.

import hashlib, hmac, time

def verify(secret: str, raw_body: bytes, header: str, tolerance: int = 300) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    ts, sig = int(parts["t"]), parts["v1"]
    if abs(time.time() - ts) > tolerance:      # anti-replay
        return False
    expected = hmac.new(secret.encode(), f"{ts}.".encode() + raw_body,
                        hashlib.sha256).hexdigest()
    return hmac.compare_digest(sig, expected)  # confronto a tempo costante

Kontingente und Sicherheit

  • 120 Aufrufe pro Minute und 20.000 pro Tag je Schlüssel. Jede erfolgreiche Antwort sagt Ihnen, wo Sie stehen; darüber kommt 429 mit Retry-After.
  • Jeder Schlüssel trägt nur die Rechte, die Sie ihm geben, Dokumente, Suche, CRM, Verkauf, Einkauf, Webhooks, einzeln vergeben.
  • Jede Antwort trägt eine X-Request-Id: nennen Sie sie, und wir können genau nachvollziehen, was passiert ist.
X-RateLimit-Limit-Minute: 120
X-RateLimit-Remaining-Minute: 118
X-RateLimit-Limit-Day: 20000
X-RateLimit-Remaining-Day: 19863