API verwenden

Mit der SCFold-API kannst du Dokumente aus deinem eigenen Programm analysieren und die erkannten Werte als JSON abrufen. Du brauchst ein aktives Kundenkonto und einen eigenen API-Schlüssel. Diese Anleitung ist ohne Anmeldung lesbar; für die API-Aufrufe ist dein Schlüssel erforderlich.

1. Konto und API-Schlüssel vorbereiten

1. Erstelle ein Konto und bestätige deine E-Mail-Adresse. Die Schritte stehen unter Konto & Anmeldung.
2. Melde dich an und öffne deinen Dokumentenbereich.
3. Klappe API-Schlüssel auf, gib unter Name eine Bezeichnung ein, etwa „Meine Anwendung“, und wähle Schlüssel erstellen.
4. Kopiere den vollständigen Schlüssel sofort. Er wird nur einmal angezeigt; später siehst du eine maskierte Kennung. Du kannst höchstens 20 aktive Schlüssel haben.
5. Hinterlege den Schlüssel vertraulich in deiner Anwendung. Verwende ihn nur auf deinem Server oder in deinem eigenen lokalen Programm; veröffentliche ihn nicht in einer Webseite, einem Screenshot oder einem gemeinsamen Repository.

Über Widerrufen sperrst du einen Schlüssel sofort für weitere Aufrufe. Hast du ihn verloren, erstelle einen neuen und widerrufe den alten. Das Widerrufen löscht keine bereits analysierten Dokumente. Ein anderer gültiger Schlüssel desselben Kontos kann weiterhin auf deine noch verfügbaren Jobs zugreifen.

2. Gewünschte Ausgabefelder festlegen

Speichere im Dokumentenbereich unter Ausgabefelder die gewünschten Feldnamen, beispielsweise invoice_number und iban. Neue Analysen geben genau diese Schlüssel zurück. Erkannte Werte sind Strings; ein fehlender oder nicht sicher erkannter Wert ist echtes JSON-null.

Ohne gespeicherte Felder ist user_json ein leeres Objekt {}. Bereits angenommene ZIP-Aufträge behalten die bei ihrer Annahme gespeicherten Felder, auch wenn du das Profil anschließend änderst. Prüfe wichtige Werte am Original, bevor du sie weiterverwendest.

3. Welche Endpunkte gibt es?

Die folgenden Pfade gehören zur SCFold-Adresse. Jede Kundenanfrage braucht den Header Authorization: Bearer DEIN_API_SCHLUESSEL.

Schlüssel verwaltest du normalerweise im Kundenbereich. Für eine eigene Kontooberfläche gibt es außerdem GET und POST /api/v1/account/api-keys sowie DELETE /api/v1/account/api-keys/{key_id}. Diese verlangen eine angemeldete Kontositzung; Erstellen und Widerrufen brauchen zusätzlich den X-CSRFToken-Header. Ein API-Schlüssel allein reicht für die Schlüsselverwaltung nicht aus.

4. Beispiele vorbereiten

Die Beispiele verwenden curl in einer Bash-Shell. Setze die Adresse deiner SCFold-Installation. Der Schlüssel wird verdeckt abgefragt und erscheint dadurch nicht als Klartext im eingegebenen Befehl.

export SCFOLD_ORIGIN='https://scfold.leonlab.ai'
read -r -s -p 'SCFold API-Schlüssel: ' SCFOLD_API_KEY
export SCFOLD_API_KEY

Prüfe zuerst deinen Schlüssel:

curl --fail-with-body "$SCFOLD_ORIGIN/api/v1/customer/identity" \
  -H "Authorization: Bearer $SCFOLD_API_KEY"

Eine gültige Antwort sieht beispielsweise so aus:

{"authenticated":true,"user_id":42}

Die Dateien und URLs in den nächsten Beispielen ersetzt du durch deine eigenen. Die Download-URLs müssen öffentlich erreichbar sein; geschützte Downloads mit zusätzlichen Anmeldedaten werden nicht unterstützt.

5. Einzeldatei hochladen oder per URL analysieren

Lade ein PNG, JPEG oder PDF hoch. Die Verbindung bleibt bis zur fertigen Antwort offen:

curl --fail-with-body "$SCFOLD_ORIGIN/api/v1/customer/invoke" \
  -H "Authorization: Bearer $SCFOLD_API_KEY" \
  -F 'file=@rechnung.png' -F 'full_detail=true'

Alternativ übergibst du eine Bild- oder PDF-URL als JSON:

curl --fail-with-body "$SCFOLD_ORIGIN/api/v1/customer/invoke" \
  -H "Authorization: Bearer $SCFOLD_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"url":"https://dein-dateihost.example/rechnung.png","full_detail":false}'

Übermittle genau eine Quelle: file oder url. Ohne full_detail erhältst du standardmäßig nur die gewünschten Werte:

{"user_json":{"invoice_number":"00042","iban":null}}

