API-Dokumentation

Einführung

Die API bildet genau den Ablauf ab, den auch die Website unter arbeitszeugnisschreiben.de nutzt. Sie übergeben die Angaben aus dem Fragebogen: Art des Zeugnisses, Mitarbeiter, Position, Beschäftigungszeitraum, Aufgaben und die Bewertung als Schulnote. Daraus entsteht ein vollständiges Zeugnis mit Einleitung, Unternehmensbeschreibung, Aufgabenbeschreibung, Leistungs- und Verhaltensbeurteilung und passender Schlussformel.

Typische Nutzer sind Personal- und Lohnbuchhaltungssoftware, Steuerkanzleien und Lohnbüros, die Zeugnisse für ihre Mandanten vorbereiten, sowie Betriebe mit eigener HR-Lösung, die das Zeugnis direkt aus der Personalakte heraus erzeugen wollen.

Alle Anfragen gehen an https://api.arbeitszeugnisschreiben.de/v1. Die API spricht ausschließlich HTTPS, nimmt JSON entgegen und antwortet mit JSON. Fachliche Felder heißen wie im Fragebogen der Website (zeugnisart, gesamtnote, aufgaben), technische Felder wie in jeder anderen API (id, status, metadata).

Zugang

Es gibt bewusst keine Selbstregistrierung. Wir schalten Schlüssel von Hand frei, weil über die API personenbezogene Daten von Beschäftigten laufen und wir vorher wissen möchten, wer sie schickt und wofür. In der Praxis ist das eine kurze E-Mail und ein Werktag Wartezeit.

Schreiben Sie an [email protected] und nennen Sie vier Dinge:

• Was Sie anbinden möchten, in zwei bis drei Sätzen.
• Ungefähres Volumen pro Monat.
• Wer bezahlt: Ihre Endkunden einzeln oder Sie gesammelt per Rechnung.
• Ob Sie Webhooks empfangen können oder lieber abfragen.

Sie erhalten zwei Schlüssel: einen Testschlüssel mit dem Präfix sk_test_, der nichts kostet und feste Beispielzeugnisse liefert, und einen Liveschlüssel mit dem Präfix sk_live_. Beide funktionieren sofort für alle Endpunkte.

Authentifizierung

Jede Anfrage trägt den Schlüssel im Authorization-Header als Bearer-Token. Anfragen ohne gültigen Header beantwortet die API mit 401 und dem Fehlertyp authentication_error.

curl https://api.arbeitszeugnisschreiben.de/v1/zeugnisse \
  -H "Authorization: Bearer $AZS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "zeugnisart": "endzeugnis",
    "perspektive": "arbeitgeber",
    "mitarbeiter_name": "Julia Becker",
    "position": "Sachbearbeiterin Buchhaltung",
    "eintrittsdatum": "2021-04-01",
    "austrittsdatum": "2026-09-30",
    "firma_name": "Muster Haustechnik GmbH",
    "aufgaben": "Kreditorenbuchhaltung, Zahlungsverkehr, Vorbereitung der Monatsabschlüsse, Ansprechpartnerin für den Steuerberater",
    "gesamtnote": 2,
    "austrittsgrund": "eigener_wunsch"
  }'

Behandeln Sie den Schlüssel wie ein Passwort: nur serverseitig verwenden, nie im Browser, nie in einem öffentlichen Repository. Kommt ein Schlüssel abhanden, sperren wir ihn auf Zuruf sofort und stellen einen neuen aus. Ein Konto darf mehrere aktive Schlüssel haben, damit sich ein Wechsel ohne Ausfall durchführen lässt.

Test- und Liveschlüssel nutzen denselben Endpunkt. Ob eine Anfrage im Testmodus lief, steht im Feld livemode jedes Objekts.

Schnellstart

Ein Zeugnis zu erstellen ist ein einziger Aufruf. Die Antwort kommt sofort mit einer Zeugnis-ID und dem Status queued, der Text entsteht im Hintergrund, in der Regel in unter einer Minute.

import os, time, requests

