Guides

Placement automatique des champs de signature avec des balises d'ancre : Positionnement de champ basé sur le texte

Écrit par

Illustration d'un champ de signature avec des coordonnées X et Y inconnues déplacé vers une zone de signature en surbrillance sur un document.

Si vous avez déjà positionné des champs de signature en calculant des coordonnées x/y sur un PDF, vous savez à quel point cela devient fastidieux à grande échelle. Modifiez la mise en page du document, et chaque coordonnée devient incorrecte. Ajoutez une deuxième page, et vous devez recalculer les décalages pour la moitié de vos champs.

Les balises d'ancrage (anchor tags) règlent ce problème. Intégrez des marqueurs de texte comme {{SIGN_HERE}} ou {{DATE}} directement dans votre modèle PDF, et Firma.dev les détecte automatiquement et place les bons types de champs à ces emplacements. Les marqueurs sont supprimés du document final, de sorte que les signataires ne les voient jamais. Un seul appel d'API, aucun calcul de coordonnées.

Les balises d'ancrage sont disponibles depuis la version v1.11.0 et prennent en charge tous les types de champs, des règles de correspondance flexibles et jusqu'à 100 balises par demande de signature.

Démarrage rapide

Le moyen le plus rapide d'utiliser les balises d'ancrage : intégrez un marqueur dans votre PDF, puis créez une demande de signature avec un tableau anchor_tags.

Étape 1 : Ajoutez le texte {{SIGN_HERE}} à l'endroit de votre PDF où vous souhaitez que le champ de signature apparaisse. Vous pouvez le faire dans l'outil de votre choix servant à générer vos documents, qu'il s'agisse d'un modèle Word, d'une bibliothèque PDF ou d'un service de génération de documents.

Étape 2 : Créez une demande de signature basée sur un document avec la définition de la balise d'ancrage :

const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      workspace_id: workspaceId,
      document: documentBase64,
      name: 'NDA - Acme Corp',
      anchor_tags: [
        {
          anchor_string: '{{SIGN_HERE}}',
          type: 'signature',
          recipient_id: 'temp_1',
          required: true
        }
      ],
      recipients: [
        {
          id: 'temp_1',
          first_name: 'Jane',
          last_name: 'Smith',
          email: 'jane@example.com',
          designation: 'Signer',
          order: 1
        }
      ]
    })
  }
);

const signingRequest = await response.json();
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      workspace_id: workspaceId,
      document: documentBase64,
      name: 'NDA - Acme Corp',
      anchor_tags: [
        {
          anchor_string: '{{SIGN_HERE}}',
          type: 'signature',
          recipient_id: 'temp_1',
          required: true
        }
      ],
      recipients: [
        {
          id: 'temp_1',
          first_name: 'Jane',
          last_name: 'Smith',
          email: 'jane@example.com',
          designation: 'Signer',
          order: 1
        }
      ]
    })
  }
);

const signingRequest = await response.json();
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      workspace_id: workspaceId,
      document: documentBase64,
      name: 'NDA - Acme Corp',
      anchor_tags: [
        {
          anchor_string: '{{SIGN_HERE}}',
          type: 'signature',
          recipient_id: 'temp_1',
          required: true
        }
      ],
      recipients: [
        {
          id: 'temp_1',
          first_name: 'Jane',
          last_name: 'Smith',
          email: 'jane@example.com',
          designation: 'Signer',
          order: 1
        }
      ]
    })
  }
);

const signingRequest = await response.json();

Firma.dev analyse le PDF pour trouver {{SIGN_HERE}}, place un champ de signature à cet endroit, l'attribue au destinataire et supprime le texte du marqueur du document. C'est tout.

Notez que les balises d'ancrage fonctionnent uniquement avec la création de demandes de signature basées sur des documents, et non sur des modèles. Vous envoyez le PDF brut et laissez le système d'ancrage gérer le placement des champs.

Types de champs pris en charge