full_detail=true ergänzt analysis_json, unter anderem mit Seiten und erkannten Regionen, Feldentscheidungen, Analysestatus und Versionsangaben. Führende Nullen bleiben in Strings erhalten. Ein fehlender Wert und ein technischer Analysefehler sind unterschiedlich: Ein technischer Fehler liefert einen Fehlerstatus, nicht nur leere Werte.

6. Mehrere Bilder als ZIP verarbeiten

Ein ZIP mit PNG-/JPEG-Bildern wird im Hintergrund verarbeitet. Auch ein ZIP mit nur einem Bild ist ein Auftrag. So lädst du ein Archiv hoch:

curl --fail-with-body "$SCFOLD_ORIGIN/api/v1/customer/invoke" \
  -H "Authorization: Bearer $SCFOLD_API_KEY" \
  -F 'file=@rechnungen.zip'

So übergibst du eine ZIP-URL:

curl --fail-with-body "$SCFOLD_ORIGIN/api/v1/customer/invoke" \
  -H "Authorization: Bearer $SCFOLD_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"url":"https://dein-dateihost.example/rechnungen.zip"}'

Die Antwort HTTP 202 bedeutet, dass der Auftrag angenommen wurde. Sie enthält job_id, status, total, successful, failed, Zeitpunkte sowie status_url und results_url. Die zurückgegebenen URLs sind Pfade, die du an deine SCFold-Adresse anhängst. Sie sind noch keine fertigen Erkennungsergebnisse.

Übernimm die zurückgegebene Job-ID und frage den Status beispielsweise alle zwei Sekunden ab:

export SCFOLD_JOB_ID='hier-die-zurueckgegebene-job-id-eintragen'
curl --fail-with-body "$SCFOLD_ORIGIN/api/v1/customer/jobs/$SCFOLD_JOB_ID" \
  -H "Authorization: Bearer $SCFOLD_API_KEY"

Beende das Polling bei einem der letzten drei Zustände. Rufe dann die Ergebnisse ab:

curl --fail-with-body "$SCFOLD_ORIGIN/api/v1/customer/jobs/$SCFOLD_JOB_ID/results?full_detail=true" \
  -H "Authorization: Bearer $SCFOLD_API_KEY"

Jeder Eintrag in results enthält Position, Dateiname, Status und sein eigenes user_json. Angelegte Analysen enthalten außerdem Dokument-/Analysekennung und Ergebnisrevision. Fehlgeschlagene Einträge haben ein error mit code und message. Mit full_detail=true erhältst du zusätzlich analysis_json je Eintrag. Eine fehlerhafte Datei verhindert nicht die Verarbeitung der übrigen gültigen Bilder.

Vor Abschluss liefert der Ergebnisabruf HTTP 409 job_not_ready; warte weiter auf einen Endzustand. Wiederholte Abrufe oder ein Wechsel von full_detail starten keine neue Analyse. Die gespeicherten Job-Ergebnisse bleiben die ursprüngliche maschinelle Fassung, auch wenn du das Dokument später im Konto korrigierst.

Wenn du Ergebnisse automatisch an deine Anwendung senden lassen möchtest, kannst du zusätzlich einen Webhook im Kundenbereich einrichten. Deine direkte API-Antwort und die hier beschriebenen Abrufe bleiben unabhängig vom Erfolg dieser Zustellung verfügbar.

7. Grenzen und Aufbewahrung

Leere, beschädigte oder verschlüsselte ZIPs sowie unsichere Pfade, Dateiverknüpfungen und doppelte Dateinamen werden abgelehnt. ZIPs dürfen keine weiteren ZIPs oder PDFs als Bilder enthalten. Private Netzwerkadressen und URLs mit Zugangsdaten oder Fragmenten werden nicht geladen; Weiterleitungen werden ebenfalls geprüft.

Nach Ablauf sind die Jobdaten nicht mehr abrufbar. Die zugehörigen Dokumente bleiben im Konto, bis du sie löschst. Wenn du ein Dokument löschst, ist auch sein gespeichertes Job-Ergebnis nicht mehr verfügbar. Andere Kunden können deine Jobs nicht lesen.

8. Fehler verstehen

Fehlerantworten enthalten error.code und error.message. Werte den HTTP-Status und den Code aus, statt dich auf den Wortlaut der Nachricht zu verlassen.

{"error":{"code":"invalid_source","message":"Provide exactly one file or URL."}}

Bewahre die Job-ID für Rückfragen auf und gib deinen vollständigen API-Schlüssel niemals an den Support weiter.

WordPress-Integration

Das WordPress-Plugin verbindet Mediathek-Bilder mit der Kunden-API und authentifizierten Webhooks. Mit der optionalen UUID client_request_id enthalten Direktantwort und Webhook ein identisches integration-Objekt samt revisionsgebundenem Klar-PNG-Pfad. Ohne diese Option bleibt die bisherige Ausgabe erhalten. Der Bildabruf verlangt einen gültigen API-Schlüssel desselben Kunden.