Dazr Sign API : documentation pour les développeurs
Préparez et envoyez des documents à signer depuis votre logiciel, au nom des personnes qui l’utilisent. Les signataires signent comme d’habitude avec Dazr Sign : connectés avec Dazr Identity, à leur tour, une seule fois.
- Démarrage rapide
- Balises de texte
- Fenêtres
- Signatures avec identité vérifiée
- Signatures qualifiées
- Exiger des signatures qualifiées
- Certificats via Dazr
- Webhooks
- Référence
- Erreurs et limites
- Transferts
Démarrage rapide
- Activez la Dazr Sign API. Dans le portail Sign, ouvrez Développeurs et choisissez Activer la Dazr Sign API pour votre application. Chaque application de votre organisation y figure, ainsi que dans la console Dazr Identity, avec le même identifiant client et le même secret ; chaque API s’active séparément. Vous pouvez aussi y enregistrer une nouvelle application.
- Demandez le scope
sign. Faites passer les personnes par le parcours habituel Se connecter avec Dazr Identity avecscope=openid sign(ajoutezoffline_accesspour un jeton d’actualisation). L’écran de consentement indique que votre application peut préparer et envoyer des documents à signer en leur nom, et en voir le statut. La Dazr Sign API suffit ; pour demander aussi des données des personnes (profile,emailet les autres), la Dazr Identity API doit aussi être activée. - Appelez l’API avec le jeton d’accès. L’adresse de base est
https://sign.dazr.eu/api/sign/v1. EnvoyezAuthorization: Bearer <access token>et du JSON. - Créez et envoyez un document. Téléversez un PDF avec des balises de texte et une liste de destinataires, puis envoyez-le, ou ouvrez la fenêtre de préparation pour que la personne place les champs.
// 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"
Balises de texte
Saisissez les champs dans le PDF sous forme de texte. Chaque balise est remplacée par un champ de même taille ou plus grand, et le texte de la balise est recouvert : les signataires ne le voient jamais.
| Balise | Champ |
|---|---|
{{signature:1}} | Signature du premier destinataire |
{{initials:2}} | Initiales du deuxième destinataire |
{{name:1}} {{date:1}} | Nom et date de signature, remplis par Dazr Sign |
{{text:2:Company}} | Un champ de texte avec l’étiquette Company |
{{checkbox:2:Terms:optional}} | Une case à cocher facultative |
{{company:1}} | Nom de l’entreprise (rempli quand la personne signe au nom d’une organisation) |
Le nombre est la position du destinataire dans recipients, à partir de 1. Une balise pour un destinataire non indiqué ajoute un destinataire vide, à compléter dans la fenêtre de préparation. Envoyez "text_tags": false pour ignorer les balises. Vous pouvez aussi envoyer fields avec des positions en points (1/72 de pouce) depuis le coin supérieur gauche de la page : { "recipient": 1, "type": "signature", "page": 1, "x": 72, "y": 600, "width": 180, "height": 48 }. Un value sur un champ texte, entreprise ou case à cocher le fixe : le signataire le voit sans pouvoir le modifier.
Fenêtres : préparer et signer
Créez un brouillon avec "prepare": { "origin": "https://app.example.eu" } et vous obtenez une prepare_url. Ouvrez-la dans une fenêtre : la personne place les destinataires et les champs dans un éditeur compact, puis clique sur Envoyer ou Enregistrer comme modèle. Pour un signataire dont c’est le tour, POST /documents/{id}/recipients/{recipient_id}/signing_url donne une fenêtre de signature. Les deux liens sont valables 10 à 15 minutes et fonctionnent une seule fois. Si nécessaire, la personne se connecte à Dazr Identity dans la fenêtre, avec l’adresse à laquelle le document a été envoyé.
Une fois terminé, la fenêtre envoie { type: 'dazr-sign', event, document_id, template_id, recipient_id, state } avec postMessage à la page qui l’a ouverte, seulement si cette page se trouve sur l’une des origines de fenêtre de votre application (par défaut, les origines de vos URI de redirection), puis se ferme. event vaut sent, saved, cancelled, signed ou declined. Avec redirect_uri (l’une de vos URI de redirection enregistrées) et state, une fenêtre qui a perdu sa page d’origine y retourne avec les mêmes valeurs en paramètres de requête.
<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>
Si votre page envoie Cross-Origin-Opener-Policy: same-origin, utilisez plutôt same-origin-allow-popups, sinon la fenêtre ne peut pas transmettre le résultat.
Signatures avec identité vérifiée
Un signataire de niveau "simple" peut se voir demander une signature avec identité vérifiée, une signature électronique avancée au sens d’eIDAS : { "name": "Mario Rossi", "email": "mario@example.eu", "id_verified": true }. Elle est désactivée tant que vous ne la demandez pas, et seulement pour les signataires de niveau "simple" (sinon 400 invalid_id_verified ; un document ne peut pas la mélanger avec des signataires qualifiés : 400 id_verification_with_qualified). Le signataire signe comme d’habitude, puis fait vérifier son identité avec Dazr Identity : une photo de sa pièce d’identité et un selfie, examinés par une personne de Dazr, ou une vérification qu’il a déjà, avec son accord. Les modèles la gardent par rôle, et from_template accepte id_verified par destinataire.
La signature compte, et le document se termine, seulement une fois la vérification approuvée. D’ici là, le document reste sent avec waiting_for_id_verification à true et sans PDF signé. Les destinataires ont id_verified et id_verification : status (not_signed, to_verify, verifying, review, verified ou rejected), verified_at et name_matches. Les webhooks ajoutent sign.document.id_verified et sign.document.id_rejected. Après un refus, l’expéditeur peut demander au signataire de signer de nouveau dans le portail Sign ; la signature ne compte jamais comme simple à la place.
Chaque vérification coûte EUR 1,50 HT, prélevés sur le solde de l’organisation de l’app quand le signataire la lance ou en utilise une existante (une fois par vérification et par organisation). send répond 402 id_verification_payer quand l’app n’a pas d’organisation et 402 id_verification_balance (avec needCents) quand le solde ne couvre pas les signataires avec vérification d’identité.
Signatures qualifiées
Chaque signataire a un level : "simple" (par défaut : une signature électronique simple au sens d’eIDAS, avec l’adresse e-mail confirmée par la connexion avec Dazr Identity, une piste d’audit détaillée et un PDF scellé) ou "qualified". "advanced", le nom utilisé avant le 13 octobre 2026, est toujours accepté et signifie "simple" ; les réponses et les webhooks indiquent "simple". Un signataire qualifié télécharge le PDF dans Dazr Sign, le signe avec sa propre signature électronique qualifiée (une carte d’identité électronique ou un certificat qualifié dans Adobe Acrobat Reader) et dépose le fichier signé. Dazr Sign le vérifie sur les listes de confiance de l’UE et ne l’accepte que s’il s’agit d’une signature qualifiée sur exactement le fichier remis. Dazr ne délivre pas de certificats.
Définissez le niveau par destinataire : { "name": "Mario Rossi", "email": "mario@example.eu", "level": "qualified" }. Une personne qui appose une signature qualifiée n’a pas de champ de paraphe. name_rule sur le document indique ce qui se passe si le nom du certificat diffère de celui du destinataire : "warn" (par défaut : acceptée, avec name_matches à false) ou "block" (refusée). Les modèles conservent le niveau de chaque rôle, et from_template peut passer un rôle à "qualified".
Chaque signature reste valide : les signatures suivantes et le sceau final de Dazr sont ajoutés en mises à jour incrémentielles, et la piste d’audit d’un tel document est un PDF scellé distinct à GET /documents/{id}/audit.pdf. Les destinataires dans les documents et les webhooks ont level et, après une signature qualifiée, 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 ou CAdES) et name_matches. Tout autre level renvoie 400 invalid_level.
Exiger des signatures qualifiées
Les propriétaires et administrateurs d’une organisation peuvent exiger une signature électronique qualifiée de toutes les personnes qui signent : pour les documents qu’une application crée (la page de l’application sous Développeurs dans le portail Sign) ou pour les documents envoyés par les membres de l’organisation (Paramètres dans le portail Sign). Dazr Sign l’applique sur le serveur. Une personne sans level signe en qualifié, "level": "simple" renvoie 422 qualified_signature_required avec l’index du destinataire, les rôles des modèles passent en qualifié (demander un rôle simple à from_template renvoie 400 qualified_signature_required) et un document n’est terminé que lorsque chaque signature qualifiée a été vérifiée. Les documents indiquent qes_required.
Certificats via Dazr
Dazr ne délivre pas de certificats, mais peut en obtenir un auprès d’un prestataire de services de confiance qualifié quand cette option est activée. Alors "provider_allowed": true sur un signataire qualifié qui n’en a pas lui permet d’obtenir ainsi un certificat qualifié. Il confirme son identité auprès du prestataire (pièce d’identité, appel vidéo) puis signe sur la page de signature avec un code à usage unique de l’application du prestataire. Dazr ne conserve jamais les identifiants de signature : le nom de l’appareil, le code PIN et le code à usage unique vont au prestataire pour cette seule signature. Le PDF signé est vérifié comme un dépôt. Le certificat appartient au signataire pendant 3 ans et signe ses documents Dazr suivants sans frais supplémentaires. Dans certificate, issued_through nomme le prestataire (null pour le certificat propre du signataire).
Cette option n’est pas activée pour le moment : provider_allowed est accepté et reste sans effet d’ici là.
La personne qui signe paie sur la page de signature (par défaut), ou l’organisation de l’application paie à l’avance : "qes_payer": "organisation" sur le document, ou le paramètre de l’application. send répond alors 402 payment_required avec checkout_url (une page de paiement) et amount (net, vat, total, certificates), et le document est envoyé dès réception du paiement (sign.document.sent). Un certificat prépayé que personne n’utilise est remboursé quand le document est terminé, annulé, refusé ou expiré. Les documents indiquent qes_payer : "signer" ou "organisation".
Webhooks
Définissez une URL de webhook pour votre application dans le portail Sign, sous Développeurs. Vous voyez son secret de signature une seule fois. Dazr Sign envoie sign.document.sent, viewed, signed, completed, declined, voided et expired pour les documents créés par votre application, avec le statut du document et de ses destinataires, jamais son contenu. Les envois échoués sont retentés après 5 minutes, 30 minutes, 2, 6, 12 et 24 heures ; le journal des envois montre chaque tentative et permet d’en renvoyer un.
// 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: [...] } } }
Référence
Tous les chemins commencent par https://sign.dazr.eu/api/sign/v1. Les heures sont au format ISO 8601, en UTC.
| Requête | Ce qu’elle fait |
|---|---|
POST /documents | Crée un brouillon à partir d’un PDF : file en base64, un envoi multipart (file plus data en JSON) ou un upload_id. Facultatif : title, message, recipients, fields, signing_order, deadline_days, reminder_days, send, prepare. |
POST /documents/from_template | Crée un brouillon à partir d’un modèle : template_id, recipients sous la forme { role, name, email }, values par identifiant ou étiquette de champ. |
GET /documents | Liste les documents de votre application pour cette personne, du plus récent au plus ancien : limit (jusqu’à 100), cursor, status. |
GET /documents/{id} | Le document avec son statut, ses destinataires et ses champs. |
POST /documents/{id}/send | Envoie un brouillon. |
POST /documents/{id}/remind | Relance les signataires dont c’est le tour (une fois par heure au plus). |
POST /documents/{id}/void | Annule un document en cours de signature, avec un reason facultatif. |
DELETE /documents/{id} | Supprime un brouillon ou un document clôturé. |
POST /documents/{id}/prepare_url | Une nouvelle fenêtre de préparation pour un brouillon : origin, redirect_uri, state. |
POST /documents/{id}/recipients/{recipient_id}/signing_url | Une fenêtre de signature pour un signataire dont c’est le tour : origin, redirect_uri, state. |
GET /documents/{id}/original.pdf | Le PDF tel qu’il a été envoyé. |
GET /documents/{id}/signed.pdf | La copie scellée, une fois que tout le monde a signé. |
GET /documents/{id}/audit.json | La piste d’audit : événements, empreintes et signataires. |
GET /documents/{id}/audit.pdf | La piste d’audit distincte et scellée d’un document avec des signatures qualifiées, une fois que tout le monde a signé. |
POST /uploads | Démarre un envoi en plusieurs parties pour les PDF de plus de 4 Mo : size. Puis PUT /uploads/{upload_id}/parts/{n} avec les octets bruts de chaque partie. |
GET /templates | Les modèles de la personne, avec leurs rôles et leurs champs. |
GET /templates/{id} | Un modèle. |
POST /templates | Enregistre l’un des documents de votre application comme modèle : document_id, name. |
DELETE /templates/{id} | Supprime un modèle. |
Envoyez un en-tête Idempotency-Key lorsque vous créez un document : la même clé et le même corps dans les 24 heures renvoient le même document (en-tête Idempotent-Replayed: true) au lieu d’en créer un second.
Erreurs et limites
Les erreurs ont un statut HTTP et un corps comme { "error": { "code": "not_found", "message": "..." } }, parfois avec des détails comme index.
| Statut | 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 (expiré ou révoqué, ou la personne a retiré votre application) |
402 | payment_required, avec checkout_url et amount |
403 | insufficient_scope, sign_api_disabled |
404 | not_found (aussi pour les documents que votre application n’a pas créés), 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 (une personne qui signe avec level simple alors que des signatures qualifiées sont exigées) |
429 | rate_limited, avec un en-tête Retry-After |
502 | payment_unavailable |
- PDF jusqu’à 25 Mo et 200 pages, sans mot de passe. Requêtes jusqu’à 4 Mo ; les PDF plus lourds passent par
/uploads. - Jusqu’à 20 destinataires et 400 champs par document, 100 modèles par personne. Les documents et les modèles comptent dans le stockage Dazr de la personne.
- 120 requêtes par minute par personne et par application, 30 nouveaux documents toutes les 10 minutes et 30 envois par heure.
- Les jetons d’accès durent 10 minutes. Utilisez le jeton d’actualisation (
offline_access) pour en obtenir un nouveau.
Transférer une application
Une application peut passer à une autre organisation inscrite sur Dazr, avec Transférer l’application dans ses réglages. Avec l’API Dazr Sign activée, elle ne peut aller qu’à une organisation vérifiée, et une personne qui gère cette organisation doit accepter dans les 14 jours. La documentation développeurs de Dazr Identity décrit chaque étape.
- Les documents créés par votre application avant le transfert restent aux personnes à qui ils appartiennent. L’application ne les voit plus via l’API, et aucun webhook n’est envoyé pour eux.
- L’URL du webhook et les origines des fenêtres contextuelles restent. Le secret de signature du webhook est renouvelé et affiché une seule fois à la personne qui accepte.
- Les jetons d’accès et d’actualisation émis avant le transfert cessent de fonctionner, et les personnes approuvent à nouveau l’application à leur prochaine connexion. Les modèles appartiennent aux personnes et ne changent pas.
- Les chiffres de documents dans le portail Sign repartent du transfert.