Signaturfelder & Anker

Jeder Signer braucht mindestens ein Feld, an dem er signiert. Felder setzt du mit Koordinaten oder mit Anker-Platzhaltern im Dokument. Beides lässt sich kombinieren.

Feldtypen: signature (Unterschrift), initials (Kürzel), date (Datum, beim Signieren automatisch gefüllt), custom_text (Freitext des Signers, label als Beschriftung).

Koordinaten

{ "field_type": "signature", "page": 1, "x": 72, "y": 700, "width": 200, "height": 50,
  "page_width": 595, "page_height": 842 }

• Einheit: PDF-Punkte (1 pt = 1/72 Zoll ≈ 0,353 mm). Ursprung oben links, y wächst nach unten.
• page ist 1-basiert.
• page_width/page_height: Grösse der Seite in Punkten. ratum prüft damit, dass das Feld auf die Seite passt (x + width ≤ page_width, y + height ≤ page_height), sonst 422. Die Werte werden nicht gespeichert.

Format	Breite × Höhe (pt)
A4 hoch	595 × 842
A4 quer	842 × 595
US Letter	612 × 792

Bei createAndSend stehen die Felder direkt am Signer (signers[].fields). In den Einzelschritten legst du sie mit POST /documents/{id}/signature-fields und signer_id an.

Anker-Platzhalter

Statt Koordinaten zu berechnen, schreibst du einen Platzhalter an die Stelle im Dokument (z. B. in der Word-Vorlage), an der das Feld erscheinen soll:

{{ratum:<feldtyp>:<signer-index>}}

• feldtyp: signature, initials, date oder custom_text
• signer-index: 1-basiert, entspricht der Signier-Reihenfolge (erster Signer = 1)

Beispiele: {{ratum:signature:1}}, {{ratum:date:1}}, {{ratum:initials:2}}.

Aktivieren

Anker sind nur über die API verfügbar und werden beim Senden mit anchors eingeschaltet, bei createAndSend oder POST /documents/{id}/send. Ein leeres Objekt nutzt die Default-Grössen:

{
  "filename": "vertrag.docx",
  "content_type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
  "size_bytes": 48211,
  "signers": [{ "email": "erika@example.com" }, { "email": "max@example.com" }],
  "anchors": {}
}

Mit anchors brauchen Signer keine Koordinaten-Felder; ohne anchors braucht jeder Signer mindestens ein Feld. Koordinaten und Anker lassen sich kombinieren.

Feldgrösse

Default je Feldtyp in PDF-Punkten (Breite × Höhe):

Feldtyp	Default
signature	180 × 50
initials	60 × 40
date	110 × 24
custom_text	160 × 24

Überschreiben pro Feldtyp (je 1–1000 pt):

"anchors": { "sizes": { "signature": { "width": 220, "height": 60 } } }

So platziert ratum das Feld

• Nach Malware-Scan und gegebenenfalls DOCX-Konvertierung sucht ratum die Platzhalter im PDF-Text.
• Das Feld sitzt an der Unterkante des Platzhalters und wächst nach oben und rechts. Das passt zu Zeilen wie «Unterschrift: {{ratum:signature:1}}». Am Seitenrand wird es nach innen verschoben.
• Das Feld deckt den Platzhalter ab. Es ist mindestens so gross wie der Platzhalter; im versiegelten PDF ist der Platzhaltertext nicht mehr sichtbar.
• Gefundene Anker (Seite, Position, Text) stehen im Audit-Report.

Keine weisse oder unsichtbare Schrift

ratum empfiehlt ausdrücklich nicht, Platzhalter in weisser, winziger oder sonst unsichtbarer Schrift zu setzen. Versteckter Text in signierten Dokumenten soll nicht zum Normalfall werden, und das Feld deckt den Platzhalter ohnehin ab. Platzhalter normal sichtbar setzen und genug Platz für das Feld lassen.

Platzhalter müssen als Text im PDF stehen. Das ist bei Word-Dokumenten und den meisten exportierten PDFs der Fall, bei gescannten Dokumenten (Bild statt Text) nicht.

Grenzen

• höchstens 200 Seiten, 60 Sekunden Suchzeit
• höchstens 20 Platzhalter je Signer (100 im Dokument)
• ein einzelner Platzhalter höchstens 500 × 40 pt gross (sehr grosse Schrift wird abgelehnt, damit die Abdeckung keinen echten Inhalt überdeckt)
• keine Platzhalter auf gedrehten Seiten

Fehler

Code	Ursache
anchor_not_found	Platzhalter ohne passenden Signer (z. B. {{ratum:signature:3}} bei zwei Signern), Signer ohne Platzhalter und ohne Koordinaten-Feld, mehr als 20 Platzhalter je Signer, Platzhalter zu gross
anchor_scan_failed	PDF für die Suche abgelehnt: zu viele Seiten oder Platzhalter, Zeit- oder Speicherlimit, Platzhalter auf gedrehter Seite, unlesbares PDF, Suche wiederholt abgebrochen oder Datei fehlt

Ist das PDF beim Senden schon verarbeitet, kommt der Fehler sofort als 422. Sonst (Normalfall bei «Senden, sobald bereit») wechselt das Dokument auf failed mit dem Code als failure_code, und der Webhook document.failed feuert.