Balises d'Ancrage

Les balises d’ancrage vous permettent de positionner des champs sur un document en faisant correspondre du texte déjà présent dans le fichier, plutôt que de calculer des coordonnées x/y. Vous importez un PDF ou un DOCX contenant du texte marqueur — généralement écrit sous la forme {{SIGN_HERE}} ou similaire, bien que n’importe quelle chaîne littérale fonctionne — vous transmettez un tableau anchor_tags dans votre requête de création, et Firma recherche chaque chaîne dans le document et place un champ à chaque endroit où elle trouve une correspondance.

Les balises d’ancrage ne fonctionnent qu’avec la création basée sur un document — une requête qui inclut document (en base64) ou document_id. Elles n’ont aucun effet sur les requêtes basées sur template_id, car le pipeline d’ancrage recherche dans le document importé lui-même ; les champs d’un modèle sont déjà positionnés.

Fonctionnement de la correspondance

anchor_string est mis en correspondance comme du texte littéral (sous-chaîne), insensible à la casse par défaut, n’importe où dans le document — aucune syntaxe de délimiteur n’est requise. {{...}} n’est qu’une convention visuellement facile à repérer dans un document et peu susceptible d’entrer en collision avec du contenu réel ; "Sign Here:" ou "X_____" fonctionnent exactement de la même façon. Chaque balise d’ancrage prend en charge :

Propriété	Valeur par défaut	Effet
`case_sensitive`	`false`	Indique si la correspondance respecte la casse
`match_whole_word`	`true`	Exige des caractères non alphanumériques des deux côtés de la correspondance
`occurrence`	`0`	`0` place un champ à chaque correspondance ; `1`, `2`, etc. placent un champ uniquement à cette occurrence précise (indexée à partir de 1)
`ignore_if_not_present`	`false`	Si la chaîne n’est pas trouvée : `true` l’ignore silencieusement, `false` fait échouer toute la requête
`x_offset` / `y_offset`	`0`	Décale le champ placé par rapport au texte trouvé
`offset_units`	`percent`	`percent` des dimensions de la page, ou `pixels` (points PDF, 72 DPI)

Si le document ne contient aucun texte extractible — un PDF scanné ou basé sur une image, par exemple — aucune balise d’ancrage ne peut correspondre. Définissez ignore_if_not_present: true si vous voulez que la requête continue malgré tout (le champ n’est alors simplement jamais placé) ; sinon la requête échoue à la validation.

Tailles de champ par défaut

Si vous ne transmettez pas width/height sur une balise d’ancrage, le champ est dimensionné selon le type (en pourcentage de la page) :

Type	Largeur	Hauteur
`signature`	25%	5%
`initial` / `initials`	10%	5%
`date`	20%	3%
`text` / `textarea` / `text_area` / `dropdown` / `url`	20%	3%
`checkbox` / `radio` / `radio_buttons`	3%	3%

stamp, file, approval_signature, approval_checkmark et approval_date sont tous acceptés par le serveur comme valeurs de type d’ancrage, mais aucun des cinq n’a d’entrée dédiée dans ce tableau — ils reviennent tous silencieusement à la valeur par défaut de text (20% × 3%). C’est généralement trop petit pour un tampon, une zone de dépôt de fichier ou une signature d’approbation. Transmettez toujours width/height de façon explicite lorsque vous ancrez l’un de ces types.

Masquer le texte d’ancrage

Deux options indépendantes et combinables contrôlent ce qui arrive au texte marqueur et à la zone qui l’entoure une fois qu’un champ est placé :

Option	Valeur par défaut	Ce qu’elle fait réellement
`remove_anchor_text`	`true`	Passe les glyphes de la chaîne d’ancrage en mode de rendu de texte PDF invisible, sur place. Les caractères restent dans le flux de contenu (donc le texte environnant ne se réorganise pas) mais rien n’est peint pour eux.
`add_white_background`	`false`	Dessine un rectangle blanc opaque sur toute la boîte englobante du champ, recouvrant tout contenu du document en dessous — pas seulement la chaîne d’ancrage.

