API v1

blapier in deiner Software.

Eine REST-Schnittstelle, zwei Aufrufe: Brief hochladen, Ergebnis abholen. Dazu auf Wunsch der fertige Entwurf. Alle Antworten sind JSON, alle Texte Deutsch, die KI läuft über GemeinsamKI.de in Deutschland.

KI kann Fehler machen. blapier liest, erklärt und bereitet vor – die Abnahme macht immer ein Mensch. Du prüfst Frist, Betrag und Text, bevor etwas rausgeht. Für API-Nutzer heißt das: Zeigt eurem Kunden Frist und Betrag zur Bestätigung, bevor etwas rausgeht. Jede Antwort enthält diesen Hinweis im Feld hinweis.

Schlüssel

Konto anlegen, in den Einstellungen einen Schlüssel erzeugen. Er beginnt mit blp_ und wird nur einmal angezeigt. Jede Anfrage trägt ihn im Header:

Authorization: Bearer blp_…

Limit: 30 Anfragen pro Minute. Die API ist immer dabei. Jede Auswertung zieht ein Dokument vom Guthaben ab: die ersten 2 sind geschenkt, danach Prepaid ohne Abo, 5 Dokumente für 1,99 € oder 50 für 9,99 €.

Auswertung anlegen

POST /api/v1/analysen – als multipart/form-data mit Feld datei (PDF, JPG, PNG, WEBP, bis 20 MB) oder als application/json mit Feld text, wenn ihr den Text schon habt.

curl -X POST https://blapier.de/api/v1/analysen \
  -H "Authorization: Bearer blp_…" \
  -F "datei=@bussgeld.pdf"

# oder mit Text
curl -X POST https://blapier.de/api/v1/analysen \
  -H "Authorization: Bearer blp_…" \
  -H "Content-Type: application/json" \
  -d '{"text": "Zentrale Bußgeldstelle … Geldbuße 58,50 EUR …", "name": "bussgeld-4711"}'

Antwort 202 Accepted:

{"id": 4711, "status": "analyse", "fertig": false,
 "url": "https://blapier.de/api/v1/analysen/4711"}

Ergebnis abholen

GET /api/v1/analysen/{id} – alle zwei Sekunden abfragen, bis fertig wahr ist. Meist dauert es unter einer Minute.

{
  "id": 4711, "status": "verstanden", "fertig": true, "demo": false,
  "analyse": {
    "absender": "Zentrale Bußgeldstelle Viechtach",
    "absender_adresse": "Postfach 1, 94234 Viechtach",
    "dokument_art": "Bußgeldbescheid",
    "betreff": "Geschwindigkeitsüberschreitung 21 km/h",
    "aktenzeichen": "123.456.789",
    "zusammenfassung": "…drei Sätze…",
    "frist": "2026-11-30", "frist_hinweis": "2 Wochen ab Zustellung",
    "betrag": "87.00", "iban": "DE89370400440532013000", "verwendungszweck": "123.456.789",
    "wenn_nichts_passiert": "…", "risiko": "hoch",
    "optionen": [
      {"id": "einspruch", "art": "widerspruch", "titel": "Einspruch einlegen", "beschreibung": "…", "empfohlen": true},
      {"id": "zahlen", "art": "zahlen", "titel": "Bezahlen", "beschreibung": "…", "empfohlen": false}
    ],
    "fehlende_angaben": ["Fahrer am Tattag"],
    "sprache_einfach": "…"
  },
  "aufgabenplan": {"automatisch": ["…"], "selbst": ["…"]},
  "entwurf": null,
  "hinweis": "KI kann Fehler machen. …"
}

Werte für art: zahlen, widerspruch, antwort, kuendigung, weiterleiten, ablegen, anrufen, pruefen. risiko: niedrig, mittel, hoch. frist ist ISO-Datum oder leer, betrag eine Dezimalzahl als String oder leer.

Entwurf schreiben lassen

