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 qualifiées
• Webhooks
• Référence
• Erreurs et limites
• Transferts

Démarrage rapide

1. 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.
2. Demandez le scope sign. Faites passer les personnes par le parcours habituel Se connecter avec Dazr Identity avec scope=openid sign (ajoutez offline_access pour 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, email et les autres), la Dazr Identity API doit aussi être activée.
3. Appelez l’API avec le jeton d’accès. L’adresse de base est https://sign.dazr.eu/api/sign/v1. Envoyez Authorization: Bearer <access token> et du JSON.
4. 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.

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 qualifiées

Chaque signataire a un level : "advanced" (par défaut : l’adresse e-mail est confirmée par la connexion avec Dazr Identity) ou "qualified". Une personne qui appose une signature qualifiée télécharge le PDF dans Dazr Sign, le signe avec sa propre signature électronique qualifiée (une carte d’identité électronique, une application de signature comme itsme, un certificat qualifié dans Adobe Acrobat Reader) et envoie le fichier signé. Dazr Sign le vérifie avec les listes de confiance de l’UE et ne l’accepte que s’il s’agit d’une signature qualifiée exactement sur le fichier remis. Dazr ne délivre pas de signatures qualifiées.

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.

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.

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.

• 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.