Signature intégrée

<bf-signing> affiche la page de signature de Bona Fide dans un iframe isolé (bac à sable) à l’intérieur de votre page, l’ajuste à la taille du document et signale les actions du signataire sous forme d’événements DOM. Il ne dépend d’aucun cadriciel; de minces adaptateurs React et Vue sont inclus.

1. Créez l’enveloppe avec delivery: "embedded", pour que les destinataires ne reçoivent pas de courriel.

2. Créez une session sur votre serveur quand le signataire ouvre la page, en indiquant l’origine de votre site dans allowedOrigins. La page intégrée refuse de communiquer avec toute page parente qui n’y figure pas.

   // Your backend (never expose the API key to the browser)
   const res = await fetch(`https://api.bonafidesign.com/v1/envelopes/${envelopeId}/sessions`, {
     method: 'POST',
     headers: { Authorization: `Bearer ${process.env.BONA_FIDE_API_KEY}`, 'Content-Type': 'application/json' },
     body: JSON.stringify({ recipient: recipientId, mode: 'embedded', allowedOrigins: ['https://app.example.com'] }),
   });
   const { token } = await res.json(); // 'bfs_…', single-use, 10 minutes by default

3. Affichez l’élément avec le jeton.

   HTML

   <script type="module" src="https://js.bonafidesign.com/v1"></script>
   
   <bf-signing session="bfs_…" theme="auto" min-height="480" max-height="90vh"></bf-signing>
   
   <script>
     const el = document.querySelector('bf-signing');
     el.addEventListener('completed', (e) => {
       // e.detail = { type: 'completed', envelope: 'env_…' }
       window.location.href = '/onboarding/next';
     });
     el.addEventListener('session_expiring', () => refreshSession());
     el.addEventListener('error', (e) => console.error(e.detail.code, e.detail.message));
   </script>

   React

   import { BonaFideSigning } from '@bona-fide/embed/react';
   
   export function SignContract({ token }: { token: string }) {
     return (
       <BonaFideSigning
         session={token}
         theme="auto"
         minHeight={480}
         maxHeight="90vh"
         onCompleted={(e) => console.log('envelope completed', e.envelope)}
         onDeclined={(e) => console.log('declined', e.reason)}
         onSessionExpiring={() => refreshSession()}
         onError={(e) => console.error(e.code, e.message)}
       />
     );
   }

   Vue

   <script setup lang="ts">
   import { BonaFideSigning } from '@bona-fide/embed/vue';
   defineProps<{ token: string }>();
   const done = (e: { envelope: string }) => console.log('envelope completed', e.envelope);
   </script>
   
   <template>
     <BonaFideSigning :session="token" theme="auto" :min-height="480" max-height="90vh" @completed="done" />
   </template>

4. Confirmez sur votre serveur. Considérez l’événement du navigateur comme un simple signal pour l’interface et fiez-vous au webhook envelope.completed (ou à GET /v1/envelopes/{id}) pour connaître le résultat.

Attributs

Attribut (prop React / Vue)	Valeur par défaut	Remarques
session		Le jeton bfs_…. Le modifier recharge le cadre
base-url (baseUrl)	https://sign.bonafidesign.com/s/	La route de signature hébergée du déploiement
theme	auto	auto, light ou dark
locale		Transmis à la page de signature
min-height, max-height (minHeight, maxHeight)	480, 90vh	En pixels ou en vh. Le cadre s’agrandit avec le document entre ces deux valeurs, puis défile à l’intérieur
timeout	30000	Délai d’attente de la page, en millisecondes, avant une error avec le code load_timeout
frame-title	Document signing	Le titre accessible de l’iframe

L’élément dispose aussi d’une méthode reload(), par exemple après la création d’une nouvelle session.

Événements

Les événements remontent dans le DOM, traversent les racines fantômes (shadow roots) et transportent leurs données dans event.detail. bf-event est déclenché pour chacun d’eux.

Événement	detail
ready	{ type: 'ready' } : la page de signature est chargée
field_completed	{ type, field } : un champ a été rempli
signed	{ type, recipient } : ce destinataire a soumis
completed	{ type, envelope } : l’enveloppe est finalisée
declined	{ type, reason? }
session_expiring	{ type, expiresAt } : créez bientôt une nouvelle session
error	{ type, code, message }, y compris load_timeout et invalid_base_url

Les props React sont onReady, onFieldCompleted, onSigned, onCompleted, onDeclined, onSessionExpiring, onError et onEvent; Vue émet les noms des événements (@completed, @session_expiring, …) et event.

Modèle de sécurité

• Le jeton circule dans le fragment de l’URL de l’iframe (#session=…), qui n’atteint jamais un serveur ni un en-tête Referer. La page de signature le lit, le retire de l’URL et de l’historique, puis l’échange contre un jeton d’accès conservé en mémoire. Aucun témoin n’est utilisé.
• L’iframe est isolé (allow-scripts allow-same-origin allow-forms allow-popups allow-popups-to-escape-sandbox allow-downloads) avec referrerpolicy="strict-origin".
• Votre page n’accepte un message que s’il provient de l’iframe propre à l’élément et de l’origine de base-url et s’il s’analyse comme un message bona-fide.embed/1 doté de son espace de noms. Tout le reste est ignoré.
• La page de signature envoie ses messages à votre origine exacte (jamais *), et seulement si cette origine figure dans les allowedOrigins de la session. L’API refuse aussi les appels d’une session intégrée qui proviennent d’origines non autorisées.

Plutôt la page hébergée

Si vous préférez ne pas intégrer la signature, créez la session avec "mode": "hosted" et redirigez vers son url; définissez returnUrl pour ramener le signataire. Consultez Sessions de signature.

Note

L’URL du script ci-dessus est celle qu’utilise l’extrait d’intégration du tableau de bord. L’élément et ses adaptateurs proviennent d’un seul paquet, @bona-fide/embed : le point d’entrée racine enregistre <bf-signing>, et @bona-fide/embed/react et @bona-fide/embed/vue exportent BonaFideSigning.