Dazr Sign API: Dokumentation für Entwickler

Schnellstart

  1. Aktivieren Sie die Dazr Sign API. Öffnen Sie im Sign-Portal Entwickler und wählen Sie für Ihre App Dazr Sign API aktivieren. Jede App Ihrer Organisation steht dort und in der Konsole von Dazr Identity, mit derselben Client-ID und demselben Secret; jede API wird einzeln aktiviert. Dort können Sie auch eine neue App registrieren.
  2. Fordern Sie den Scope sign an. Leiten Sie Ihre Nutzer durch den üblichen Ablauf Mit Dazr Identity anmelden mit scope=openid sign (mit offline_access für ein Refresh-Token). Der Zustimmungsbildschirm erklärt, dass Ihre App in ihrem Namen Dokumente zur Unterschrift vorbereiten und versenden und deren Status sehen darf. Dafür genügt die Dazr Sign API; für Daten der Menschen (profile, email und die anderen) muss auch die Dazr Identity API aktiviert sein.
  3. Rufen Sie die API mit dem Zugriffstoken auf. Die Basisadresse ist https://sign.dazr.eu/api/sign/v1. Senden Sie Authorization: Bearer <access token> und JSON.
  4. Erstellen und versenden Sie ein Dokument. Laden Sie ein PDF mit Text-Tags und einer Empfängerliste hoch und versenden Sie es, oder öffnen Sie das Vorbereitungs-Pop-up, damit die Person die Felder selbst platziert.
// Node 18+: create a document from a PDF with text tags, then send it
import fs from 'node:fs';
const api = 'https://sign.dazr.eu/api/sign/v1';
const headers = { Authorization: 'Bearer ' + accessToken, 'Content-Type': 'application/json' };

let res = await fetch(api + '/documents', {
  method: 'POST',
  headers: { ...headers, 'Idempotency-Key': 'order-1042' },
  body: JSON.stringify({
    title: 'Service agreement',
    file: fs.readFileSync('agreement.pdf').toString('base64'),
    recipients: [
      { name: 'Alex Example', email: 'alex@example.eu' },
      { name: 'Sam Client', email: 'sam@client.example' },
    ],
  }),
});
const { document } = await res.json();

res = await fetch(api + '/documents/' + document.id + '/send', { method: 'POST', headers });
console.log((await res.json()).document.status); // "sent"

Text-Tags

Schreiben Sie die Felder als Text in das PDF. Jedes Tag wird durch ein gleich großes oder größeres Feld ersetzt, und der Tag-Text wird überdeckt, sodass Unterzeichnende ihn nie sehen.

TagFeld
{{signature:1}}Unterschrift der ersten empfangenden Person
{{initials:2}}Initialen der zweiten empfangenden Person
{{name:1}} {{date:1}}Name und Datum der Unterschrift, von Dazr Sign ausgefüllt
{{text:2:Company}}Ein Textfeld mit der Beschriftung Company
{{checkbox:2:Terms:optional}}Ein optionales Kontrollkästchen
{{company:1}}Firmenname (ausgefüllt, wenn die Person im Namen einer Organisation unterschreibt)

Die Zahl ist die Position der empfangenden Person in recipients, ab 1. Ein Tag für eine nicht aufgeführte empfangende Person fügt eine leere hinzu, die im Vorbereitungs-Pop-up ergänzt wird. Senden Sie "text_tags": false, um Tags zu ignorieren. Sie können auch fields mit Positionen in Punkten (1/72 Zoll) ab der linken oberen Ecke der Seite senden: { "recipient": 1, "type": "signature", "page": 1, "x": 72, "y": 600, "width": 180, "height": 48 }. Ein value in einem Text-, Firmen- oder Kontrollkästchenfeld legt es fest: Die unterzeichnende Person sieht es und kann es nicht ändern.

Erstellen Sie einen Entwurf mit "prepare": { "origin": "https://app.example.eu" }, und Sie erhalten eine prepare_url. Öffnen Sie sie in einem Pop-up: Die Person platziert Empfangende und Felder in einem kompakten Editor und klickt dann auf Senden oder Als Vorlage speichern. Für eine unterzeichnende Person, die an der Reihe ist, liefert POST /documents/{id}/recipients/{recipient_id}/signing_url ein Unterschrifts-Pop-up. Beide Links gelten 10 bis 15 Minuten und funktionieren einmal. Bei Bedarf meldet sich die Person im Pop-up bei Dazr Identity an, mit der Adresse, an die das Dokument gesendet wurde.

