Box.com-Verbindung: Methode und funktionaler Hintergrund

Die Box.com-Verbindung regelt digitale Unterschriften auf Aufträgen über Box Sign. Wenn ein Auftrag den Status “Unterschrift anfordern” erreicht, generiert i-Reserve PDF-Dokumente aus Auftragsvorlagen, lädt diese in Box hoch und erstellt eine Box Sign-Anforderung, die an den Kunden gesendet wird. Sobald der Kunde unterschreibt, empfängt i-Reserve einen Webhook, lädt die unterschriebenen Dokumente herunter und aktualisiert den Auftragsstatus.

Authentifizierung

Die Verbindung nutzt eine Box JWT-App (Server-Authentifizierung mit einem Service-Konto), keine interaktive OAuth-Anmeldung. i-Reserve signiert ein JWT (RS256) mit den App-Credentials und tauscht dieses gegen einen Access-Token; die App arbeitet auf Enterprise-Ebene. Erforderliche Daten: Client-ID, Client-Secret, Public-Key-ID, Private Key (PEM), Passphrase und Enterprise-ID. Optional können Sie über as user als ein bestimmter Box-Benutzer handeln.

Was bei “Unterschrift anfordern” geschieht

1. i-Reserve generiert die PDF(s) aus den konfigurierten Auftragsvorlagen.
2. Die PDFs werden in Box hochgeladen (in einen festen i-Reserve-Ordner, den die Verbindung erstellt/wiederverwendet).
3. Es wird eine Box Sign-Anforderung mit dem Kunden als Unterzeichner (und einem Empfänger für die Endkopie) erstellt. Felder können vorab ausgefüllt werden (Prefill) mit Kunden-/Unternehmensdaten.
4. Die Anforderung erhält eine external_id im Format ord_{order_id}:int_{integration_id}, damit der Webhook später den richtigen Auftrag wiederfindet; die Sign-Request-ID wird in einem Auftragsfeld aufbewahrt.

Webhook zurück von Box

Beim Einrichten registriert die Verbindung einen Webhook auf dem Box-Ordner für die Events SIGN_REQUEST.COMPLETED, SIGN_REQUEST.DECLINED und SIGN_REQUEST.EXPIRED. Box sendet Benachrichtigungen an den i-Reserve-Endpunkt; diese werden mit einer HMAC-SHA256-Signatur verifiziert. i-Reserve übersetzt das Event in einen Auftragsstatus (unterschrieben / abgelehnt / abgelaufen), lädt die unterschriebenen Dokumente + das Unterzeichnungsprotokoll herunter und speichert diese als Auftragsdokumente.

Einschränkungen

• Arbeitet auf Auftragsebene (nicht auf einzelnen Buchungen) und ist auf den Box Sign-Prozess ausgerichtet.
• Nur JWT-Service-Konto; keine interaktive Anmeldung pro Kunde.
• Ohne ausgewählte Auftragsvorlagen wird keine Sign-Anforderung erstellt (stiller No-op).
• Das external_id-Format und das eingestellte Auftragsfeld für die Sign-Request-ID sind für die Webhook-Verbindung wesentlich.
• Der Private Key muss korrekt als PEM eingefügt werden; die Webhook-URL, die Box zurückruft, muss öffentlich erreichbar sein.