Zones de signature

Placer dans un PDF les zones qu'un signataire doit remplir : signature, initiales, date, champs de texte, cases à cocher, listes. Les zones s'utilisent avec la signature numérique.

Prérequis

Le flux de signature numérique : voir Signature numérique. Cette page détaille l'étape 2, le placement des zones.

Coordonnées

Point	Règle
Unité	Le point PDF (1/72 de pouce). Une page Letter mesure 612 x 792 points.
Origine	Le coin supérieur gauche de la page ; y augmente vers le bas.
Position d'une zone	`x` et `y` désignent le coin supérieur gauche de la zone.
Dimensions de la page	`GetPageDimensions` donne la largeur et la hauteur d'une page, telle qu'elle s'affiche : une page pivotée de 90° a sa largeur et sa hauteur inversées.
Débordement	Rien ne vérifie qu'une zone reste dans la page : contrôlez `x + largeur` et `y + hauteur` vous-même.

Exemple

SignZoneDetails[] zones;
using (var zoneBuilder = new ZoneBuilder(pdf, isPki: true))   // octets du PDF, ou son chemin
{
    var page = zoneBuilder.GetPageDimensions(1);
    float y = page.Height - 150;   // à 150 points du bas de la page

    zones = new[]
    {
        zoneBuilder.CreateFieldTextZone(page: 1, fieldName: "nom", x: 60, y: y - 40, width: 200, height: 20),
        zoneBuilder.CreateFieldSignZone(page: 1, fieldName: "signature", x: 60, y: y, width: 200, height: 50),
        zoneBuilder.CreateFieldDateSignZone(page: 1, fieldName: "date", x: 300, y: y + 15, width: 100, height: 20),
        zoneBuilder.CreateFieldCheckBoxZone(page: 1, fieldName: "accepte", x: 60, y: y + 70, required: true),
    };
}

with ZoneBuilder(chemin_pdf, is_pki=True) as zone_builder:
    largeur, hauteur = zone_builder.get_page_dimensions(1)
    y = hauteur - 150  # à 150 points du bas de la page

    zones = [
        zone_builder.create_field_text_zone(page=1, field_name="nom", x=60, y=y - 40, width=200, height=20),
        zone_builder.create_field_sign_zone(page=1, field_name="signature", x=60, y=y, width=200, height=50),
        zone_builder.create_field_date_sign_zone(page=1, field_name="date", x=300, y=y + 15, width=100, height=20),
        zone_builder.create_field_checkbox_zone(page=1, field_name="accepte", x=60, y=y + 70, required=True),
    ]

$zoneBuilder = new ZoneBuilder($cheminPdf, isPki: true);
try {
    [$largeur, $hauteur] = $zoneBuilder->getPageDimensions(1);
    $y = $hauteur - 150;   // à 150 points du bas de la page

    $zones = [
        $zoneBuilder->createFieldTextZone(page: 1, fieldName: 'nom', x: 60, y: $y - 40, width: 200, height: 20),
        $zoneBuilder->createFieldSignZone(page: 1, fieldName: 'signature', x: 60, y: $y, width: 200, height: 50),
        $zoneBuilder->createFieldDateSignZone(page: 1, fieldName: 'date', x: 300, y: $y + 15, width: 100, height: 20),
        $zoneBuilder->createFieldCheckBoxZone(page: 1, fieldName: 'accepte', x: 60, y: $y + 70, required: true),
    ];
} finally {
    $zoneBuilder->close();
}

Libérez toujours le ZoneBuilder après usage (using, with, close) : il garde le PDF ouvert.

Créer le ZoneBuilder

Élément	.NET	Python	PHP
Source du PDF	Ses octets ou son chemin	Ses octets ou son chemin	Son chemin, ou ses octets avec `ZoneBuilder::fromBytes`
Mode PKI	`isPki`, true par défaut	`is_pki`, true par défaut	`isPki`, true par défaut
Nombre de pages	Propriété `PageCount`	Propriété `page_count`	Méthode `getPageCount()`
Mode choisi	Propriété `IsPki`, en lecture seule	Attribut `is_pki`	Non exposé