Danach sendet das Pop-up { type: 'dazr-sign', event, document_id, template_id, recipient_id, state } per postMessage an die Seite, die es geöffnet hat, nur wenn diese Seite auf einem der Pop-up-Origins Ihrer App liegt (standardmäßig die Origins Ihrer Redirect-URIs), und schließt sich. event ist sent, saved, cancelled, signed oder declined. Mit redirect_uri (einer Ihrer registrierten Redirect-URIs) und state kehrt ein Pop-up ohne öffnende Seite dorthin zurück, mit denselben Werten als Query-Parameter.

<script src="https://sign.dazr.eu/sdk.js"></script>
<script>
document.querySelector('#sign').addEventListener('click', async () => {
  // Ask your server for the URL after the click: the popup opens at once.
  const url = fetch('/my-server/prepare-url').then(r => r.json()).then(j => j.prepare_url);
  const result = await DazrSign.open(url);
  if (result.event === 'sent') showSent(result.document_id);
  // 'closed': the window was closed; check the status with the API or a webhook
});
</script>

Wenn Ihre Seite Cross-Origin-Opener-Policy: same-origin sendet, verwenden Sie stattdessen same-origin-allow-popups, sonst kann das Pop-up nichts zurückmelden.

Signaturen mit Ausweisprüfung

Eine Person mit Stufe "simple" kann um eine Signatur mit Ausweisprüfung gebeten werden, eine fortgeschrittene elektronische Signatur nach eIDAS: { "name": "Mario Rossi", "email": "mario@example.eu", "id_verified": true }. Sie ist aus, solange Sie sie nicht setzen, und nur für Personen mit Stufe "simple" möglich (sonst 400 invalid_id_verified; ein Dokument kann sie nicht mit qualifiziert Unterzeichnenden mischen: 400 id_verification_with_qualified). Die Person unterschreibt wie gewohnt und bestätigt danach ihre Identität mit Dazr Identity: ein Foto ihres Ausweisdokuments und ein Selfie, geprüft von einer Person bei Dazr, oder eine Prüfung, die sie schon hat, mit ihrer Zustimmung. Vorlagen behalten sie pro Rolle, und from_template nimmt id_verified pro Empfänger an.

Die Unterschrift zählt, und das Dokument wird abgeschlossen, erst wenn die Prüfung bestätigt ist. Bis dahin bleibt das Dokument sent mit waiting_for_id_verification true und ohne unterschriebenes PDF. Empfänger haben id_verified und id_verification: status (not_signed, to_verify, verifying, review, verified oder rejected), verified_at und name_matches. Webhooks kommen hinzu: sign.document.id_verified und sign.document.id_rejected. Nach einer Ablehnung kann der Absender die Person im Sign-Portal erneut um die Unterschrift bitten; die Unterschrift zählt nie stattdessen als einfache.

Jede Prüfung kostet EUR 1,50 zzgl. MwSt. aus dem Guthaben der Organisation der App, abgebucht, wenn die Person sie startet oder eine bestehende verwendet (einmal pro Prüfung und Organisation). send antwortet 402 id_verification_payer, wenn die App keine Organisation hat, und 402 id_verification_balance (mit needCents), wenn das Guthaben die Personen mit Ausweisprüfung nicht abdeckt.

Qualifizierte Signaturen

Jede unterzeichnende Person hat ein level: "simple" (Standard: eine einfache elektronische Signatur nach eIDAS, die E-Mail-Adresse bestätigt durch die Anmeldung mit Dazr Identity, mit ausführlichem Prüfprotokoll und versiegeltem PDF) oder "qualified". "advanced", der Name vor dem 13. Oktober 2026, wird weiter angenommen und bedeutet "simple"; Antworten und Webhooks nennen "simple". Eine qualifiziert unterzeichnende Person lädt das PDF in Dazr Sign herunter, signiert es mit ihrer eigenen qualifizierten elektronischen Signatur (elektronischer Personalausweis oder ein qualifiziertes Zertifikat in Adobe Acrobat Reader) und lädt die signierte Datei hoch. Dazr Sign prüft sie anhand der EU-Vertrauenslisten und akzeptiert sie nur, wenn es eine qualifizierte Signatur auf genau der ausgegebenen Datei ist. Dazr stellt selbst keine Zertifikate aus.

Legen Sie das Niveau pro empfangende Person fest: { "name": "Mario Rossi", "email": "mario@example.eu", "level": "qualified" }. Wer qualifiziert unterschreibt, hat keine Initialenfelder. name_rule am Dokument legt fest, was passiert, wenn der Name im Zertifikat vom Namen der empfangenden Person abweicht: "warn" (Standard: angenommen, mit name_matches false) oder "block" (abgelehnt). Vorlagen behalten das Niveau jeder Rolle, und from_template kann eine Rolle auf "qualified" anheben.

