Systèmes de coordonnées¶

Concepts communs¶

VoidSign utilise deux systèmes de coordonnées, chacun assigné à des types de champs spécifiques :

Pour les schémas complets des champs, consultez la Référence API.

Pour un guide pratique sur l'utilisation de l'outil Fields Helper et les stratégies de positionnement, consultez Positionner les champs sur un PDF.

Coordonnées en ratios¶

Toutes les valeurs de coordonnées sont des nombres décimaux dans l'intervalle [0.0, 1.0]. Une valeur représente une fraction de la largeur de la page (pour les paramètres X / largeur) ou de la hauteur de la page (pour les paramètres Y / hauteur). Le placement des champs est ainsi indépendant de la résolution.

Origine et axes de la page¶

L'origine (0.0, 0.0) se situe dans le coin supérieur gauche de la page. L'axe X augmente de gauche → droite, et l'axe Y augmente de haut → bas.

(0,0)─────────────── X (1,0)
  │                     │
  │                     │
  │     PDF page        │
  │                     │
  │                     │
Y (0,1)──────────────(1,1)

Numérotation des pages¶

Les pages sont indexées à partir de zéro : page_number: 0 correspond à la première page. Les champs de paraphe acceptent en plus "all" pour placer le champ sur chaque page.

CS-ULP-GD - Upper-Left Point + Given Dimensions¶

Utilisé par : champs signature uniquement.

Avec ce système de coordonnées, vous définissez le point d'ancrage supérieur gauche ainsi que la largeur et la hauteur explicites de la zone du champ. Le nom complet du signataire est automatiquement rendu dans la zone avec une taille de police calculée pour s'y adapter.

Fonctionnement¶

Vous fournissez quatre valeurs en ratios qui décrivent entièrement le rectangle :

(0,0)──────────────────────────────(1,0)
  │                                  │
  │  (box_x_ratio, box_y_ratio)      │
  │    ↓                             │
  │    ┌─────────────────────┐       │
  │    │                     │       │
  │    │   Signature field   │ box_height_ratio
  │    │                     │       │
  │    └─────────────────────┘       │
  │       box_width_ratio            │
  │                                  │
(0,1)──────────────────────────────(1,1)

Paramètres¶

Exemple¶

{
  "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
}

Cela place une zone de signature dont le coin supérieur gauche se situe à 15 % de la largeur de la page et 70 % de la hauteur de la page, s'étendant sur 30 % de la largeur et 10 % de la hauteur. Le signer_ref: 1 lie ce champ au signataire dont le ref est 1 dans le tableau signers.

CS-CP-AD - Center Point + Auto-Derived Dimensions¶

Utilisé par : champs text, paraph et date.

Avec ce système de coordonnées, vous spécifiez où le centre du champ doit se trouver. Le serveur calcule automatiquement la largeur et la hauteur du champ à partir du contenu et de la font_size, puis positionne la zone de sorte que son centre corresponde à vos coordonnées.

Fonctionnement¶

Vous fournissez le point central et une taille de police. La zone englobante est dérivée par le serveur :

(0,0)──────────────────────────────(1,0)
  │                                  │
  │              ┌───────────┐       │
  │              │           │       │
  │              │     ×     │       │
  │              │  (center) │       │
  │              └───────────┘       │
  │         auto-derived box         │
  │                                  │
(0,1)──────────────────────────────(1,1)

Pourquoi un système basé sur le centre ?¶

Comme le serveur dérive les dimensions de la zone à partir du contenu, vous ne pouvez pas accidentellement spécifier une zone trop petite (ou trop grande) pour le texte qu'elle contient. Vous vous concentrez sur où le champ doit être placé ; le serveur gère quelle taille il doit avoir.

Champ texte¶

Texte statique rendu sur le document.

{
  "type": "text",
  "box_coordinate_system": "CS-CP-AD",
  "box_center_x_ratio": 0.5,
  "box_center_y_ratio": 0.95,
  "page_number": 0,
  "text": "Contrat de prestation N°2024-001",
  "font_size": 12.0
}

Champ paraphe¶

Affiche les initiales du signataire (dérivées de son nom complet). Le page_number peut être un entier ou "all" pour placer les initiales sur chaque page.

{
  "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
}

Pour placer le paraphe sur une page spécifique uniquement, utilisez un entier :

{
  "type": "paraph",
  "box_coordinate_system": "CS-CP-AD",
  "box_center_x_ratio": 0.9,
  "box_center_y_ratio": 0.95,
  "page_number": 2,
  "signer_ref": 1,
  "font_size": 10.0
}

Champ date¶

Affiche la date UTC actuelle au format dd/mm/yyyy. Le contenu est généré automatiquement — vous spécifiez uniquement la position et la taille de police.

{
  "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
}

Référence rapide¶

Validation et contraintes¶

• page_number doit être inférieur au nombre de pages du PDF (indexé à partir de zéro). Une valeur dépassant le nombre de pages retourne une erreur de validation.
• Les champs date sont limités aux requêtes à signataire unique (erreur date_field_multi_signer).
• Chaque signataire doit avoir au moins un champ signature. Les champs possédant un signer_ref doivent référencer un ref de signataire valide. Note : les champs text et date n'ont pas de signer_ref et ne sont pas liés à un signataire spécifique.
• font_size doit être strictement supérieure à 0 et au maximum 100.
• text a une longueur maximale de 250 caractères.
• Toutes les valeurs en ratios (box_x_ratio, box_y_ratio, box_width_ratio, box_height_ratio, box_center_x_ratio, box_center_y_ratio) doivent être dans l'intervalle [0.0, 1.0].

Consultez le Tableau des erreurs pour la liste complète des codes d'erreur.

Cas limites¶

• Champs proches des bords de page : avec CS-CP-AD, la zone dérivée automatiquement s'étend vers l'extérieur depuis le centre. Si le centre est proche d'un bord (par exemple box_center_x_ratio: 0.98), une partie de la zone peut dépasser la limite de la page. Maintenez les coordonnées du centre dans une plage d'environ 0.05–0.95, selon la taille de police.
• Longues chaînes de texte : un texte de 250 caractères avec une font_size élevée produit une zone très large qui peut déborder de la page. Utilisez des tailles de police plus petites pour les textes longs.
• Grandes tailles de police : une font_size jusqu'à 100.0 est acceptée, mais les valeurs élevées produisent de grands champs. Testez avec votre PDF réel avant de déployer.
• Initiales de paraphe : dérivées de la première lettre de chaque mot du nom complet du signataire (séparé par des espaces et des tirets). Par exemple, « Jean-Pierre Dupont » → « JPD ». La largeur de la zone varie avec le nombre d'initiales.