Le mode PKI ne fait qu'autoriser trois types de zones : le texte multiligne, la liste d'options et la liste déroulante. Il ne change rien aux autres zones. Il est actif par défaut : avec la signature numérique, laissez-le à true.

Types de zones

Toutes les méthodes prennent page (à partir de 1), fieldName, x et y. Toutes, sauf la case à cocher et le bouton radio, prennent aussi la largeur et la hauteur. La taille de police (fontSize) est en points, 12 par défaut.

Zone	Méthode	Paramètres propres (défaut)	Points à retenir
Signature	`CreateFieldSignZone`	Aucun	Toujours obligatoire.
Initiales	`CreateFieldInitialZone`	Aucun	Toujours obligatoire.
Date de signature	`CreateFieldDateSignZone`	`fontSize` (12)	Remplie automatiquement au moment de la signature. Toujours obligatoire.
Texte	`CreateFieldTextZone`	`defaultValue` (vide), `fontSize` (12), `required` (true)
Nombre	`CreateFieldNumberZone`	`defaultValue` (0 ; obligatoire en .NET), `fontSize` (12), `required` (true)
Date	`CreateFieldDateZone`	`fontSize` (12), `required` (true)	Sélecteur de date.
Case à cocher	`CreateFieldCheckBoxZone`	`isChecked` (false), `required` (false), `requiredFocus` (false)	Taille fixe (10 x 10). Une case obligatoire est toujours présentée décochée : `isChecked` est alors ignoré. Avec `requiredFocus`, le signataire doit passer par la case avant de compléter la signature ; `required` l'active aussi.
Bouton radio	`CreateFieldRadioZone`	`groupId` (obligatoire), `isSelected` (false)	Taille fixe (10 x 10). Le nom du champ est la valeur de l'option ; les boutons d'un même groupe partagent le même `groupId`. Rien n'empêche de sélectionner plusieurs boutons d'un groupe : n'en sélectionnez qu'un.
Texte multiligne	`CreateFieldTextAreaZone`	`defaultValue` (vide), `fontSize` (12), `required` (false)	Mode PKI seulement.
Liste d'options	`CreateFieldOptionListZone`	`options` (obligatoire), `selectedValues` (aucune), `multiSelect` (false), `required` (false)	Mode PKI seulement. Sans `multiSelect`, une seule valeur peut être choisie d'avance. Pas de taille de police.
Liste déroulante	`CreateFieldDropdownZone`	`options` (obligatoire), `selectedValue` (aucune), `fontSize` (12), `required` (false)	Mode PKI seulement.

Aucun SDK ne vérifie la taille ni la position d'une zone, sa taille de police, ni que les valeurs choisies d'avance figurent dans options.

Note

Valeur par défaut. Pour le texte, le texte multiligne et le nombre, la valeur par défaut est une valeur déjà remplie, que le signataire voit et peut modifier ; ce n'est pas un texte indicatif. Elle voyage avec la définition de la zone : n'y mettez que ce que le signataire doit voir.

En .NET, le champ nombre exige une valeur par défaut (defaultValue). En Python et en PHP, elle vaut 0.

Associer les zones aux signataires

Chaque signataire reçoit sa définition : son adresse, et pour le fichier (désigné par son empreinte SHA-512), ses zones en mode define. Voir l'étape 3 de l'exemple complet.

Plusieurs signataires : une définition par signataire, chacune avec ses propres zones.
Un fichier par signataire : une définition ne peut viser qu'un seul fichier.

Champs déjà présents dans le PDF

Avec DetectExistingFields (true par défaut), la certification détecte les champs déjà présents dans le PDF :

Cas	Comportement
Un seul signataire	Tous les champs détectés lui sont attribués.
Plusieurs signataires	Vous devez fournir `DefineRecipients`, qui répartit les champs détectés entre les signataires ; sinon la certification échoue.
Plusieurs signataires, zones placées avec `ZoneBuilder` seulement	Passez `DetectExistingFields` à false.

