Positionnement des champs

Inkr accepte 2 systèmes de coordonnées sur POST /v1/submissions/from_pdf pour placer les zones signature : fractions 0-1 (simple) et points PDF absolus (précis). Tu choisis celui qui s'adapte le mieux à ton flux. La détection est automatique côté API.

Convention des pages

Inkr accepte les 2 conventions de numérotation de page :

Tu peux mixer les 2 dans un même appel. Pour la cohérence de ton code, choisis l'une des 2 conventions et tiens-toi-y dans tous tes appels.

Système 1 : fractions 0-1 (simple)

Chaque coordonnée est une proportion de la dimension de la page. Pratique si tu veux que la zone signature soit toujours à la même position relative, quelle que soit la taille du PDF (A4, Letter US, custom).

{
  "areas": [
    { "page": 0, "x": 0.6, "y": 0.85, "w": 0.3, "h": 0.05 }
  ]
}

Lecture :

• x: 0.6 : 60 % depuis la gauche de la page.
• y: 0.85 : 85 % depuis le haut de la page (origine haut-gauche).
• w: 0.3 : largeur de la zone = 30 % de la largeur de la page.
• h: 0.05 : hauteur de la zone = 5 % de la hauteur de la page.

Sur une page A4 standard (595 × 842 points), ça donne :

• Coin haut-gauche de la zone : (357, 716) en points absolus.
• Coin bas-droit : (535, 758) en points absolus.

Système 2 : points PDF absolus (précis)

Chaque coordonnée est exprimée en points PDF (unité officielle Adobe : 1 pt = 1/72 inch). C'est l'unité native du format PDF, utilisée par pdf-lib, iText, PyPDF2 et l'Adobe Acrobat SDK.

{
  "areas": [
    { "page": 1, "x": 357, "y": 716, "w": 178, "h": 42 }
  ]
}

Lecture :

• x: 357 : 357 points depuis la gauche de la page.
• y: 716 : 716 points depuis le haut de la page (origine haut-gauche).
• w: 178 : largeur de la zone = 178 points.
• h: 42 : hauteur de la zone = 42 points.

Tailles de page courantes (largeur × hauteur en points) :

Quand utiliser l'un ou l'autre

Fractions 0-1 si :

• Ton PDF a une taille fixe connue d'avance (par exemple toujours A4).
• Tu veux la simplicité maximale au démarrage.
• Ta zone signature est positionnée par rapport à des proportions visuelles (en bas à droite, centré au milieu).

Points PDF absolus si :

• Tu génères des PDF de tailles variables (formats custom, lignes variables, tableaux dynamiques).
• Tu veux la précision pixel-perfect alignée sur le canvas du PDF.
• Tu utilises déjà pdf-lib ou un outil PDF qui te donne nativement les coordonnées en points.

Détection automatique

Inkr regarde la valeur de x et y pour deviner le système :

• Si x ≤ 1 et y ≤ 1 : fractions.
• Sinon : points PDF.

Tu n'as pas besoin de déclarer le mode explicitement. Évite de mélanger les 2 systèmes dans le même areas[] sur la même page (résultat indéterminé). Sois cohérent sur l'ensemble de l'appel.

Origine et axes

Dans les 2 systèmes, Inkr utilise la convention origine en haut-gauche (comme un écran ou la convention Web). L'axe Y descend vers le bas de la page.

Attention : la spec PDF officielle utilise au contraire origine en bas-gauche (axe Y monte). Si tu prends des coordonnées d'un outil PDF natif comme pdf-lib, tu dois inverser le Y :

const inkr_y = page_height - pdf_y - h

Exemple complet

Placer une zone signature en bas à droite d'un contrat A4, dans les 2 systèmes :

{
  "documents": [
    {
      "name": "Contrat",
      "pdf_base64": "JVBERi0xLjQK..."
    }
  ],
  "submitters": [
    {
      "email": "alice@example.com",
      "fields": [
        {
          "name": "signature",
          "type": "signature",
          "required": true,
          "areas": [
            { "page": 0, "x": 0.6, "y": 0.85, "w": 0.3, "h": 0.05 }
          ]
        }
      ]
    }
  ],
  "send_email": true
}

{
  "documents": [
    {
      "name": "Contrat",
      "file": "JVBERi0xLjQK...",
      "fields": [
        {
          "name": "signature",
          "type": "signature",
          "required": true,
          "areas": [
            { "page": 1, "x": 357, "y": 716, "w": 178, "h": 42 }
          ]
        }
      ]
    }
  ],
  "submitters": [
    { "email": "alice@example.com" }
  ],
  "send_email": true
}

Les 2 appels produisent une zone signature identique sur le PDF final.

Aller plus loin

• Quickstart : ton premier appel from_pdf en 10 minutes.
• Submissions : créer une submission depuis un template figé ou un PDF inline.
• API Reference : tous les champs acceptés par /submissions/from_pdf.