API = "https://api.arbeitszeugnisschreiben.de/v1"
HEAD = {"Authorization": "Bearer " + os.environ["AZS_API_KEY"]}

z = requests.post(f"{API}/zeugnisse", headers=HEAD, json={
    "zeugnisart": "zwischenzeugnis",
    "perspektive": "arbeitgeber",
    "mitarbeiter_name": "Murat Yilmaz",
    "position": "Elektroniker für Energie- und Gebäudetechnik",
    "eintrittsdatum": "2019-08-01",
    "fuehrungskraft": False,
    "firma_name": "Muster Haustechnik GmbH",
    "firma_branche": "Elektrohandwerk, 25 Mitarbeitende",
    "aufgaben": "Installation und Prüfung von Anlagen in Neubau und Bestand, "
                "Fehlersuche, Betreuung von Wartungskunden, Anleitung von Auszubildenden",
    "besondere_leistungen": "Hat 2024 die E-Mobilität im Betrieb aufgebaut",
    "gesamtnote": 1,
}).json()

while z["status"] in ("queued", "generating"):
    time.sleep(3)
    z = requests.get(f"{API}/zeugnisse/{z['id']}", headers=HEAD).json()

print(z["status"])          # ready
print(z["preview_text"])    # die ersten 200 Wörter, kostenlos

Das Beispiel fragt der Einfachheit halber alle drei Sekunden ab. Im Produktivbetrieb sind Webhooks der bessere Weg, sie sind weiter unten beschrieben.

Das wichtigste Feld ist aufgaben. Je konkreter die Tätigkeiten beschrieben sind, desto genauer wird die Aufgabenbeschreibung im Zeugnis. Stichpunkte reichen völlig, ganze Sätze sind nicht nötig. Die Formulierung in Zeugnissprache übernehmen wir.

Endpunkte im Überblick

Zeugnis erstellen

POST /v1/zeugnisse nimmt die Angaben entgegen und beginnt sofort mit der Erstellung. Pflicht sind sechs Felder, dazu je nach Zeugnisart die Note und das Austrittsdatum (siehe nächster Abschnitt). Alles andere ist optional und macht das Zeugnis genauer.

import { randomUUID } from "node:crypto";

const res = await fetch("https://api.arbeitszeugnisschreiben.de/v1/zeugnisse", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.AZS_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": randomUUID(),
  },
  body: JSON.stringify({
    zeugnisart: "endzeugnis",
    perspektive: "arbeitnehmer",
    mitarbeiter_name: "Sandra Wolf",
    position: "Teamleiterin Kundenservice",
    eintrittsdatum: "2018-01-15",
    austrittsdatum: "2026-10-31",
    fuehrungskraft: true,
    firma_name: "Beispiel Versand AG",
    aufgaben: "Leitung eines Teams von acht Mitarbeitenden, Schichtplanung, Eskalationen, Einarbeitung neuer Kolleginnen und Kollegen",
    gesamtnote: 2,
    teilnoten: { fuehrung: 1, sozialverhalten: 1 },
    austrittsgrund: "eigener_wunsch",
    metadata: { personalnummer: "4711" },
  }),
});
const zeugnis = await res.json();

Zeugnisarten und Regeln

Die drei Zeugnisarten unterscheiden sich in Aufbau und Pflichtangaben. Die API prüft das beim Erstellen und lehnt widersprüchliche Angaben mit validation_error ab, statt stillschweigend etwas wegzulassen.

Noten und Zeugnissprache

Sie geben Schulnoten an, die Übersetzung in Zeugnissprache übernehmen wir. Die Gesamtnote 1 wird zu "stets zu unserer vollsten Zufriedenheit", die 3 zu "zu unserer vollen Zufriedenheit". Doppeldeutige Formulierungen und versteckte Codes verwenden wir nicht, das Zeugnis ist wohlwollend und wahr im Sinne von § 109 GewO.

Eine Teilnote fuehrung ist nur erlaubt, wenn fuehrungskraft wahr ist. Ohne Führungsverantwortung fehlt dieser Baustein bewusst, und das ist im Zeugnis neutral.

