Die meisten Produkte, die eine Unterschrift brauchen, schicken ihre Nutzer dafür woandershin. Eine E-Mail kommt an, ein Link öffnet eine Seite, die Ihrem Produkt in nichts ähnelt, der Nutzer unterschreibt dort und findet irgendwie zurück, und Ihr System erfährt erst, dass etwas passiert ist, wenn jemand nachsieht. Das funktioniert, und genau dort bricht jeder Ablauf. Ab heute ist das nicht mehr die einzige Option: die GingerDocs-API und das Embed-SDK sind live, mit der Dokumentation unter app.gingerdocs.com/docs und beiden SDK-Paketen auf npm.

Dies ist die Kurzfassung dessen, was Sie damit bauen können, in der Reihenfolge, in der Sie es bauen würden.

Drei Schritte: Session erzeugen, Frame einbinden, auf Events reagieren

Das Modell ist bewusst klein gehalten. Ihr Server fordert bei unserer API eine Embed-Session an: eine kurzlebige URL, die an ein Dokument und einen Unterzeichner gebunden ist, oder an einen Ihrer Nutzer und einen Arbeitsbereich. Ihre Seite übergibt diese URL an das SDK, das den Signaturablauf auf unserem Origin in einen Frame einbettet und Origin und Session-ID auf beiden Seiten festschreibt. Ihr Code lauscht dann auf typisierte Events und reagiert darauf.

Ihr Secret Key erreicht nie einen Browser. Das ist keine Richtlinie, an die Sie sich halten müssen; das Design macht es schlicht unnötig, denn das Einzige, was die Seite je zu sehen bekommt, ist die Session-URL, die von selbst abläuft und jederzeit von Ihrem Server widerrufen werden kann.

  • Erzeugen Sie auf Ihrem Server mit einem Secret Key eine Session: ein POST, der das Dokument und den Origin der Seite benennt, die den Frame einbetten wird.
  • Binden Sie den Frame mit dem SDK ein: vier Zeilen in Ihrer Seite oder eine Komponente in React.
  • Reagieren Sie auf Events: ready, viewed, signed, completed, declined sowie die Dokument-Events einer Arbeitsbereichs-Session. Für alles, was außerhalb des Frames abgeschlossen wird, sind Ihr Webhook-Endpunkt oder die Events-API die verlässliche Quelle.

Der Code

Auf dem Server erzeugt ein einziger Aufruf die Session. Die Antwort enthält die URL für die Seite und eine ID, die Sie weiterreichen, damit das SDK nur Nachrichten aus genau dieser Session akzeptiert.

backend.jsJavaScript
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()

In der Seite bindet das SDK den Frame in ein beliebiges Element ein und liefert Ihnen die Events. Läuft eine Session ab, erzeugen Sie eine neue und laden den Frame an Ort und Stelle neu; der Unterzeichner verliert nie seine Stelle.

frontend.jsJavaScript
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 })
})

Wenn Sie React verwenden, ist es eine Komponente mit einem Handler für alle Events, den Sie bedenkenlos inline übergeben können. React ist optional: Das Kernpaket hat keine Framework-Abhängigkeit, die vier Zeilen oben funktionieren also unverändert in Vue, Angular, Svelte oder einer einfachen HTML-Seite.

Signing.jsxJSX
import { GingerDocsEmbed } from '@gingerdocs/react'

<GingerDocsEmbed
  url={session.url}
  sessionId={session.id}
  onEvent={event => event.type === 'completed' && showConfirmation()}
/>

Kostenlos bauen, im Testmodus

Developer Mode und Test-Keys stehen in jedem Tarif zur Verfügung, auch im Free-Tarif. Alles in diesem Beitrag funktioniert in der Testumgebung: keine E-Mail irgendeiner Art verlässt unsere Server, das ausgegebene PDF trägt ein Wasserzeichen als nicht rechtsverbindlich, und Testdokumente werden nach 90 Tagen entfernt. Ein Test-Endpunkt kann sogar die Unterschrift simulieren, sodass Ihre CI prüfen kann, dass ein Dokument den Status COMPLETED erreicht, ohne dass ein Mensch irgendwo klickt.

Wechseln Sie zu einem Live-Key, sobald Sie bereit sind. Die Aufrufe sind identisch.

Ihr Name auf dem Zertifikat

Jedes abgeschlossene Dokument endet mit einem Abschlusszertifikat: der Referenznummer, dem Verifizierungscode sowie dem Zeitverlauf und der IP-Adresse jedes Unterzeichners. Wenn Sie den Signaturlink selbst zustellen oder die Identität eines Unterzeichners über eine eingebettete Session bestätigen, nennt das Zertifikat Ihre juristische Person als verifizierende Partei. Genau das akzeptieren Sie in den Integrator Terms, wenn Sie den Developer Mode einschalten, und es ist die ehrliche Fassung des Nachweises: Sie sagt, wer für den Unterzeichner gebürgt hat.

Jeder, der das PDF in Händen hält, kann es weiterhin auf der Verifizierungsseite gegen unsere Aufzeichnungen prüfen, ganz ohne Konto.

Webhooks und ein Event-Log über 90 Tage

Jede Statusänderung löst ein Event aus. Registrieren Sie einen Webhook-Endpunkt, und jedes Event kommt als signierter POST an, mit Wiederholungsversuchen und einem Zustellprotokoll, das Sie unter Einstellungen → Developer einsehen können. Verpassen Sie trotzdem eines, weil Ihr Endpunkt eine Stunde lang nicht erreichbar war, ist es immer noch da: Jedes Event bleibt 90 Tage lang über die API abrufbar.

Der Frame meldet, was in ihm geschieht; Ihr Webhook meldet, was irgendwo geschieht. Bauen Sie auf dem Zweiten auf, und nutzen Sie das Erste für die Person vor dem Bildschirm.

Open Source, zwei Pakete

Das SDK ist klein genug, um es in einem Rutsch zu lesen, und genau das ist der Punkt. @gingerdocs/embed ist frameworkfrei, unter 1,5 KB gzippt und ohne Abhängigkeiten; @gingerdocs/react verpackt es in eine Komponente. Beide stehen unter MIT-Lizenz und liegen auf GitHub unter gingerdocs/embed-sdk und gingerdocs/embed-react-sdk, wo die Issue-Tracker offen sind.

Ein lesbares SDK ist der Weg, auf dem aus dem Sicherheitsversprechen oben etwas wird, das Sie nachprüfen können, statt etwas, das Sie auf Vertrauen hinnehmen.

Preise, und wo Sie anfangen

Bauen Sie kostenlos auf Test-Keys. Gehen Sie mit dem Developer plan live: 100 $ im Jahr für alles aus Pro, dieselben 1.000 Dokument-Uploads im Monat und Live-API-Keys. Die Details finden Sie auf der Preisseite.

Beginnen Sie mit dem Quickstart: vom frischen Konto zum unterschriebenen Dokument in vier Aufrufen, in Ihrem Terminal, in etwa zehn Minuten. Die Entwicklerseite bietet den Überblick, und die API-Referenz ist da, wenn Sie jedes einzelne Feld brauchen.