Positionner les champs¶

Introduction¶

Les champs positionnent les zones de signature, les libellés texte, les paraphes et les dates sur les pages de vos documents PDF. Toutes les positions utilisent des coordonnées en ratios, des nombres décimaux compris entre 0.0 et 1.0, relatives aux dimensions de la page. Il n'y a aucune valeur en pixels.

Ce guide explique comment choisir la bonne stratégie de positionnement, utiliser l'outil Fields Helper, et intégrer des champs cachés dans vos PDF pour un positionnement automatique. Pour les spécifications des systèmes de coordonnées et les tableaux de paramètres, consultez la référence Systèmes de coordonnées.

Choisir une stratégie de positionnement¶

Le diagramme suivant vous aide à choisir la stratégie de positionnement la plus adaptée à votre cas d'usage :

flowchart TD
    A["Positionnement des champs"] --> B{"Contrôlez-vous la\ngénération du PDF ?"}
    B -- Non --> D{"Le PDF suit-il toujours\nla même structure ?"}
    B -- Oui ---> C["Intégrer des champs cachés dans le PDF"]
    D -- Non --> F["Calculer les coordonnées"]
    D -- Oui --> E["Extraire les coordonnées\navec le Fields Helper"]
    F -. "voir" .-> I["Réf. Systèmes de coordonnées"]
    E -. "voir" .-> H["§ API Fields Helper"]
    C -. "voir" .-> G["§ Positionnement par champs cachés"]

• Champs cachés (CS-ACP-GD) : vous générez le PDF et pouvez y intégrer des champs cachés. VoidSign détecte automatiquement la position : pas besoin de coordonnées fixes ni de recalcul.
• Fields Helper : vous recevez des PDF à structure fixe (même mise en page, même nombre de pages). Extrayez les coordonnées une fois et réutilisez-les.
• Calcul des coordonnées : les documents ont une mise en page variable et non contrôllables. Calculez les coordonnées dans votre code en utilisant les systèmes de coordonnées.

API Fields Helper¶

L'outil API Fields Helper vous permet de placer visuellement des champs sur votre PDF et d'exporter la configuration JSON. Inutile de calculer les coordonnées à la main. Ouvrez l'outil depuis le tableau de bord API sous l'onglet « Outils ».

Quand les coordonnées peuvent être réutilisées telles quelles¶

Le même modèle PDF est toujours utilisé (mise en page identique, même nombre de pages, même structure).

Quand les coordonnées doivent être recalculées¶

• Le nombre de pages change (contenu ajouté ou supprimé)
• Le contenu se déplace entre les pages (un tableau a grandi, un paragraphe a été ajouté)
• Un modèle de document entièrement différent est utilisé

Stratégies pour les documents dynamiques¶

• Réextraire : téléversez chaque variante de document dans l'API Fields Helper et extrayez de nouvelles coordonnées, pratique pour un petit nombre de variantes de modèles
• Calculer les coordonnées : si les documents sont générés dynamiquement avec des mises en page variables, calculez les coordonnées dans votre propre code en utilisant les systèmes de coordonnées décrits dans la référence
• Hybride : utilisez le Fields Helper pour déterminer les coordonnées des « zones stables » (par exemple un en-tête ou un pied de page fixe), et il est possible de déduire les coordonnées manquantes en se basant sur des parties stables et en comprenant le système de coordonnées
• Champs cachés : si vous contrôlez la génération du PDF, intégrez des champs cachés VS_ANCH_* et utilisez le système CS-ACP-GD pour un positionnement automatique indépendant de la mise en page

Positionnement par champs cachés (CS-ACP-GD)¶

Principe¶

Le système de coordonnées CS-ACP-GD (Anchor Center Point + Given Dimensions) permet de positionner des champs de signature en référençant des marqueurs texte cachés intégrés dans le PDF. Lors de la création d'une demande de signature, VoidSign détecte automatiquement la position et la page de chaque champ caché : vous ne fournissez que les dimensions de la zone de signature.