Das Zeugnis-Objekt

Jeder Endpunkt, der ein einzelnes Zeugnis zurückgibt, liefert dasselbe Objekt. Felder, die noch nicht feststehen, sind null und füllen sich im Lauf der Erstellung.

{
  "id": "zgn_8Kq2mV4tRx",
  "object": "zeugnis",
  "status": "queued",
  "zeugnisart": "endzeugnis",
  "perspektive": "arbeitgeber",
  "mitarbeiter_name": "Julia Becker",
  "gesamtnote": 2,
  "preview_text": null,
  "text": null,
  "word_count": null,
  "paid": false,
  "price": { "amount": 2999, "currency": "eur" },
  "corrections_left": 3,
  "created_at": "2026-09-29T09:14:03Z",
  "metadata": {},
  "livemode": true
}

{
  "id": "zgn_8Kq2mV4tRx",
  "object": "zeugnis",
  "status": "complete",
  "zeugnisart": "endzeugnis",
  "perspektive": "arbeitgeber",
  "mitarbeiter_name": "Julia Becker",
  "gesamtnote": 2,
  "preview_text": "Arbeitszeugnis\n\nFrau Julia Becker, geboren am ...",
  "text": "Arbeitszeugnis\n\nFrau Julia Becker, geboren am ...",
  "word_count": 412,
  "files": {
    "pdf": "https://files.arbeitszeugnisschreiben.de/z/zgn_8Kq2mV4tRx.pdf?sig=...",
    "docx": "https://files.arbeitszeugnisschreiben.de/z/zgn_8Kq2mV4tRx.docx?sig=...",
    "odt": "https://files.arbeitszeugnisschreiben.de/z/zgn_8Kq2mV4tRx.odt?sig=..."
  },
  "files_expire_at": "2026-09-30T09:15:40Z",
  "paid": true,
  "price": { "amount": 2999, "currency": "eur" },
  "corrections_left": 3,
  "created_at": "2026-09-29T09:14:03Z",
  "completed_at": "2026-09-29T09:15:40Z",
  "metadata": {},
  "livemode": true
}

Statuswerte

Ein Zeugnis durchläuft die Zustände in dieser Reihenfolge. complete und failed sind Endzustände. Eine Korrektur setzt ein Zeugnis kurz auf generating zurück, danach steht es wieder auf ready oder complete, je nachdem, ob es schon bezahlt war.

Ein einzelner fehlgeschlagener Versuch führt nicht sofort zu failed. Wir wiederholen intern und geben erst auf, wenn alle Versuche scheitern.

Abrufen und auflisten

GET /v1/zeugnisse/{id} liefert den aktuellen Stand eines Zeugnisses. Der Endpunkt darf im Sekundentakt abgefragt werden, solange das Ratelimit eingehalten wird.

curl -G https://api.arbeitszeugnisschreiben.de/v1/zeugnisse \
  -H "Authorization: Bearer $AZS_API_KEY" \
  -d status=complete \
  -d zeugnisart=endzeugnis \
  -d created_after=2026-09-01 \
  -d limit=50

Listen sind cursorbasiert. Sie erhalten höchstens limit Einträge, standardmäßig 20 und höchstens 100, absteigend nach Erstellungszeit. Ist has_more wahr, geben Sie next_cursor beim nächsten Aufruf als starting_after mit. Filtern lässt sich nach status, zeugnisart, paid sowie created_after und created_before.

{
  "object": "list",
  "data": [
    { "id": "zgn_8Kq2mV4tRx", "status": "complete", "zeugnisart": "endzeugnis", "...": "..." },
    { "id": "zgn_3Hn7pQ1wZc", "status": "complete", "zeugnisart": "endzeugnis", "...": "..." }
  ],
  "has_more": true,
  "next_cursor": "zgn_3Hn7pQ1wZc"
}

Text und Dateien

