Dazr Sign API: Dokumentation für Entwickler
Bereiten Sie Dokumente aus Ihrer eigenen Software zur Unterschrift vor und versenden Sie sie im Namen der Menschen, die sie nutzen. Unterschrieben wird wie gewohnt mit Dazr Sign: angemeldet mit Dazr Identity, in der festgelegten Reihenfolge, einmal.
- Schnellstart
- Text-Tags
- Pop-ups
- Signaturen mit Ausweisprüfung
- Qualifizierte Signaturen
- Qualifizierte Signaturen verlangen
- Zertifikate über Dazr
- Webhooks
- Referenz
- Fehler und Grenzen
- Übertragungen
Schnellstart
- 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.
- Fordern Sie den Scope
signan. Leiten Sie Ihre Nutzer durch den üblichen Ablauf Mit Dazr Identity anmelden mitscope=openid sign(mitoffline_accessfü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,emailund die anderen) muss auch die Dazr Identity API aktiviert sein. - Rufen Sie die API mit dem Zugriffstoken auf. Die Basisadresse ist
https://sign.dazr.eu/api/sign/v1. Senden SieAuthorization: Bearer <access token>und JSON. - 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.
| Tag | Feld |
|---|---|
{{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.
Pop-ups: vorbereiten und unterschreiben
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.
| Anfrage | Was sie bewirkt |
|---|---|
POST /documents | Erstellt 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_template | Erstellt einen Entwurf aus einer Vorlage: template_id, recipients als { role, name, email }, values nach Feld-ID oder Beschriftung. |
GET /documents | Listet 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}/send | Versendet einen Entwurf. |
POST /documents/{id}/remind | Erinnert die Unterzeichnenden, die an der Reihe sind (höchstens einmal pro Stunde). |
POST /documents/{id}/void | Storniert 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_url | Ein neues Vorbereitungs-Pop-up für einen Entwurf: origin, redirect_uri, state. |
POST /documents/{id}/recipients/{recipient_id}/signing_url | Ein Unterschrifts-Pop-up für eine unterzeichnende Person, die an der Reihe ist: origin, redirect_uri, state. |
GET /documents/{id}/original.pdf | Das PDF, wie es versendet wurde. |
GET /documents/{id}/signed.pdf | Die versiegelte Kopie, sobald alle unterschrieben haben. |
GET /documents/{id}/audit.json | Der Prüfpfad: Ereignisse, Hashes und Unterzeichnende. |
GET /documents/{id}/audit.pdf | Das separate, versiegelte Prüfprotokoll eines Dokuments mit qualifizierten Signaturen, sobald alle unterschrieben haben. |
POST /uploads | Startet einen Upload in Teilen für PDFs über 4 MB: size. Danach PUT /uploads/{upload_id}/parts/{n} mit den Rohbytes jedes Teils. |
GET /templates | Die Vorlagen der Person, mit Rollen und Feldern. |
GET /templates/{id} | Eine Vorlage. |
POST /templates | Speichert 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.
| Status | Codes |
|---|---|
400 | invalid_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) |
401 | unauthenticated, invalid_token (abgelaufen oder widerrufen, oder die Person hat Ihre App entfernt) |
402 | payment_required, mit checkout_url und amount |
403 | insufficient_scope, sign_api_disabled |
404 | not_found (auch für Dokumente, die Ihre App nicht erstellt hat), template_not_found |
409 | not_draft, not_sent, not_your_turn, not_signable, signer_without_fields, no_signers, void_first, idempotency_in_progress, payment_in_progress |
413 | pdf_too_large, too_large, quota |
422 | idempotency_key_reused, qualified_signature_required (eine unterschreibende Person mit level simple, obwohl qualifizierte Signaturen verlangt sind) |
429 | rate_limited, mit einem Header Retry-After |
502 | payment_unavailable |
- PDFs bis 25 MB und 200 Seiten, ohne Passwort. Anfragen bis 4 MB; größere PDFs laufen über
/uploads. - Bis zu 20 Empfangende und 400 Felder pro Dokument, 100 Vorlagen pro Person. Dokumente und Vorlagen zählen zum Dazr-Speicher der Person.
- 120 Anfragen pro Minute je Person und App, 30 neue Dokumente alle 10 Minuten und 30 Versendungen pro Stunde.
- Zugriffstokens gelten 10 Minuten. Verwenden Sie das Refresh-Token (
offline_access), um ein neues zu erhalten.
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.
- Dokumente, die Ihre App vor der Übertragung erstellt hat, bleiben bei den Menschen, denen sie gehören. Die App sieht sie über die API nicht mehr, und für sie werden keine Webhooks gesendet.
- Die Webhook-URL und die Pop-up-Origins bleiben. Das Signatur-Secret für Webhooks wird erneuert und der annehmenden Person einmal angezeigt.
- Zugriffs- und Refresh-Tokens aus der Zeit vor der Übertragung funktionieren nicht mehr, und die Menschen stimmen bei der nächsten Anmeldung erneut zu. Vorlagen gehören den Menschen und bleiben unverändert.
- Die Dokumentzahlen im Sign-Portal beginnen ab der Übertragung neu.