Cette approche est idéale lorsque vous contrôlez la génération du PDF : les champs cachés suivent le contenu quelle que soit la mise en page, éliminant le besoin de recalculer les coordonnées.

Intégrer des champs cachés dans un PDF¶

Un champ caché est un texte invisible préfixé par VS_ANCH_, intégré dans le PDF lors de sa génération. La technique consiste à rendre du texte blanc sur fond blanc (ou de taille très réduite) à l'emplacement souhaité de la zone de signature. Le texte doit être écrit directement dans le flux de contenu de la page, avec une police à encodage mono-octet (par exemple Helvetica, Times, Courier).

Définition du champ avec CS-ACP-GD¶

{
  "type": "signature",
  "box_coordinate_system": "CS-ACP-GD",
  "box_center_anchor_tag": "VS_ANCH_SIGNATURE_CLIENT",
  "box_width_ratio": 0.3,
  "box_height_ratio": 0.1,
  "signer_ref": 1
}

Fiabilité et limites¶

La détection des champs cachés repose sur l'analyse du flux de contenu PDF. Consultez Limites : Champs cachés PDF pour les conditions de fiabilité et les scénarios non pris en charge.

Exemple complet : Requête multi-champs¶

Cette requête combine les quatre types de champs sur un seul document avec un signataire :

curl -X POST \
  "https://api.voidsign.com/api/v1/requests" \
  -H "X-VoidSign-Key: vs_live_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "auth_method": "mail",
    "invitation_mode": "voidsign_mail",
    "locales": ["fr-FR"],
    "description": "Multi-field example",
    "documents": [
      {
        "base64": "<BASE64_CONTENT>",
        "fields": [
          {
            "type": "signature",
            "box_coordinate_system": "CS-ULP-GD",
            "box_x_ratio": 0.15,
            "box_y_ratio": 0.7,
            "box_width_ratio": 0.3,
            "box_height_ratio": 0.1,
            "page_number": 0,
            "signer_ref": 1
          },
          {
            "type": "text",
            "box_coordinate_system": "CS-CP-AD",
            "box_center_x_ratio": 0.5,
            "box_center_y_ratio": 0.05,
            "page_number": 0,
            "text": "Contrat de prestation N°2024-001",
            "font_size": 12.0
          },
          {
            "type": "paraph",
            "box_coordinate_system": "CS-CP-AD",
            "box_center_x_ratio": 0.9,
            "box_center_y_ratio": 0.95,
            "page_number": "all",
            "signer_ref": 1,
            "font_size": 10.0
          },
          {
            "type": "date",
            "box_coordinate_system": "CS-CP-AD",
            "box_center_x_ratio": 0.5,
            "box_center_y_ratio": 0.92,
            "page_number": 0,
            "font_size": 10.0
          }
        ]
      }
    ],
    "signers": [
      {
        "ref": 1,
        "email": "jean.dupont@example.com",
        "first_name": "Jean",
        "last_name": "Dupont",
        "reminder_days": [3, 7]
      }
    ]
  }'

Exemple : Requête avec champ caché¶

Cette requête utilise le système CS-ACP-GD pour positionner la signature à l'emplacement d'un champ caché intégré dans le PDF :

curl -X POST \
  "https://api.voidsign.com/api/v1/requests" \
  -H "X-VoidSign-Key: vs_live_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "auth_method": "mail",
    "invitation_mode": "voidsign_mail",
    "locales": ["fr-FR"],
    "description": "Anchor-based example",
    "documents": [
      {
        "base64": "<BASE64_CONTENT>",
        "fields": [
          {
            "type": "signature",
            "box_coordinate_system": "CS-ACP-GD",
            "box_center_anchor_tag": "VS_ANCH_SIGNATURE_CLIENT",
            "box_width_ratio": 0.3,
            "box_height_ratio": 0.1,
            "signer_ref": 1
          }
        ]
      }
    ],
    "signers": [
      {
        "ref": 1,
        "email": "jean.dupont@example.com",
        "first_name": "Jean",
        "last_name": "Dupont",
        "reminder_days": [3, 7]
      }
    ]
  }'

Astuces¶