Les balises d'ancrage prennent en charge tous les types de champs disponibles dans Firma.dev. Définissez la propriété type sur chaque balise d'ancrage sur l'une de ces valeurs :

signature pour les champs de signature, initials pour les champs de paraphe, text pour les champs de texte sur une seule ligne, textarea pour les champs de texte multiligne, date pour les champs de date, checkbox pour les cases à cocher, radio pour les groupes de boutons radio, dropdown pour les listes déroulantes, url pour les champs d'URL, stamp pour les champs de tampon, et file pour les champs de téléchargement de fichier.

Chaque type affiche le composant de champ approprié dans l'expérience de signature. Une balise d'ancrage date crée un sélecteur de date, une balise dropdown crée un menu déroulant, et ainsi de suite.

Options de correspondance et de positionnement

Le comportement de correspondance par défaut convient à la plupart des cas, mais vous pouvez affiner la manière dont Firma.dev trouve et positionne les champs créés par ancrage.

Sensibilité à la casse : Définissez case_sensitive sur true ou false (la valeur par défaut est false). Avec une correspondance insensible à la casse, {{sign_here}} et {{SIGN_HERE}} correspondent tous les deux.

Correspondance de mot entier : Définissez whole_word sur true pour empêcher les correspondances partielles. Si votre chaîne d'ancrage est SIGN et que whole_word est false, elle correspondrait également à SIGNATURE ou COSIGN. La définir sur true garantit qu'elle ne correspond qu'au mot exact.

Ciblage d'occurrences spécifiques : Si votre PDF contient la même chaîne d'ancrage plusieurs fois, vous pouvez cibler des occurrences spécifiques avec occurrence. Définissez-la sur 1 pour la première occurrence, 2 pour la deuxième, etc. Omettez-la ou définissez match_all sur true pour placer des champs à chaque occurrence.

Positionnement avec décalage : Ajustez l'emplacement exact où le champ se positionne par rapport au texte d'ancrage en utilisant offset_x et offset_y. Vous pouvez spécifier les décalages en pourcentages (par rapport aux dimensions de la page) ou en pixels. C'est pratique lorsque vous voulez que le champ soit placé légèrement en dessous ou à droite du marqueur, plutôt que directement dessus.

Gestion fluide des ancres manquantes : Définissez ignore_if_not_present sur true si la chaîne d'ancrage peut ne pas être présente dans chaque document. Sans cela, une ancre manquante renvoie une erreur. Lorsque cette option est activée, Firma.dev ignore simplement cette balise sans générer d'erreur et traite le reste.

Configuration avancée

Voici un exemple plus complet qui combine plusieurs balises d'ancrage avec différents types de champs, des dimensions personnalisées et des décalages de positionnement :