Vor der Freischaltung liefert die API die ersten 200 Wörter des fertigen Zeugnisses im Feld preview_text. Das ist keine gesonderte Kurzfassung, sondern der echte Anfang des Zeugnisses. Einleitung und Aufgabenbeschreibung lassen sich damit prüfen, die Bewertung folgt im gesperrten Teil.

Nach der Freischaltung gibt GET /v1/zeugnisse/{id}/text den vollständigen Text als text/plain zurück. GET /v1/zeugnisse/{id}/datei liefert die Datei im gewünschten Format, gesteuert über format=pdf, docx oder odt.

# Word-Datei zum Anpassen auf Firmenpapier
curl -L -o zeugnis.docx \
  "https://api.arbeitszeugnisschreiben.de/v1/zeugnisse/zgn_8Kq2mV4tRx/datei?format=docx" \
  -H "Authorization: Bearer $AZS_API_KEY"

Die Word-Datei ist für die Weiterbearbeitung gedacht: Übernahme auf Ihr Geschäftspapier, Ergänzungen, Unterschriftszeile. Das PDF ist ein neutral gesetztes Dokument ohne Briefkopf. Die Adressen im Feld files sind signiert und 24 Stunden gültig, ein erneuter Abruf des Zeugnisses erzeugt jederzeit frische.

Korrekturen

Stimmt ein Zeugnis nicht mit den Angaben überein, oder fehlt etwas, fordern Sie eine korrigierte Fassung an. POST /v1/zeugnisse/{id}/korrektur erzeugt eine neue Fassung unter derselben ID. Die vorherige bleibt unter previous_versions erhalten.

curl https://api.arbeitszeugnisschreiben.de/v1/zeugnisse/zgn_8Kq2mV4tRx/korrektur \
  -H "Authorization: Bearer $AZS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "hinweis": "Frau Becker hat zusätzlich die Umstellung auf DATEV Unternehmen online verantwortet. Bitte bei den Aufgaben ergänzen.",
    "aenderungen": { "besondere_leistungen": "Einführung von DATEV Unternehmen online 2025" }
  }'

Das Feld hinweis geht direkt in die Überarbeitung ein, also lohnt sich ein konkreter Satz. Im Objekt aenderungen stehen Felder aus dem ursprünglichen Auftrag, die sich ändern sollen, etwa eine andere Teilnote. Bis zu drei Korrekturen je Zeugnis sind kostenlos, vor und nach der Freischaltung.

Eine Korrektur ändert nie die Zeugnisart. Wer aus einem Zwischenzeugnis ein Endzeugnis machen will, erstellt ein neues Zeugnis.

Zeugnis-Analyse

Der zweite Dienst läuft in die Gegenrichtung: Sie schicken ein bestehendes Arbeitszeugnis als Text, und wir werten es aus. POST /v1/analysen nimmt das Feld zeugnis_text mit 200 bis 20.000 Zeichen entgegen. Namen dürfen Sie vorher schwärzen, die Analyse braucht sie nicht.

curl https://api.arbeitszeugnisschreiben.de/v1/analysen \
  -H "Authorization: Bearer $AZS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "zeugnis_text": "Herr Tobias Krämer, geboren am 12.03.1990, war vom 01.02.2022 bis 30.06.2026 ..."
  }'

Die Analyse enthält die Gesamtnote, ein Kurzfazit, fünf Teilnoten mit Begründung und wörtlichem Zitat, die auffälligste Formulierung, eine Detailanalyse Abschnitt für Abschnitt, fehlende Bausteine, Warnsignale sowie eine Empfehlung mit konkreten Alternativformulierungen. Anders als beim Erstellen reicht die Notenskala hier von 1 bis 6, weil fremde Zeugnisse auch ungenügend ausfallen können.

