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

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

Les balises d'ancrage résolvent cela. 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 types de champs corrects à ces emplacements. Les marqueurs sont supprimés du document final, donc les signataires ne les voient jamais. Un appel API, pas de calcul de coordonnées.

Les balises d'ancrage ont été livrées dans 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

La façon la plus rapide de faire fonctionner 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}} quelque part dans votre PDF où vous souhaitez que le champ de signature apparaisse. Vous pouvez faire cela dans n'importe quel outil qui génère vos documents, que ce soit un modèle Word, une bibliothèque PDF ou un service de génération de documents.

Étape 2 : Créez une demande de signature basée sur le 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 scanne le PDF pour {{SIGN_HERE}}, place un champ de signature à cet emplacement, l'assigne au destinataire, et retire le texte du marqueur du document. C'est tout.

Notez que les balises d'ancrage ne fonctionnent qu'avec la création de demande de signature basée sur le document, pas sur le modèle. 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 supportent 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 d'initiales, text pour l'entrée de texte à une ligne, textarea pour l'entrée de texte multi-lignes, date pour les champs de date, checkbox pour les cases à cocher, radio pour les groupes de boutons radio, dropdown pour les sélections 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 rend le widget 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 de sélection, et ainsi de suite.

Options de correspondance et de positionnement

Le comportement de correspondance par défaut fonctionne pour 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 à true ou false (défaut à false). Avec la correspondance insensible à la casse, {{sign_here}} et {{SIGN_HERE}} correspondent tous deux.

Correspondance de mot entier : Réglez whole_word à true pour éviter les correspondances partielles. Si votre chaîne d'ancrage est SIGN et whole_word est false, elle correspondra également à SIGNATURE ou COSIGN. En la mettant à true, elle correspondra uniquement au mot exact.

Ciblage d'occurrences spécifiques : Si votre PDF contient plusieurs fois la même chaîne d'ancrage, vous pouvez cibler des occurrences spécifiques avec occurrence. Réglez sur 1 pour la première correspondance, 2 pour la deuxième, et ainsi de suite. Omettez-le ou réglez match_all sur true pour placer les champs à chaque occurrence.

Positionnement par décalage : Affinez l'endroit où le champ se situe par rapport au texte d'ancrage à l'aide de offset_x et offset_y. Vous pouvez spécifier les décalages en pourcentages (par rapport aux dimensions de la page) ou en pixels. Cela est utile lorsque vous souhaitez que le champ soit un peu en dessous ou à droite du marqueur, plutôt que directement dessus.

Gestion élégante des ancrages manquants : Réglez ignore_if_not_present à true si la chaîne d'ancrage pourrait ne pas exister dans chaque document. Sans cela, un ancrage manquant renvoie une erreur. Avec lui activé, Firma.dev ignore silencieusement cette balise 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 remarques sur cet exemple. La balise {{EMPLOYEE_INITIALS}} utilise match_all: true, donc si le PDF a des marqueurs d'initiales aux pages 1, 5 et 12, les trois auront des champs. La case à cocher {{BENEFITS_OPT_IN}} utilise ignore_if_not_present: true car chaque version de l'accord d'emploi n'inclut pas cette section. Et l'offset_y: 2 sur le champ de signature le décale 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 basé sur les pourcentages utilisé par les champs positionnés manuellement. Les balises d'ancrage et les champs manuels fonctionnent ensemble, vous pouvez donc utiliser des ancrages pour la majorité de vos champs et ajouter encore des champs basés sur des coordonnées manuelles dans la même demande pour des cas particuliers.

Migration à partir d'autres plateformes

Si vous migrez d'un autre fournisseur de signatures électroniques qui utilise le placement de champ basé sur du texte, les concepts se traduisent directement. La syntaxe de chaîne d'ancrage et les noms de propriétés diffèrent, mais le mécanisme sous-jacent est le même : incorporez un marqueur, définissez le type de champ, laissez 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. La propriété anchorIgnoreIfNotPresent de DocuSign se mappe sur ignore_if_not_present. La propriété anchorCaseSensitive de DocuSign se mappe sur 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 séparés pour chaque type d'onglet.

Depuis Yousign Smart Anchors : Le concept d'"ancrages intelligents" de Yousign avec la détection des types de champs se traduit directement. Les options de correspondance et de positionnement sont comparables, bien que les noms de propriétés utilisent la convention du snake_case de Firma.dev.

La limite est de 100 balises d'ancrage par demande de signature, ce qui couvre confortablement la plupart des flux de travail de documents. Si vous traitez des documents qui nécessitent réellement plus de 100 champs, envisagez de les diviser entre 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 demande de signature basée sur le document (POST /signing-requests). Chaque élément du tableau est un objet AnchorTag avec environ 25 propriétés configurables.

Les propriétés clés :

anchor_string (requise) est le marqueur de texte à rechercher dans le PDF. type (requis) est le type de champ à créer. recipient_id assigne le champ à un destinataire spécifique en utilisant son ID ou un ID temporaire. required marque le champ comme obligatoire ou facultatif. offset_x et offset_y ajustent la position du champ par rapport à l'emplacement d'ancrage. width et height définissent des dimensions de champ personnalisées. case_sensitive contrôle si la correspondance est sensible à la casse. whole_word empêche les correspondances partielles de chaînes. occurrence cible une instance spécifique lorsque l'ancrage 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 le schéma complet avec toutes les propriétés et leurs types, voir le journal des modifications de l'API pour la version v1.11.0.

Prochaines étapes

Les balises d'ancrage s'associent bien avec la génération programmatique de document. Si votre application génère des contrats, des NDA, ou des documents d'intégration à partir de modèles, vous pouvez intégrer des chaînes d'ancrage pendant la génération et laisser Firma.dev gérer automatiquement le placement des champs à chaque demande.

Commencez avec Firma.dev gratuitement, sans carte de crédit requise.