// Reçoit les signataires (chacun avec une liste vide) et les champs détectés ; retourne la répartition.
DefineRecipients = (zonesParSignataire, champsDetectes) =>
{
    var signataires = zonesParSignataire.Keys.ToList();
    foreach (var champ in champsDetectes)
    {
        if (champ.FieldName.StartsWith("client_")) zonesParSignataire[signataires[0]].Add(champ);
        else if (champ.FieldName.StartsWith("conseiller_")) zonesParSignataire[signataires[1]].Add(champ);
        else throw new InvalidOperationException("Champ hors convention dans le PDF");   // jamais d'attribution par défaut
    }
    return zonesParSignataire;
}

Le délégué reçoit un dictionnaire {adresse: []} et la liste des champs détectés, sous forme de dictionnaires bruts (clés "Type", "Page", "DefaultValue"...) : le nom du champ se trouve dans DefaultValue. Il retourne le dictionnaire rempli.

import json

# Reçoit les signataires (chacun avec une liste vide) et les champs détectés ; retourne la répartition.
def repartir(zones_par_signataire, champs_detectes):
    signataires = list(zones_par_signataire)
    for champ in champs_detectes:
        nom = json.loads(champ.get("DefaultValue") or "{}").get("existingFieldInfos", {}).get("fieldName", "")
        if nom.startswith("client_"):
            zones_par_signataire[signataires[0]].append(champ)
        elif nom.startswith("conseiller_"):
            zones_par_signataire[signataires[1]].append(champ)
        else:
            raise ValueError("Champ hors convention dans le PDF")  # jamais d'attribution par défaut
    return zones_par_signataire

# CertifyPdfArgs(..., define_recipients=repartir)

Le délégué reçoit un tableau [adresse => []] et les champs détectés (ZoneDetails) ; il doit retourner le tableau rempli, car les tableaux PHP sont passés par valeur. Le nom du champ est dans fieldName.

// Reçoit les signataires (chacun avec une liste vide) et les champs détectés ; retourne la répartition.
$repartir = static function (array $zonesParSignataire, array $champsDetectes): array {
    $signataires = array_keys($zonesParSignataire);
    foreach ($champsDetectes as $champ) {   // ZoneDetails
        if (str_starts_with($champ->fieldName, 'client_')) {
            $zonesParSignataire[$signataires[0]][] = $champ;
        } elseif (str_starts_with($champ->fieldName, 'conseiller_')) {
            $zonesParSignataire[$signataires[1]][] = $champ;
        } else {
            throw new RuntimeException('Champ hors convention dans le PDF');   // jamais d'attribution par défaut
        }
    }
    return $zonesParSignataire;
};

// new CertifyPdfArgs(..., defineRecipients: $repartir)

Les champs détectés que vous n'attribuez à aucun signataire sont passés en lecture seule avant la certification : personne ne peut les remplir, et ils gardent le contenu du PDF d'origine.

Erreurs fréquentes

Symptôme	Cause probable	Solution
Erreur « page hors limites »	Numéro de page inférieur à 1 ou supérieur au nombre de pages	Les pages commencent à 1.
Erreur à la création d'un texte multiligne, d'une liste d'options ou d'une liste déroulante	`ZoneBuilder` créé sans le mode PKI	Créez-le avec le mode PKI.
La certification échoue avec plusieurs signataires	Champs détectés sans `DefineRecipients`	Fournissez `DefineRecipients`, ou passez `DetectExistingFields` à false.
« File does not contain existing fields »	`DefineRecipients` fourni pour un PDF sans champ	Passez `DetectExistingFields` à false.
Une zone apparaît au mauvais endroit	Origine prise en bas de page	L'origine est le coin supérieur gauche ; voir Coordonnées.

Et ensuite

Signature numérique
Journaux : suivre la signature

Table of Contents