Passer au contenu principal

Signature intégrable

Intégrez le flux de signature directement dans votre application afin que les destinataires puissent signer des documents sans quitter votre produit. Cela crée une expérience de signature fluide et en marque blanche.

Modèle d’URL de signature

L’interface de signature est disponible à l’adresse : https://app.firma.dev/signing/{signing_request_user_id}

Intégration iframe de base

Permissions iframe requises

  • camera - Pour la vérification d’identité (si activée)
  • microphone - Pour la vérification vidéo (si activée)
  • clipboard-write - Pour copier/coller du contenu

Obtenir l’URL de signature

Le signing_request_user_id est renvoyé lorsque vous récupérez les utilisateurs de la demande de signature via l’API.

Exemple : obtenir les URL de signature des destinataires

Exemple d’implémentation complète

Composant React

Point de terminaison côté serveur (Node.js)

Événements postMessage

L’iframe de signature émet des événements postMessage pour suivre la progression de la signature :
Une erreur de chargement (LOAD_FAILED, NOT_SENT, LINK_INVALID, SEAL_PAUSED) n’est envoyée qu’une fois et peut arriver sans aucun événement signing.loaded antérieur. La page relance automatiquement un chargement ayant échoué pendant environ 30 secondes au maximum avant d’envoyer LOAD_FAILED. Si votre page a besoin de son propre mécanisme de secours, considérez que le chargement a échoué si vous ne recevez pas signing.loaded (origine https://app.firma.dev, source firma-signing) environ 30 secondes après l’événement load de l’iframe, et proposez au signataire de réessayer en rechargeant l’iframe. Notez que signing.loaded n’est envoyé que lorsque le signataire a au moins un champ. Un second onglet ou appareil intégré qui ouvre ou recharge le lien de signature après que le signataire a terminé ne reçoit aucun message signing.completed ni signing.error : cet onglet affiche l’écran « déjà signé ». Un onglet déjà ouvert avant que le signataire ait terminé peut encore envoyer signing.completed (en terminant) ou signing.error (en refusant). Les webhooks signing_request.recipient.signed et signing_request.completed restent les signaux durables pour l’hôte.

Bonnes pratiques de sécurité

N’exposez jamais de clés API dans le code frontend. Récupérez toujours les ID d’utilisateur de signature via un point de terminaison backend sécurisé.

✅ À faire

  • ✅ Récupérez les ID d’utilisateur de signature via votre backend
  • ✅ Validez les origines des postMessage (https://app.firma.dev)
  • ✅ Utilisez HTTPS pour toutes les requêtes API
  • ✅ Surveillez les événements de signature via des webhooks (60 req/min)

❌ À ne pas faire

  • ❌ N’exposez pas de clés API dans le code client
  • ❌ Ne faites pas confiance aux données postMessage sans validation de l’origine

Limites de débit

Consultez le guide sur les Limites de débit.

Intégration des webhooks

Utilisez des webhooks pour suivre les événements de signature en temps réel plutôt que de faire du polling :
Consultez le guide des Webhooks pour tous les détails d’implémentation.

Dépannage

L’iframe ne se charge pas

Causes possibles :
  • L’ID de destinataire du lien de signature n’existe pas ou a été supprimé : la page affiche « Lien de signature non valide » et envoie signing.error avec LINK_INVALID.
  • La connexion du signataire a échoué ou a expiré : la page réessaie, puis affiche un écran « Réessayer » et envoie LOAD_FAILED.
  • La demande de signature n’a pas encore été envoyée : NOT_SENT.
  • Un sceau d’organisation en pause est placé plus tôt dans l’ordre de signature : SEAL_PAUSED.
Les demandes terminées, annulées, refusées et expirées affichent leurs propres pages, pas une erreur ; vérifiez l’état de la demande avec GET /signing-requests/{id}.

Les événements postMessage ne sont pas reçus

Causes possibles :
  • La validation de l’origine bloque les messages
  • L’écouteur d’événement n’est pas attaché avant le chargement de l’iframe
Solution :
  • Vérifiez que l’origine est exactement https://app.firma.dev
  • Attachez l’écouteur avant de créer l’iframe

403 Forbidden lors de la récupération de la demande de signature

Causes possibles :
  • L’utilisateur n’a pas accès à la demande de signature
  • La clé API ne dispose pas des permissions requises
Solution : vérifiez la logique d’autorisation et les permissions de la clé API

Étapes suivantes