La plupart des produits qui ont besoin d’une signature envoient leurs utilisateurs ailleurs pour l’obtenir. Un e-mail arrive, un lien ouvre une page qui ne ressemble en rien à votre produit, l’utilisateur y signe et retrouve son chemin comme il peut, et votre système n’apprend qu’il s’est passé quelque chose que lorsque quelqu’un va vérifier. Cela fonctionne, et c’est là que chaque flux se casse. À partir d’aujourd’hui, ce n’est plus la seule option : l’API GingerDocs et le SDK d’intégration sont disponibles, avec la documentation sur app.gingerdocs.com/docs et les deux paquets SDK sur npm.
Voici la version courte de ce que vous pouvez construire avec, dans l’ordre où vous le construiriez.
Trois étapes : émettre, monter, agir sur les événements
Le modèle est volontairement réduit. Votre serveur demande à notre API une session intégrée : une URL de courte durée liée à un document et à un signataire, ou à l’un de vos utilisateurs et à un espace de travail. Votre page confie cette URL au SDK, qui encadre l’expérience de signature sur notre origine et épingle l’origine et l’identifiant de session des deux côtés. Votre code écoute ensuite des événements typés et agit en conséquence.
Votre clé secrète n’atteint jamais un navigateur. Ce n’est pas une consigne que vous devez respecter ; la conception la rend inutile, parce que la seule chose que la page voit jamais est l’URL de session, qui expire d’elle-même et peut être révoquée depuis votre serveur à tout moment.
- Émettez une session sur votre serveur avec une clé secrète : un seul POST indiquant le document et l’origine de la page qui affichera le cadre.
- Montez le cadre avec le SDK : quatre lignes dans votre page, ou un composant en React.
- Agissez sur les événements : ready, viewed, signed, completed, declined, et les événements de document d’une session d’espace de travail. Pour tout ce qui se termine en dehors du cadre, votre endpoint de webhook ou l’API des événements est la source de vérité.
Le code
Côté serveur, un seul appel crée la session. La réponse contient l’URL destinée à la page et un identifiant que vous transmettez pour que le SDK n’accepte que les messages de cette session.
const res = await fetch('https://api.gingerdocs.com/api/v1/embed_sessions', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.GINGERDOCS_SECRET_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
kind: 'signing',
document_id: documentId,
host_origin: 'https://app.example.com',
}),
})
const { id, url } = await res.json()Dans la page, le SDK monte le cadre dans n’importe quel élément et vous remet les événements. Quand une session expire, émettez-en une nouvelle et rechargez le cadre sur place ; le signataire ne perd jamais sa position.
import { mount } from '@gingerdocs/embed'
const embed = mount('#signing', { url, sessionId: id })
embed.on('ready', () => hideLoader())
embed.on('completed', () => showConfirmation())
embed.on('session_expired', async () => {
const fresh = await refetchSession()
embed.reload(fresh.url, { sessionId: fresh.id })
})Si vous utilisez React, c’est un composant avec un seul gestionnaire pour tous les événements, que vous pouvez passer en ligne sans risque. React est facultatif : le paquet principal ne dépend d’aucun framework, donc les quatre lignes ci-dessus fonctionnent telles quelles dans Vue, Angular, Svelte ou une simple page HTML.
import { GingerDocsEmbed } from '@gingerdocs/react'
<GingerDocsEmbed
url={session.url}
sessionId={session.id}
onEvent={event => event.type === 'completed' && showConfirmation()}
/>Construisez gratuitement, en test
Le mode développeur et les clés de test sont disponibles dans chaque forfait, Free compris. Tout ce que décrit cet article fonctionne dans l’environnement de test : aucun e-mail, de quelque nature que ce soit, ne quitte nos serveurs, le PDF produit porte un filigrane indiquant qu’il n’a pas de valeur juridique, et les documents de test sont supprimés après 90 jours. Un endpoint de test peut même simuler la signature, pour que votre CI vérifie qu’un document atteint COMPLETED sans qu’un humain clique sur quoi que ce soit.
Passez à une clé live quand vous êtes prêt. Les appels sont identiques.
Votre nom sur le certificat
Chaque document finalisé se termine par un certificat de finalisation : le numéro de référence, le code de vérification, ainsi que la chronologie et l’adresse IP de chaque signataire. Lorsque vous transmettez vous-même le lien de signature, ou attestez l’identité d’un signataire par une session intégrée, le certificat nomme votre entité juridique comme partie vérificatrice. C’est ce que vous acceptez dans les Conditions d’intégration en activant le mode développeur, et c’est la version honnête du relevé : il dit qui s’est porté garant du signataire.
Quiconque détient le PDF peut toujours le confronter à nos enregistrements sur la page de vérification, sans compte.
Des webhooks, et un journal d’événements de 90 jours
Chaque changement d’état émet un événement. Enregistrez un endpoint de webhook et chacun d’eux arrive sous forme de POST signé, avec de nouvelles tentatives et un journal de livraison consultable sous Paramètres → Développeur. Si vous en manquez un malgré tout, parce que votre endpoint était indisponible pendant une heure, il est toujours là : chaque événement reste lisible via l’API pendant 90 jours.
Le cadre rapporte ce qui se passe à l’intérieur ; votre webhook rapporte ce qui se passe n’importe où. Bâtissez sur le second, et réservez le premier à la personne qui se trouve devant l’écran.
Open source, deux paquets
Le SDK est assez petit pour être lu d’une traite, et c’est tout l’intérêt. @gingerdocs/embed est indépendant de tout framework, pèse moins de 1,5 Ko gzippé et n’a aucune dépendance ; @gingerdocs/react l’enveloppe dans un composant. Tous deux sont sous licence MIT et vivent sur GitHub, sur gingerdocs/embed-sdk et gingerdocs/embed-react-sdk, où les outils de suivi des problèmes sont ouverts.
Un SDK lisible, c’est ce qui fait de la promesse de sécurité ci-dessus quelque chose que vous pouvez vérifier plutôt que quelque chose que vous prenez pour argent comptant.
Tarifs, et par où commencer
Construisez gratuitement avec des clés de test. Passez en production avec le forfait Developer : 100 $ par an pour tout ce que propose Pro, les mêmes 1 000 documents importés par mois, et des clés d’API live. Les détails sont sur la page des tarifs.
Commencez par le guide de démarrage rapide : d’un compte tout neuf à un document signé en quatre appels, dans votre terminal, en une dizaine de minutes. La page Développeurs donne la vue d’ensemble, et la référence de l’API est là quand il vous faut chaque champ.