La référence publique de l’API décrit actuellement remove_anchor_text comme « dessinant un rectangle blanc par-dessus » le texte d’ancrage. Cette description est obsolète — elle correspond à une implémentation antérieure. Le comportement actuel est le rendu de texte invisible (ci-dessus), qui laisse les glyphes en place plutôt que de peindre par-dessus. Dessiner un rectangle est ce que fait add_white_background, et cela agit sur toute la boîte du champ, pas spécifiquement sur la chaîne d’ancrage.

Comme remove_anchor_text ne change que la façon dont le texte est peint, elle ne supprime jamais la chaîne de la couche de texte du document :

Un document traité avec remove_anchor_text: true (la valeur par défaut) donne l’impression que le texte d’ancrage a disparu dans n’importe quel lecteur PDF — mais exécuter une extraction de texte (pdftotext, la méthode extractText d’une bibliothèque PDF, etc.) sur le même fichier renvoie toujours la chaîne d’ancrage littérale. Cela s’applique aussi au document final signé, pas seulement à la version antérieure à la signature. Si vous voyez un signalement du support indiquant que le texte d’ancrage est « toujours là » après traitement, c’est presque toujours l’explication : le texte est invisible, pas supprimé, et la signature elle-même est une couche d’image distincte placée aux coordonnées de l’ancrage.

Si vous avez besoin que la zone derrière un champ soit visuellement effacée (par exemple pour recouvrir un cadre imprimé de type espace réservé, pas seulement le texte marqueur qu’il contient), combinez les deux options — remove_anchor_text masque les glyphes du marqueur, add_white_background recouvre toute l’empreinte du champ.

Documents DOCX

Il n’existe pas de logique de correspondance d’ancrage spécifique au DOCX. Un fichier DOCX importé est d’abord entièrement converti en PDF, puis exactement le même pipeline de recherche de texte décrit ci-dessus s’exécute sur le PDF obtenu :

Les premiers octets du fichier importé sont analysés pour détecter s’il s’agit d’un DOCX (un fichier au format ZIP) ou d’un PDF.
Un DOCX est converti via mammoth (DOCX → HTML) puis remis en page depuis zéro sur une page A4 fixe, avec des marges fixes et un tableau de tailles de police fixe — ce n’est pas une rastérisation de la pagination Word d’origine.
La correspondance d’ancrage s’exécute sur ce PDF fraîchement généré.

Comme la conversion DOCX→PDF remet en page le contenu plutôt que de préserver la mise en page originale de Word, la position d’une ancre après conversion dépend de l’endroit où le moteur de rendu du convertisseur place ce texte — et non de l’endroit où il apparaissait dans le document Word d’origine. Les sauts de page et les retours à la ligne peuvent se déplacer. Les images intégrées dans le DOCX sont entièrement supprimées lors de la conversion — l’étape d’analyse HTML ne gère que les titres, paragraphes, listes et tableaux, sans prise en charge des images. Si une ancre se trouve près d’une image dans votre DOCX source, attendez-vous à ce que l’image soit absente du document de signature, et pas seulement repositionnée.

Les types de champ pris en charge sont identiques à ceux des ancres PDF — au moment où la correspondance d’ancrage s’exécute, le fichier est déjà un PDF, il n’y a donc aucune restriction spécifique au DOCX sur les valeurs de type que vous pouvez utiliser.

Documents PDF

Pour un PDF natif importé, la correspondance d’ancrage s’exécute directement sur le document : le texte positionné est extrait page par page, les fragments de texte adjacents sur la même ligne sont fusionnés (ainsi une chaîne d’ancrage divisée entre différents opérateurs d’affichage de texte PDF par le producteur PDF d’origine est tout de même trouvée comme une seule correspondance), et chaque correspondance est convertie des points PDF en une position en pourcentage relative à la page pour le nouveau champ.