{
  "id": "ana_5Tf9kL2mNp",
  "object": "analyse",
  "status": "ready",
  "gesamtnote": "3 (befriedigend)",
  "kurzfazit": "Das Zeugnis klingt freundlich, liegt in der Leistungsbewertung aber nur im Bereich befriedigend. Die Schlussformel fehlt.",
  "teilnoten": [
    { "bereich": "Fachwissen", "note": "2", "begruendung": "\"umfassende und fundierte Fachkenntnisse\" steht für gut." },
    { "bereich": "Arbeitsweise", "note": "3", "begruendung": "\"arbeitete stets sorgfältig\" ohne Steigerung entspricht befriedigend." },
    { "bereich": "Erfolge", "note": null, "begruendung": null, "locked": true },
    { "bereich": "Sozialverhalten", "note": null, "begruendung": null, "locked": true },
    { "bereich": "Führung", "note": null, "begruendung": null, "locked": true }
  ],
  "text": null,
  "paid": false,
  "price": { "amount": 999, "currency": "eur" },
  "created_at": "2026-09-29T10:02:11Z",
  "livemode": true
}

Vor der Freischaltung sind Gesamtnote, Kurzfazit und die ersten beiden Teilnoten sichtbar. Die übrigen Teilnoten tragen locked: true, das Feld text mit der vollständigen Auswertung folgt nach Zahlung von 9,99 €. Checkout und Freischaltung funktionieren wie beim Zeugnis, unter /v1/analysen/{id}/checkout und /v1/analysen/{id}/unlock.

Bezahlen und freischalten

Es gibt zwei Wege, ein Zeugnis freizuschalten, je nachdem, wer bezahlt.

Der Endkunde bezahlt

POST /v1/zeugnisse/{id}/checkout erzeugt eine gehostete Bezahlseite mit Karte, PayPal, Klarna, Apple Pay, Google Pay und SEPA-Lastschrift. Sie leiten Ihren Kunden dorthin weiter und erhalten nach erfolgreicher Zahlung das Ereignis zeugnis.completed.

curl https://api.arbeitszeugnisschreiben.de/v1/zeugnisse/zgn_8Kq2mV4tRx/checkout \
  -H "Authorization: Bearer $AZS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "success_url": "https://ihre-software.de/zeugnis/fertig",
    "cancel_url": "https://ihre-software.de/zeugnis/abgebrochen",
    "customer_email": "[email protected]"
  }'

{
  "object": "checkout_session",
  "url": "https://pay.arbeitszeugnisschreiben.de/c/cs_7Rz1xW4q",
  "expires_at": "2026-09-30T09:20:00Z",
  "amount": 2999,
  "currency": "eur",
  "payment_methods": ["card", "paypal", "klarna", "apple_pay", "google_pay", "sepa_debit"]
}

Sie bezahlen

Bei Konten mit Sammelabrechnung schaltet POST /v1/zeugnisse/{id}/unlock das Zeugnis sofort frei und bucht 29,99 € auf die Monatsrechnung. Das ist der übliche Weg für Kanzleien, Lohnbüros und HR-Software, die Zeugnisse im Rahmen eines eigenen Angebots erstellen.

curl -X POST https://api.arbeitszeugnisschreiben.de/v1/zeugnisse/zgn_8Kq2mV4tRx/unlock \
  -H "Authorization: Bearer $AZS_API_KEY"

Betriebe mit einem Zeugnis-Abo zu 49,99 € pro Monat können ihren Abo-Schlüssel ebenfalls für die API nutzen. /unlock bucht dann nichts, solange die Nutzung im üblichen Rahmen für das eigene Unternehmen bleibt. Das Abo deckt keine Zeugnisse für Dritte als eigene Dienstleistung ab, dafür ist die Sammelabrechnung da.

Gültige Werte

Die Aufzählungen für Zeugnisart, Perspektive, Austrittsgrund und Dateiformat können sich erweitern. Statt sie fest einzubauen, fragen Sie GET /v1/optionen ab und halten das Ergebnis ein paar Stunden im Cache.