Jede Signatur bleibt gültig: Spätere Signaturen und das abschließende Dazr-Siegel werden als inkrementelle Aktualisierungen hinzugefügt, und das Prüfprotokoll eines solchen Dokuments ist ein separates versiegeltes PDF unter GET /documents/{id}/audit.pdf. Empfangende Personen in Dokumenten und Webhooks haben level und, sobald qualifiziert unterschrieben wurde, certificate: subject (common_name, given_name, surname, serial_number, country, organization, organization_identifier), issuer, serial, sha256, trust_service_provider, trusted_list_country, signing_time, trusted_timestamp, format (PAdES oder CAdES) und name_matches. Jedes andere level ergibt 400 invalid_level.

Qualifizierte Signaturen verlangen

Inhaber und Admins einer Organisation können von allen, die unterschreiben, eine qualifizierte elektronische Signatur verlangen: für die Dokumente, die eine App erstellt (die Seite der App unter Entwickler im Sign-Portal), oder für die Dokumente, die Mitglieder der Organisation senden (Einstellungen im Sign-Portal). Dazr Sign setzt das auf dem Server durch. Wer ohne level unterschreibt, unterschreibt qualifiziert, "level": "simple" ergibt 422 qualified_signature_required mit dem index der empfangenden Person, Rollen aus Vorlagen werden qualifiziert (eine einfache Rolle bei from_template ergibt 400 qualified_signature_required), und ein Dokument wird erst abgeschlossen, wenn jede qualifizierte Signatur geprüft ist. Dokumente zeigen qes_required.

Zertifikate über Dazr

Dazr stellt selbst keine Zertifikate aus, kann aber eines bei einem qualifizierten Vertrauensdiensteanbieter besorgen, wenn diese Option aktiviert ist. Dann erlaubt "provider_allowed": true bei einer qualifiziert unterzeichnenden Person ohne Zertifikat, auf diesem Weg ein qualifiziertes Zertifikat zu erhalten. Sie bestätigt beim Anbieter, wer sie ist (Ausweisdokument, Videoanruf), und signiert dann auf der Signaturseite mit einem Einmalcode aus der App des Anbieters. Dazr speichert niemals Signaturdaten: Gerätename, PIN und Einmalcode gehen nur für diese eine Signatur an den Anbieter. Das signierte PDF wird wie ein Upload geprüft. Das Zertifikat gehört 3 Jahre lang der Person selbst und signiert spätere Dazr-Dokumente ohne Zusatzkosten. In certificate nennt issued_through den Anbieter (null beim eigenen Zertifikat der Person).

Diese Option ist derzeit nicht aktiviert: provider_allowed wird akzeptiert und hat bis dahin keine Wirkung.

Die unterschreibende Person bezahlt auf der Signaturseite (Standard), oder die Organisation der App bezahlt im Voraus: "qes_payer": "organisation" am Dokument oder die Einstellung der App. Dann antwortet send mit 402 payment_required mit checkout_url (eine Zahlungsseite) und amount (net, vat, total, certificates), und das Dokument wird versendet, sobald die Zahlung eingegangen ist (sign.document.sent). Ein vorausbezahltes Zertifikat, das niemand nutzt, wird erstattet, wenn das Dokument abgeschlossen, abgebrochen, abgelehnt oder abgelaufen ist. Dokumente zeigen qes_payer: "signer" oder "organisation".

Webhooks

Legen Sie im Sign-Portal unter Entwickler eine Webhook-URL für Ihre App fest. Das Signatur-Secret sehen Sie einmal. Dazr Sign sendet sign.document.sent, viewed, signed, completed, declined, voided und expired für die Dokumente, die Ihre App erstellt hat, mit dem Status des Dokuments und der Empfangenden, nie mit dem Inhalt. Fehlgeschlagene Zustellungen werden nach 5 Minuten, 30 Minuten, 2, 6, 12 und 24 Stunden wiederholt; das Zustellprotokoll zeigt jeden Versuch und kann eine Zustellung erneut senden.

// Node: check the Dazr-Signature header (t=<unix time>,v1=<HMAC-SHA256 hex>)
import crypto from 'node:crypto';

export function verify(rawBody, header, secret) {
  const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(header || '');
  if (!m || Math.abs(Date.now() / 1000 - Number(m[1])) > 300) return false;
  const want = crypto.createHmac('sha256', secret).update(m[1] + '.' + rawBody).digest();
  return crypto.timingSafeEqual(want, Buffer.from(m[2], 'hex'));
}
// The body: { id, type: 'sign.document.completed', created, data: { document: { id, status, recipients: [...] } } }