La position de la correspondance est approximée proportionnellement à partir de l’index de caractère au sein d’un bloc de texte, et non à partir du crénage exact par glyphe. Sur des polices proportionnelles (non monospace), un champ placé peut être très légèrement décentré par rapport au texte d’ancrage exact. Cela est rarement visible aux tailles de champ normales, mais utile à savoir si vous avez besoin d’une précision de positionnement au sous-pixel.

PDF et DOCX en un coup d’œil

	PDF	DOCX
Mise en page d’origine conservée	Oui — la correspondance s’exécute sur le fichier importé exact	Non — le fichier est remis en page sur une mise en page A4 fixe avant l’exécution de la correspondance
Images	Non affectées par le traitement d’ancrage	Supprimées lors de la conversion DOCX→PDF
Pipeline de correspondance	S’exécute directement	S’exécute sur le PDF converti (logique identique)

Exemple complet

Cette requête crée et envoie un document avec trois champs placés par ancrage : une signature, une date par défaut au jour de la signature, et un champ de texte en lecture seule reprenant une valeur fixe.

curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ],
    "anchor_tags": [
      {
        "anchor_string": "{{SIGN_HERE}}",
        "type": "signature",
        "recipient_id": "temp_1"
      },
      {
        "anchor_string": "{{DATE}}",
        "type": "date",
        "recipient_id": "temp_1",
        "date_signing_default": true
      },
      {
        "anchor_string": "{{CONTRACT_REF}}",
        "type": "text",
        "recipient_id": "temp_1",
        "read_only": true,
        "read_only_value": "Contract #12345"
      }
    ]
  }'

const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Employment Contract',
      document_id: 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer'
        }
      ],
      anchor_tags: [
        {
          anchor_string: '{{SIGN_HERE}}',
          type: 'signature',
          recipient_id: 'temp_1'
        },
        {
          anchor_string: '{{DATE}}',
          type: 'date',
          recipient_id: 'temp_1',
          date_signing_default: true
        },
        {
          anchor_string: '{{CONTRACT_REF}}',
          type: 'text',
          recipient_id: 'temp_1',
          read_only: true,
          read_only_value: 'Contract #12345'
        }
      ]
    })
  }
)

const result = await response.json()

import os
import requests

response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Employment Contract',
        'document_id': 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer'
            }
        ],
        'anchor_tags': [
            {
                'anchor_string': '{{SIGN_HERE}}',
                'type': 'signature',
                'recipient_id': 'temp_1'
            },
            {
                'anchor_string': '{{DATE}}',
                'type': 'date',
                'recipient_id': 'temp_1',
                'date_signing_default': True
            },
            {
                'anchor_string': '{{CONTRACT_REF}}',
                'type': 'text',
                'recipient_id': 'temp_1',
                'read_only': True,
                'read_only_value': 'Contract #12345'
            }
        ]
    }
)

result = response.json()

recipient_id utilise ici un id temporaire (temp_1) car le destinataire est défini dans la même requête (création basée sur un document). Les champs résolus à partir des balises d’ancrage sont fusionnés avec tout fields spécifié manuellement dans la même requête, et une fois créés, ce sont des lignes de champ ordinaires — la réponse ne distingue pas un champ placé par ancrage d’un champ positionné manuellement, et n’expose pas quelle chaîne d’ancrage ou quelle occurrence l’a produit.

Pièges à connaître

Le texte d’ancrage supprimé est masqué, pas effacé — prévoyez qu’il apparaisse dans une extraction

Comme indiqué ci-dessus, remove_anchor_text ne supprime jamais de caractères du PDF ; elle les empêche seulement d’être peints. Si vos propres exigences de conformité ou de rédaction impliquent qu’une chaîne marqueur ne puisse jamais apparaître dans une extraction de texte programmatique du document final signé, les balises d’ancrage telles qu’elles sont implémentées aujourd’hui ne peuvent pas satisfaire cela — choisissez des chaînes d’ancrage que vous acceptez de voir présentes de façon permanente (de manière invisible) dans le fichier, ou ne comptez pas sur cette API pour les effacer.

