Datei-Scans integrieren

Scan-Modus auswählen

Blazelock bietet zwei Möglichkeiten, einen Datei-Scan zu übermitteln:

Modus	Endpunkt	Geeignet für	Verhalten der Antwort
`async`	`POST /file-scans`	Die meisten Produktivanbindungen, Hintergrund-Workflows und größere Dateien	Gibt sofort einen Scan im Status `processing` zurück
`sync`	`POST /file-scans/sync`	Request-Response-Abläufe, die ein Ergebnis innerhalb derselben Anfrage benötigen	Gibt ein finales Ergebnis oder einen Timeout-Fehler zurück

Wann Sie `async` bevorzugen sollten

Verwenden Sie asynchrone Scans standardmäßig, wenn:

Ihre Anwendung im Hintergrund weiterarbeiten kann
Sie den Status über Webhooks oder späteres Polling nachverfolgen möchten
Sie vermeiden möchten, dass eine HTTP-Anfrage während des Scan-Vorgangs offen bleibt
Sie Dateien scannen müssen, die das synchrone Upload-Limit überschreiten

Der asynchrone Endpunkt akzeptiert Dateien bis 100 MB und gibt den erstellten Scan im Status processing zurück. Den weiteren Verlauf können Sie dann über Webhooks oder die Status-Endpunkte nachverfolgen.

Wann `sync` gut geeignet ist

Verwenden Sie synchrone Scans, wenn alle folgenden Punkte zutreffen:

Die aufrufende Seite profitiert von einem direkten Ergebnis innerhalb desselben Request-Response-Zyklus
Es ist für die User Experience akzeptabel, auf den Scan zu warten
Die Datei bleibt innerhalb des synchronen Upload-Limits

Der synchrone Endpunkt akzeptiert Dateien bis 10 MB. Er wartet innerhalb eines begrenzten Polling-Fensters auf ein finales Ergebnis und gibt dann entweder completed oder failed zurück.

Wenn der Scan nicht rechtzeitig abgeschlossen wird, gibt der Endpunkt 408 sync_scan_timeout zusammen mit file_scan_id zurück. Der Scan selbst existiert weiterhin. Ihre Anbindung sollte daher mit GET /file-scans/{id} oder Webhooks fortfahren, anstatt das Timeout als verlorene Übermittlung zu behandeln.

In den meisten Anbindungen ist async die bessere Standardwahl. Verwenden Sie sync nur dann, wenn ein sofortiges Ergebnis den aufrufenden Ablauf tatsächlich sinnvoll verändert.

Polling vs. Webhooks

Es gibt zwei gängige Möglichkeiten, asynchrone Scans nachzuverfolgen:

Ansatz	Funktionsweise	Stärken	Nachteile
Polling	Ihr System fordert die aktuellen Daten wiederholt an, bis sich der Status ändert.	Einfach zu verstehen und für den Einstieg leicht zu testen.	Erzeugt unnötige Anfragen, erhöht die Latenz und verlagert mehr Koordinationslogik in Ihre Anwendung.
Webhooks	Blazelock sendet ein Ereignis an Ihren Endpunkt, wenn sich der Status ändert.	Nahezu Echtzeit-Updates, weniger API-Aufrufe und eine sauberere asynchrone Architektur.	Erfordert einen öffentlichen HTTPS-Endpunkt und eine korrekte Validierung der Anfrage.

Wenn Sie nur gelegentlich einen Status prüfen müssen, kann Polling ausreichen. Wenn Sie eine ereignisgesteuerte Anbindung möchten, die besser skaliert und schneller reagiert, sind Webhooks in der Regel die bessere Wahl.

`external_reference_id` verwenden

external_reference_id ist eine optionale ID, die Sie beim Übermitteln eines Scans in attributes.external_reference_id mitsenden können.

Beispiel:

{
  "attributes": {
    "file_name": "invoice.pdf",
    "external_reference_id": "invoice-4711"
  }
}

Wenn Sie ihn mitsenden:

Wird der Wert in Scan-Antworten zurückgegeben
Wird der Wert in Webhook-Payloads mitgeliefert
Können Sie den Scan über GET /file-scans/external-reference/{external_reference_id} abrufen

Der Wert wird innerhalb der authentifizierten API-Anbindung aufgelöst. In der Praxis bedeutet das, dass er pro Anbindung eindeutig sein muss. Wenn Sie denselben Wert für dieselbe Anbindung erneut übermitteln, gibt die API 409 duplicate_external_reference_id zurück.

Wann es sinnvoll ist

external_reference_id ist sinnvoll, wenn Sie den Scan mit einer ID verknüpfen möchten, die in Ihrem eigenen System bereits existiert, zum Beispiel:

Einer Upload-Record-ID
Einer Dokument- oder Rechnungs-ID
Einer Job-, Workflow- oder Queue-Item-ID

Dadurch können Ihre Anwendung und Ihre Webhook-Consumer mit einem fachlichen Bezeichner arbeiten, den sie bereits kennen, anstatt sich nur auf die Blazelock-Scan-ID zu stützen.

Format

external_reference_id ist optional, darf bis zu 255 Zeichen lang sein und nur Buchstaben, Ziffern, ., _, :, /, #, @ und - enthalten.

Empfehlungen

Wenn Sie external_reference_id verwenden, wählen Sie einen stabilen Wert, der das zugehörige Fachobjekt in Ihrem System bereits identifiziert.
Verwenden Sie Namensräume, wenn mehrere Workflows sich eine Anbindung teilen, zum Beispiel invoice/4711 oder upload:01HXYZ.
Behandeln Sie den Wert als Bezeichner, nicht als Secret.
Wenn dasselbe Fachobjekt mehrfach gescannt werden kann, versionieren Sie den Wert explizit, zum Beispiel invoice/4711/scan/2.

Auf dieser Seite