{
  "zeugnisart": ["endzeugnis", "zwischenzeugnis", "einfaches_zeugnis"],
  "perspektive": ["arbeitgeber", "arbeitnehmer"],
  "noten": [1, 2, 3, 4, 5],
  "teilnoten": ["fachwissen", "arbeitsweise", "erfolge", "sozialverhalten", "fuehrung"],
  "austrittsgrund": ["eigener_wunsch", "betriebsbedingt", "einvernehmlich", "befristung"],
  "dateiformate": ["pdf", "docx", "odt"],
  "sprache": ["de"]
}

Zeugnisse entstehen derzeit ausschließlich auf Deutsch und nach deutschem Recht. Österreichische und Schweizer Zeugnisse folgen teils anderen Konventionen und sind noch nicht freigeschaltet.

Webhooks

Geben Sie beim Erstellen eine callback_url an, oder hinterlegen Sie eine Adresse für das ganze Konto. Wir schicken dann jedes Ereignis als POST dorthin.

{
  "id": "evt_2Lp8sD6vYt",
  "type": "zeugnis.ready",
  "created_at": "2026-09-29T09:14:51Z",
  "livemode": true,
  "data": {
    "id": "zgn_8Kq2mV4tRx",
    "object": "zeugnis",
    "status": "ready",
    "zeugnisart": "endzeugnis",
    "paid": false,
    "metadata": { "personalnummer": "4711" }
  }
}

Signatur prüfen

Jede Zustellung trägt einen Header mit Zeitstempel und HMAC-SHA256 über Zeitstempel, Punkt und Rohkörper. Prüfen Sie ihn, bevor Sie dem Inhalt vertrauen, und verwerfen Sie alles, was älter als fünf Minuten ist.

AZS-Signature: t=1790500491,v1=5f1c0a9e3b7d...

import hmac, hashlib, os, time

SECRET = os.environ["AZS_WEBHOOK_SECRET"].encode()

def verify(header: str, raw_body: bytes) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    ts, sig = parts["t"], parts["v1"]
    if abs(time.time() - int(ts)) > 300:
        return False
    expected = hmac.new(SECRET, ts.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, sig)

Wiederholungen

Wir erwarten innerhalb von zehn Sekunden eine Antwort mit Status 2xx. Bleibt sie aus, wiederholen wir mit wachsendem Abstand acht Mal über 24 Stunden. Zustellungen können sich dabei doppeln, behandeln Sie Ihren Endpunkt deshalb idempotent und richten Sie sich nach created_at, nicht nach der Ankunftszeit.

Die Payloads enthalten bewusst keinen Zeugnistext und keine Namen außer denen in metadata. Den Inhalt holen Sie danach über die API ab. So landen keine Beschäftigtendaten in Protokollen von Zwischenstationen.

Idempotenz

Jeder POST akzeptiert den Header Idempotency-Key mit einem beliebigen eindeutigen Wert, üblicherweise einer UUID. Kommt derselbe Schlüssel innerhalb von 24 Stunden erneut an, geben wir die ursprüngliche Antwort zurück, statt ein zweites Zeugnis zu erstellen.

curl https://api.arbeitszeugnisschreiben.de/v1/zeugnisse \
  -H "Authorization: Bearer $AZS_API_KEY" \
  -H "Idempotency-Key: 9b1d4f0e-6c1a-4d8b-a0f2-3e7c5b2a1d90" \
  -H "Content-Type: application/json" \
  -d @zeugnis.json

Das schützt vor doppelten Zeugnissen, wenn bei einem Netzwerkfehler die Antwort verlorengeht und Ihr Code die Anfrage wiederholt. Derselbe Schlüssel mit abweichendem Inhalt führt zu 409 und dem Fehlertyp conflict.

Fehler

Fehler kommen immer im selben Format, mit maschinenlesbarem type und code, einer lesbaren deutschen Meldung und, wo sinnvoll, dem betroffenen Feld. Die request_id gehört in jede Supportanfrage.

{
  "error": {
    "type": "validation_error",
    "code": "grade_not_allowed",
    "message": "Ein einfaches Zeugnis enthält keine Bewertung. Bitte gesamtnote und teilnoten weglassen oder zeugnisart auf endzeugnis setzen.",
    "field": "gesamtnote",
    "request_id": "req_4Wm9bK1xQs"
  }
}