Retraiter un document déjà ancré fait à nouveau correspondre les mêmes ancres

Comme le texte d’ancrage n’est que visuellement masqué, un document déjà passé par le traitement des balises d’ancrage correspond toujours aux mêmes valeurs d’anchor_string si vous le repassez (ou une copie de celui-ci) dans une nouvelle requête de création avec les mêmes anchor_tags. Le texte invisible est indiscernable du texte visible pour l’étape de correspondance. Exécutez toujours les balises d’ancrage sur votre document source original, non traité — pas sur un document que vous avez déjà généré à partir d’une requête d’ancrage précédente.

Le style de police des balises d’ancrage ne persiste généralement pas

Une balise d’ancrage accepte font_family, font_size, font_color et text_align. Seul font_size atteint réellement le champ créé — il est fusionné dans format_rules.fontSize (limité entre 8 et 48). font_family, font_color et text_align sont résolus en interne mais abandonnés avant l’enregistrement du champ, donc les définir sur une balise d’ancrage n’a aucun effet visible.

Les types d’ancrage `stamp`, `file` et `approval_*` nécessitent un dimensionnement explicite

stamp, file, approval_signature, approval_checkmark et approval_date passent tous la validation côté serveur comme valeurs de type d’ancrage, mais aucun n’a d’entrée dédiée de dimensions par défaut, donc les cinq héritent silencieusement de la valeur par défaut de text (20% × 3%). Transmettez explicitement width et height pour ces types.

Prochaines étapes

Envoi d’une demande de signature pour le flux complet de création des destinataires et des champs
Préremplissage des champs — le comportement read_only/read_only_value/format_rules.prefilledData que suivent aussi les champs placés par ancrage une fois créés
Webhooks — abonnez-vous à signing_request.field.filled pour réagir au fur et à mesure que les champs placés par ancrage sont complétés

Guides de Démarrage

Guides avancés

Balises d'Ancrage

Fonctionnement de la correspondance

Tailles de champ par défaut

Masquer le texte d’ancrage

Documents DOCX

Documents PDF

PDF et DOCX en un coup d’œil

Exemple complet

Pièges à connaître

Le texte d’ancrage supprimé est masqué, pas effacé — prévoyez qu’il apparaisse dans une extraction

Retraiter un document déjà ancré fait à nouveau correspondre les mêmes ancres

Le style de police des balises d’ancrage ne persiste généralement pas

Les types d’ancrage `stamp`, `file` et `approval_*` nécessitent un dimensionnement explicite

Prochaines étapes

​Fonctionnement de la correspondance

​Tailles de champ par défaut

​Masquer le texte d’ancrage

​Documents DOCX

​Documents PDF

​PDF et DOCX en un coup d’œil

​Exemple complet

​Pièges à connaître

​Le texte d’ancrage supprimé est masqué, pas effacé — prévoyez qu’il apparaisse dans une extraction

​Retraiter un document déjà ancré fait à nouveau correspondre les mêmes ancres

​Le style de police des balises d’ancrage ne persiste généralement pas

​Les types d’ancrage stamp, file et approval_* nécessitent un dimensionnement explicite

​Prochaines étapes

Fonctionnement de la correspondance

Tailles de champ par défaut

Masquer le texte d’ancrage

Documents DOCX

Documents PDF

PDF et DOCX en un coup d’œil

Exemple complet

Pièges à connaître

Le texte d’ancrage supprimé est masqué, pas effacé — prévoyez qu’il apparaisse dans une extraction

Retraiter un document déjà ancré fait à nouveau correspondre les mêmes ancres

Le style de police des balises d’ancrage ne persiste généralement pas

Les types d’ancrage `stamp`, `file` et `approval_*` nécessitent un dimensionnement explicite

Prochaines étapes