POST /api/v1/analysen/{id}/entwurf mit JSON {"option_id": "einspruch", "hinweise": "Ich war an dem Tag im Urlaub."}. Ohne option_id wird die empfohlene Option genommen. Für zahlen und ablegen gibt es keinen Brief. Antwort 202, danach steht der Text unter entwurf im Ergebnis.

"entwurf": {"betreff": "Einspruch gegen Bußgeldbescheid 123.456.789",
            "text": "Sehr geehrte Damen und Herren,\n\n…\n\nMit freundlichen Grüßen",
            "option_id": "einspruch"}

Formulare ausfüllen

Erkennt blapier ein Formular, enthält das Ergebnis formular mit titel, art (acro für echte PDF-Felder, sonst pdf_text, pdf_scan, bild), seiten (Bildgröße je Seite) und felder. Jedes Feld hat id, label, typ (text, datum, zahl, iban, kreuz, auswahl, unterschrift), pflicht, hinweis, gedaechtnis_schluessel, verortet und position: die erkannte Zielstelle auf dem Blatt. Felder vom Typ unterschrift zeigen, wo unterschrieben wird. Unterschriften nimmt die API nicht entgegen, blapier speichert grundsätzlich keine.

Positionen sind relativ zur Seite, Ursprung oben links: x und y von 0 bis 1 für die linke obere Ecke des Textes, groesse als Schriftgröße im Verhältnis zur Seitenhöhe (0.0125 entspricht etwa 10,5 pt auf A4), seite ab 0.

POST /api/v1/analysen/{id}/formular
{"werte": {"vorname": "Erika", "nachname": "Muster", "geburtsdatum": "01.02.1980", "einverstanden": "X"},
 "platzierung": [{"id": "vorname", "seite": 0, "x": 0.42, "y": 0.137, "groesse": 0.0125}]}

→ {"id": 4711, "ausgefuellt_url": "https://blapier.de/api/v1/analysen/4711/ausgefuellt.pdf",
   "im_anhang": [],
   "platzierung": [{"id": "vorname", "seite": 0, "x": 0.42, "y": 0.137, "groesse": 0.0125, "gesetzt": true}, …]}

platzierung ist freiwillig: Ohne Angabe setzt blapier jeden Wert an die erkannte Stelle, mit Angabe gilt eure Position für dieses Feld. So könnt ihr eurem Kunden dieselbe Korrektur anbieten wie der Editor im Konto. Angaben ohne Stelle stehen auf einer Anhangseite (im_anhang). Kreuze setzt ihr mit "X", Daten als TT.MM.JJJJ. Soll an einer Stelle etwas anderes stehen als die Angabe, gebt dem Platz ein "text" mit, zum Beispiel "X" im Kästchen „verheiratet“ statt des Wortes. Das Gedächtnis gibt es nur im Konto, nicht über die API.

Weitere Aufrufe

Fehler

Fehler kommen als JSON {"fehler": "…"} mit passendem Status: 401 Schlüssel ungültig, 402 Guthaben aufgebraucht, 413 Datei zu groß, 415 falscher Typ, 429 zu viele Anfragen.

Beispiel in Python

import time, requests

API = "https://blapier.de/api/v1"
H = {"Authorization": "Bearer blp_…"}

r = requests.post(f"{API}/analysen", headers=H, files={"datei": open("brief.pdf", "rb")})
url = r.json()["url"]
while True:
    d = requests.get(url, headers=H).json()
    if d["fertig"]:
        break
    time.sleep(2)
print(d["analyse"]["zusammenfassung"], d["analyse"]["frist"], d["analyse"]["betrag"])

Datenschutz

Dokumente werden auf Servern in Deutschland verarbeitet. Vor dem KI-Modell ersetzt die Clearingstelle von GemeinsamKI personenbezogene Daten durch Platzhalter. Für Unternehmen schließen wir einen Auftragsverarbeitungsvertrag: mail@resultos.com.

Konto anlegen und Schlüssel holen