Referenz

Alle Pfade beginnen mit https://sign.dazr.eu/api/sign/v1. Zeiten sind ISO 8601 in UTC.

AnfrageWas sie bewirkt
POST /documentsErstellt einen Entwurf aus einem PDF: file in Base64, ein Multipart-Upload (file plus data als JSON) oder eine upload_id. Optional: title, message, recipients, fields, signing_order, deadline_days, reminder_days, send, prepare.
POST /documents/from_templateErstellt einen Entwurf aus einer Vorlage: template_id, recipients als { role, name, email }, values nach Feld-ID oder Beschriftung.
GET /documentsListet die Dokumente Ihrer App für diese Person auf, neueste zuerst: limit (bis 100), cursor, status.
GET /documents/{id}Das Dokument mit Status, Empfangenden und Feldern.
POST /documents/{id}/sendVersendet einen Entwurf.
POST /documents/{id}/remindErinnert die Unterzeichnenden, die an der Reihe sind (höchstens einmal pro Stunde).
POST /documents/{id}/voidStorniert ein Dokument, das zur Unterschrift versendet ist, mit optionalem reason.
DELETE /documents/{id}Löscht einen Entwurf oder ein abgeschlossenes Dokument.
POST /documents/{id}/prepare_urlEin neues Vorbereitungs-Pop-up für einen Entwurf: origin, redirect_uri, state.
POST /documents/{id}/recipients/{recipient_id}/signing_urlEin Unterschrifts-Pop-up für eine unterzeichnende Person, die an der Reihe ist: origin, redirect_uri, state.
GET /documents/{id}/original.pdfDas PDF, wie es versendet wurde.
GET /documents/{id}/signed.pdfDie versiegelte Kopie, sobald alle unterschrieben haben.
GET /documents/{id}/audit.jsonDer Prüfpfad: Ereignisse, Hashes und Unterzeichnende.
GET /documents/{id}/audit.pdfDas separate, versiegelte Prüfprotokoll eines Dokuments mit qualifizierten Signaturen, sobald alle unterschrieben haben.
POST /uploadsStartet einen Upload in Teilen für PDFs über 4 MB: size. Danach PUT /uploads/{upload_id}/parts/{n} mit den Rohbytes jedes Teils.
GET /templatesDie Vorlagen der Person, mit Rollen und Feldern.
GET /templates/{id}Eine Vorlage.
POST /templatesSpeichert eines der Dokumente Ihrer App als Vorlage: document_id, name.
DELETE /templates/{id}Löscht eine Vorlage.

Senden Sie beim Erstellen eines Dokuments einen Header Idempotency-Key: Derselbe Schlüssel und derselbe Body innerhalb von 24 Stunden liefern dasselbe Dokument (Header Idempotent-Replayed: true) statt eines zweiten.

Fehler und Grenzen

Fehler haben einen HTTP-Status und einen Body wie { "error": { "code": "not_found", "message": "..." } }, manchmal mit Details wie index.

StatusCodes
400invalid_field, invalid_recipients, invalid_email, not_pdf, pdf_unreadable, pdf_encrypted, invalid_origin, invalid_redirect_uri, unknown_role, unknown_field, invalid_provider_allowed, invalid_qes_payer, qualified_signature_required (from_template)
401unauthenticated, invalid_token (abgelaufen oder widerrufen, oder die Person hat Ihre App entfernt)
402payment_required, mit checkout_url und amount
403insufficient_scope, sign_api_disabled
404not_found (auch für Dokumente, die Ihre App nicht erstellt hat), template_not_found
409not_draft, not_sent, not_your_turn, not_signable, signer_without_fields, no_signers, void_first, idempotency_in_progress, payment_in_progress
413pdf_too_large, too_large, quota
422idempotency_key_reused, qualified_signature_required (eine unterschreibende Person mit level simple, obwohl qualifizierte Signaturen verlangt sind)
429rate_limited, mit einem Header Retry-After
502payment_unavailable

Eine App übertragen

Eine App kann zu einer anderen Organisation auf Dazr wechseln, unter App übertragen in den Einstellungen der App. Mit aktivierter Dazr Sign API geht das nur an eine verifizierte Organisation, und eine Person mit der Rolle Inhaber oder Admin dort muss innerhalb von 14 Tagen annehmen. Die Entwicklerdokumentation von Dazr Identity beschreibt jeden Schritt.