Bei 429 und 5xx ist eine Wiederholung sinnvoll, am besten mit exponentiell wachsendem Abstand. Bei anderen 4xx-Antworten nicht, dieselbe Anfrage scheitert erneut.

Limits

Jede Antwort trägt den aktuellen Stand in den Headern.

RateLimit-Limit: 60
RateLimit-Remaining: 57
RateLimit-Reset: 34

Höhere Limits sind möglich, sie sind nur nicht voreingestellt. Wenn Ihr Volumen wächst, schreiben Sie uns kurz.

Versionierung

Die Hauptversion steht im Pfad und bleibt stabil. Innerhalb von v1 kommen nur additive Änderungen: neue Felder, neue Werte in Aufzählungen, neue Endpunkte. Bestehende Felder verschwinden nicht und ändern ihre Bedeutung nicht.

Wer sich zusätzlich absichern will, legt einen Stichtag im Header fest. Ohne Header gilt immer der neueste Stand.

AZS-Version: 2026-09-01

Ihr Code sollte unbekannte Felder in Antworten ignorieren, statt an ihnen zu scheitern. Das ist die einzige Annahme, die wir an Clients stellen.

Testmodus

Schlüssel mit dem Präfix sk_test_ nutzen dieselben Endpunkte, erstellen aber keine echten Zeugnisse und kosten nichts. Sie erhalten nach wenigen Sekunden ein festes Beispielzeugnis passend zur Zeugnisart, und alle Objekte tragen livemode: false. Schicken Sie im Testmodus bitte keine echten Beschäftigtendaten.

Bestimmte Werte im Feld mitarbeiter_name erzwingen einen bestimmten Ausgang: test_fail führt zu failed, test_slow zu einer Erstellung von etwa drei Minuten, test_ratelimit zu einer 429-Antwort. So lässt sich die Fehlerbehandlung prüfen, ohne auf einen echten Ausfall zu warten.

Webhooks funktionieren im Testmodus ebenfalls, mit demselben Signaturverfahren und einem eigenen Geheimnis.

Recht und Datenschutz

Die API erstellt Zeugnisentwürfe als Formulierungshilfe. Wirksam wird ein Zeugnis erst, wenn der Arbeitgeber es auf Geschäftspapier ausstellt und eine vertretungsberechtigte Person unterschreibt (§ 109 GewO). Für die inhaltliche Richtigkeit der übergebenen Angaben ist der Auftraggeber verantwortlich. Die API ersetzt keine Rechtsberatung.

Am fertigen Text erhalten Sie ein uneingeschränktes Nutzungsrecht. Sie dürfen ihn bearbeiten, ausdrucken, an Ihre Kunden weitergeben und in Ihr eigenes Produkt einbetten. Bei Einzelkäufen gilt zusätzlich unsere Geld-zurück-Garantie innerhalb von 24 Stunden.

Über die API laufen personenbezogene Daten von Beschäftigten. Sie sind dafür der Verantwortliche im Sinne der DSGVO, wir der Auftragsverarbeiter. Einen Auftragsverarbeitungsvertrag erhalten Sie mit dem Schlüssel. Wir verwenden die Angaben ausschließlich für das jeweilige Zeugnis und nicht zum Training von Modellen.

Zeugnisse, Analysen und Eingaben bewahren wir 90 Tage auf und löschen sie danach. Mit DELETE /v1/zeugnisse/{id} geht es sofort. Geburtsdatum und Firmenbeschreibung sind optional, schicken Sie nur, was im Zeugnis stehen soll.

Support

Fragen, höhere Limits, Sammelabrechnung, Auftragsverarbeitungsvertrag: [email protected]. Nennen Sie bei technischen Problemen die request_id aus der Fehlerantwort, dann finden wir den Vorgang direkt.

Für Integrationen über KI-Agenten gibt es zusätzlich einen MCP-Server. Er ist unter /mcp/ dokumentiert und nutzt dieselben Schlüssel wie die REST-API.