Signature intégrée

<bf-signing> affiche la page de signature de Bona Fide dans une iframe isolée (sandbox) au sein 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 framework ; de fins wrappers React et Vue sont fournis.

1. Créez l’enveloppe avec delivery: "embedded", afin que les destinataires ne reçoivent pas d’e-mail.

2. Créez une session sur votre serveur lorsque 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 signal pour l’interface et appuyez-vous sur le webhook envelope.completed (ou sur GET /v1/envelopes/{id}) pour connaître le résultat.

Attributs

Attribut (prop React / Vue)	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	Pixels ou vh. Le cadre s’agrandit avec le document entre ces deux valeurs, puis défile en interne
timeout	30000	Délai d’attente de la page, en millisecondes, avant un error de 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 (bubbling), traversent les shadow roots et transportent leur charge utile 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 validé
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 d’événements (@completed, @session_expiring, …) ainsi que event.

Modèle de sécurité

• Le jeton transite dans le fragment d’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 cookie n’est utilisé.
• L’iframe est isolée (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 de l’espace de noms bona-fide.embed/1. Tout le reste est ignoré.
• La page de signature envoie ses messages à votre origine exacte (jamais *), et uniquement si cette origine figure dans les allowedOrigins de la session. L’API refuse elle aussi les appels d’une session intégrée provenant d’origines non autorisées.

Opter pour 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 ensuite 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 wrappers proviennent d’un seul paquet, @bona-fide/embed : le point d’entrée principal enregistre <bf-signing>, et @bona-fide/embed/react et @bona-fide/embed/vue exportent BonaFideSigning.