const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      workspace_id: workspaceId,
      document: documentBase64,
      name: 'Employment Agreement',
      anchor_tags: [
        {
          anchor_string: '{{EMPLOYEE_SIGNATURE}}',
          type: 'signature',
          recipient_id: 'temp_1',
          required: true,
          width: 30,
          height: 8,
          offset_y: 2
        },
        {
          anchor_string: '{{EMPLOYEE_DATE}}',
          type: 'date',
          recipient_id: 'temp_1',
          required: true
        },
        {
          anchor_string: '{{EMPLOYEE_INITIALS}}',
          type: 'initials',
          recipient_id: 'temp_1',
          required: true,
          match_all: true
        },
        {
          anchor_string: '{{MANAGER_SIGNATURE}}',
          type: 'signature',
          recipient_id: 'temp_2',
          required: true
        },
        {
          anchor_string: '{{BENEFITS_OPT_IN}}',
          type: 'checkbox',
          recipient_id: 'temp_1',
          required: false,
          ignore_if_not_present: true
        }
      ],
      recipients: [
        {
          id: 'temp_1',
          first_name: 'Sarah',
          last_name: 'Chen',
          email: 'sarah@example.com',
          designation: 'Signer',
          order: 1
        },
        {
          id: 'temp_2',
          first_name: 'Mike',
          last_name: 'Torres',
          email: 'mike@example.com',
          designation: 'Signer',
          order: 2
        }
      ]
    })
  }
);
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      workspace_id: workspaceId,
      document: documentBase64,
      name: 'Employment Agreement',
      anchor_tags: [
        {
          anchor_string: '{{EMPLOYEE_SIGNATURE}}',
          type: 'signature',
          recipient_id: 'temp_1',
          required: true,
          width: 30,
          height: 8,
          offset_y: 2
        },
        {
          anchor_string: '{{EMPLOYEE_DATE}}',
          type: 'date',
          recipient_id: 'temp_1',
          required: true
        },
        {
          anchor_string: '{{EMPLOYEE_INITIALS}}',
          type: 'initials',
          recipient_id: 'temp_1',
          required: true,
          match_all: true
        },
        {
          anchor_string: '{{MANAGER_SIGNATURE}}',
          type: 'signature',
          recipient_id: 'temp_2',
          required: true
        },
        {
          anchor_string: '{{BENEFITS_OPT_IN}}',
          type: 'checkbox',
          recipient_id: 'temp_1',
          required: false,
          ignore_if_not_present: true
        }
      ],
      recipients: [
        {
          id: 'temp_1',
          first_name: 'Sarah',
          last_name: 'Chen',
          email: 'sarah@example.com',
          designation: 'Signer',
          order: 1
        },
        {
          id: 'temp_2',
          first_name: 'Mike',
          last_name: 'Torres',
          email: 'mike@example.com',
          designation: 'Signer',
          order: 2
        }
      ]
    })
  }
);
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      workspace_id: workspaceId,
      document: documentBase64,
      name: 'Employment Agreement',
      anchor_tags: [
        {
          anchor_string: '{{EMPLOYEE_SIGNATURE}}',
          type: 'signature',
          recipient_id: 'temp_1',
          required: true,
          width: 30,
          height: 8,
          offset_y: 2
        },
        {
          anchor_string: '{{EMPLOYEE_DATE}}',
          type: 'date',
          recipient_id: 'temp_1',
          required: true
        },
        {
          anchor_string: '{{EMPLOYEE_INITIALS}}',
          type: 'initials',
          recipient_id: 'temp_1',
          required: true,
          match_all: true
        },
        {
          anchor_string: '{{MANAGER_SIGNATURE}}',
          type: 'signature',
          recipient_id: 'temp_2',
          required: true
        },
        {
          anchor_string: '{{BENEFITS_OPT_IN}}',
          type: 'checkbox',
          recipient_id: 'temp_1',
          required: false,
          ignore_if_not_present: true
        }
      ],
      recipients: [
        {
          id: 'temp_1',
          first_name: 'Sarah',
          last_name: 'Chen',
          email: 'sarah@example.com',
          designation: 'Signer',
          order: 1
        },
        {
          id: 'temp_2',
          first_name: 'Mike',
          last_name: 'Torres',
          email: 'mike@example.com',
          designation: 'Signer',
          order: 2
        }
      ]
    })
  }
);

Quelques points à noter dans cet exemple. La balise {{EMPLOYEE_INITIALS}} utilise match_all: true, donc si le PDF contient des marqueurs d'initiales sur les pages 1, 5 et 12, les trois reçoivent des champs. La case à cocher {{BENEFITS_OPT_IN}} utilise ignore_if_not_present: true car toutes les versions du contrat de travail n'incluent pas cette section. Et offset_y: 2 sur le champ de signature le déplace légèrement vers le bas par rapport à la position du texte d'ancrage.

Les dimensions (width et height) suivent le même système de coordonnées en pourcentage que celui utilisé par les champs positionnés manuellement. Les balises d'ancrage et les champs manuels fonctionnent ensemble, ce qui vous permet d'utiliser des ancres pour la majorité de vos champs tout en ajoutant des champs manuels basés sur des coordonnées dans la même requête pour les cas particuliers.

