Dokumente per Schnittstelle einliefern (API)

Dokumente kommen nicht nur per E-Mail, Upload oder Connector zu scanJUMP – auch per Schnittstelle (API). Damit lassen sich n8n, eigene Skripte oder ein Dokumenten-Export an ein Postfach anschließen. Die API ist in jedem Paket enthalten.

Token anlegen

1. In scanJUMP unter Einstellungen → Entwickler einen API-Token anlegen und sicher speichern – er wird nur einmal angezeigt.
2. Tokens gelten 365 Tage und lassen sich jederzeit widerrufen.
3. Die Postfach-Nummer (channel_id) findest du in der Adresszeile der Postfach-Einstellungen oder über GET /api/v1/mail-ingest/channels.

PDFs einliefern

POST /api/v1/ingest, ausschließlich als multipart/form-data: Feld channel_id (Ziel-Postfach) und ein oder mehrere Felder files (PDF). Optional der Header Idempotency-Key – ein wiederholter Aufruf mit demselben Schlüssel legt keinen zweiten Vorgang an.

curl -X POST "https://api.scanjump.de/api/v1/ingest" \
  -H "Authorization: Bearer $SCANJUMP_TOKEN" \
  -H "Idempotency-Key: gmail-msg-18c2f4a7" \
  -F "channel_id=12" \
  -F "files=@rechnung.pdf;type=application/pdf"

Antwort 200: {"status": "queued", "history_id": 1234, "tasks": [...]}. Das Dokument läuft dann wie eine E-Mail durch das Postfach: Trennen, Benennen, Ablegen oder Weiterleiten.

Grenzen

Besondere Antworten

• 202 mit "status": "held": Kontingent aufgebraucht oder Konto noch nicht freigeschaltet. Das Dokument ist sicher gespeichert und wird nach Freischaltung automatisch verarbeitet – kein erneuter Aufruf nötig.
• 503 mit Retry-After: Zwischenspeicher nicht erreichbar, nichts angenommen – die Anfrage unverändert wiederholen.
• 200 mit "replayed": true: derselbe Idempotency-Key wurde schon einmal mit derselben Anfrage benutzt; es wurde nichts erneut eingeliefert.
• 409: Postfach deaktiviert oder Idempotency-Key mit anderem Inhalt wiederverwendet.

Status abfragen

GET /api/v1/ingest/{history_id} liefert Status (queued, processed, forwarded, held, error), Ein- und Ausgabedateien mit Links in deine Ablage, Ordnerpfad und Fehler. Bei mehreren Dateien bleibt der Gesamtstatus queued, bis alle Dokumente fertig sind; documents nennt erwartete, fertige und fehlgeschlagene.

Webhook statt Abfragen

Je Postfach kannst du eine callback_url hinterlegen (PATCH /api/v1/mail-ingest/channels/{id} mit {"callback_url": "https://…"}). Die Antwort enthält beim ersten Setzen einmalig das callback_secret. scanJUMP ruft die Adresse dann je Dokument ("event": "document") und einmal am Ende ("event": "completed") mit den Dateinamen und dem Ordnerpfad auf. Jeder Aufruf trägt X-Scanjump-Signature: sha256=…, ein HMAC-SHA256 über den Anfragetext mit dem Secret als Schlüssel – bitte prüfen und ungültige Aufrufe verwerfen. Zustellung: 10 s Zeitlimit, bis zu drei Wiederholungen.

Noch nicht in dieser Version

• Bilder (Handyfotos) einliefern – kommt mit der Capture-App.
• Webhook für Postfächer mit reiner Weiterleitung – dort bitte den Status abfragen.
• Token nur zum Einliefern (Scopes).