Box.com-koppeling: methode en functionele achtergrond

De Box.com-koppeling regelt digitale handtekeningen op orders via Box Sign. Wanneer een order de status “handtekening aanvragen” bereikt, genereert i-Reserve PDF-documenten uit ordersjablonen, uploadt die naar Box en maakt een Box Sign-verzoek aan dat naar de klant wordt gestuurd. Zodra de klant tekent, ontvangt i-Reserve een webhook, downloadt de getekende documenten en werkt de orderstatus bij.

Authenticatie

De koppeling gebruikt een Box JWT-app (server authentication met een service-account), geen interactieve OAuth-login. i-Reserve ondertekent een JWT (RS256) met de app-credentials en wisselt die in voor een access-token; de app werkt op enterprise-niveau. Benodigde gegevens: client-id, client-secret, public key-id, private key (PEM), passphrase en enterprise-id. Optioneel kun je via as user als een specifieke Box-gebruiker handelen.

Wat er gebeurt bij “handtekening aanvragen”

1. i-Reserve genereert de PDF('s) uit de geconfigureerde ordersjablonen.
2. De PDF's worden naar Box geüpload (in een vaste i-Reserve-map die de koppeling aanmaakt/herbruikt).
3. Er wordt een Box Sign-verzoek aangemaakt met de klant als ondertekenaar (en een ontvanger voor de eindkopie). Velden kunnen vooraf ingevuld worden (prefill) met klant-/bedrijfsgegevens.
4. Het verzoek krijgt een external_id in het formaat ord_{order_id}:int_{integration_id} zodat de webhook later de juiste order terugvindt; het sign-request-id wordt in een orderveld bewaard.

Webhook terug van Box

Bij het opzetten registreert de koppeling een webhook op de Box-map voor de events SIGN_REQUEST.COMPLETED, SIGN_REQUEST.DECLINED en SIGN_REQUEST.EXPIRED. Box stuurt notificaties naar het i-Reserve-endpoint; deze worden geverifieerd met een HMAC-SHA256-handtekening. i-Reserve vertaalt het event naar een orderstatus (getekend / geweigerd / verlopen), downloadt de getekende documenten + het ondertekenlog en slaat die als orderdocumenten op.

Beperkingen

• Werkt op order-niveau (niet op losse boekingen) en is gericht op het Box Sign-proces.
• Alleen JWT-service-account; geen interactieve per-klant-login.
• Zonder geselecteerde ordersjablonen wordt geen sign-verzoek aangemaakt (stille no-op).
• Het external_id-formaat en het ingestelde orderveld voor het sign-request-id zijn essentieel voor de webhook-koppeling.
• De private key moet correct als PEM worden geplakt; de webhook-URL die Box terugbelt moet publiek bereikbaar zijn.