Migration depuis d'autres plateformes

Si vous migrez depuis un autre fournisseur de signature électronique qui utilise le placement de champs basé sur le texte, les concepts correspondent directement. La syntaxe de la chaîne d'ancrage et les noms de propriétés diffèrent, mais le mécanisme sous-jacent est le même : intégrer un marqueur, définir le type de champ, laisser l'API gérer le placement.

Depuis DocuSign Auto-Place : DocuSign utilise anchorString, anchorXOffset, anchorYOffset et des types spécifiques aux onglets comme signHereTabs. Dans Firma.dev, cela devient anchor_string, offset_x, offset_y et le champ universel type. Le anchorIgnoreIfNotPresent de DocuSign correspond à ignore_if_not_present. Le anchorCaseSensitive de DocuSign correspond à case_sensitive. La principale différence structurelle est que Firma.dev utilise un seul tableau anchor_tags avec une propriété type, plutôt que des tableaux distincts pour chaque type d'onglet.

Depuis les Smart Anchors de Yousign : Le concept de "smart anchors" de Yousign avec détection de type de champ se transpose directement. Les options de correspondance et de positionnement sont comparables, bien que les noms de propriétés utilisent la convention snake_case de Firma.dev.

La limite est de 100 balises d'ancrage par demande de signature, ce qui couvre largement la plupart des flux de travail documentaires. Si vous traitez des documents qui nécessitent réellement plus de 100 champs, envisagez de les répartir sur plusieurs demandes de signature ou d'utiliser une combinaison de balises d'ancrage et de définitions de champs basées sur des modèles.

Référence de l'API

Le tableau anchor_tags est disponible sur le point de terminaison de création de demandes de signature basées sur un document (POST /signing-requests). Chaque élément du tableau est un objet AnchorTag comportant environ 25 propriétés configurables.

Les propriétés clés :

anchor_string (obligatoire) est le marqueur de texte à rechercher dans le PDF. type (obligatoire) est le type de champ à créer. recipient_id attribue le champ à un destinataire spécifique en utilisant son identifiant ou identifiant temporaire. required indique si le champ est obligatoire ou facultatif. offset_x et offset_y ajustent la position du champ par rapport à l'emplacement de l'ancre. width et height définissent des dimensions de champ personnalisées. case_sensitive contrôle si la recherche respecte la casse. whole_word empêche les correspondances de chaînes partielles. occurrence cible une occurrence spécifique lorsque l'ancre apparaît plusieurs fois. match_all place des champs à chaque occurrence. ignore_if_not_present ignore la balise sans erreur si le texte d'ancrage n'est pas trouvé dans le document.

Pour obtenir le schéma complet avec toutes les propriétés et leurs types, consultez le journal des modifications de l'API pour la v1.11.0.

Prochaines étapes

Les balises d'ancrage s'associent parfaitement à la génération automatisée de documents. Si votre application génère des contrats, des accords de confidentialité (NDA) ou des documents d'intégration à partir de modèles, vous pouvez intégrer des chaînes d'ancrage lors de la génération et laisser Firma.dev gérer automatiquement le placement des champs à chaque demande.

Commencez à utiliser Firma.dev gratuitement, aucune carte bancaire requise.

  1. Titre

Image de fond

Prêt à ajouter des signatures électroniques à votre application ?

Commencez gratuitement. Aucune carte de crédit requise. Payez seulement 0,049 € par enveloppe lorsque vous serez prêt à lancer votre activité.

Image de fond

Prêt à ajouter des signatures électroniques à votre application ?

Commencez gratuitement. Aucune carte de crédit requise. Payez seulement 0,049 € par enveloppe lorsque vous serez prêt à lancer votre activité.

Image de fond

Prêt à ajouter des signatures électroniques à votre application ?

Commencez gratuitement. Aucune carte de crédit requise. Payez seulement 0,049 € par enveloppe lorsque vous serez prêt à lancer votre activité.