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 utiliser l'outil Fields Helper, quand les coordonnées peuvent être réutilisées, et les stratégies pour les documents dynamiques. Pour les spécifications du système de coordonnées et les tableaux de paramètres, consultez la référence 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 par programme : 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 calculez le reste par programme

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]
      }
    ]
  }'

Astuces¶