Automatisches Platzieren von Unterschriftenfeldern mit Anker-Tags: Textbasierte Feldplatzierung

Wenn Sie jemals Unterschriftsfelder durch Berechnung der x/y-Koordinaten auf einem PDF positioniert haben, wissen Sie, wie mühsam das in großem Maßstab wird. Ändern Sie das Dokumentlayout, und jede Koordinate bricht. Fügen Sie eine zweite Seite hinzu, und Sie berechnen die Versätze für die Hälfte Ihrer Felder neu.

Ankerkategorien beheben dies. Betten Sie Textmarker wie {{SIGN_HERE}} oder {{DATE}} direkt in Ihre PDF-Vorlage ein, und Firma.dev erkennt sie automatisch und platziert die richtigen Feldtypen an diesen Stellen. Die Markierungen werden aus dem endgültigen Dokument entfernt, sodass Unterzeichner sie nie sehen. Ein API-Aufruf, keine Koordinatenmathematik.

Ankerkategorien wurden in v1.11.0 eingeführt und unterstützen alle Feldtypen, flexible Übereinstimmungsregeln und bis zu 100 Markierungen pro Signaturanfrage.

Schnellstart

Der schnellste Weg, um Ankerkategorien zum Laufen zu bringen: Betten Sie einen Marker in Ihr PDF ein und erstellen Sie dann eine Signaturanfrage mit einem anchor_tags-Array.

Schritt 1: Fügen Sie den Text {{SIGN_HERE}} irgendwo in Ihrem PDF hinzu, wo das Unterschriftsfeld erscheinen soll. Sie können dies mit jedem Tool tun, das Ihre Dokumente erstellt, sei es eine Word-Vorlage, eine PDF-Bibliothek oder ein Dokumentengenerierungsdienst.

Schritt 2: Erstellen Sie eine dokumentbasierte Signaturanfrage mit der Ankerkategorie-Definition:

const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      workspace_id: workspaceId,
      document: documentBase64,
      name: 'NDA - Acme Corp',
      anchor_tags: [
        {
          anchor_string: '{{SIGN_HERE}}',
          type: 'signature',
          recipient_id: 'temp_1',
          required: true
        }
      ],
      recipients: [
        {
          id: 'temp_1',
          first_name: 'Jane',
          last_name: 'Smith',
          email: 'jane@example.com',
          designation: 'Signer',
          order: 1
        }
      ]
    })
  }
);

const signingRequest = await response.json();

const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      workspace_id: workspaceId,
      document: documentBase64,
      name: 'NDA - Acme Corp',
      anchor_tags: [
        {
          anchor_string: '{{SIGN_HERE}}',
          type: 'signature',
          recipient_id: 'temp_1',
          required: true
        }
      ],
      recipients: [
        {
          id: 'temp_1',
          first_name: 'Jane',
          last_name: 'Smith',
          email: 'jane@example.com',
          designation: 'Signer',
          order: 1
        }
      ]
    })
  }
);

const signingRequest = await response.json();

const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      workspace_id: workspaceId,
      document: documentBase64,
      name: 'NDA - Acme Corp',
      anchor_tags: [
        {
          anchor_string: '{{SIGN_HERE}}',
          type: 'signature',
          recipient_id: 'temp_1',
          required: true
        }
      ],
      recipients: [
        {
          id: 'temp_1',
          first_name: 'Jane',
          last_name: 'Smith',
          email: 'jane@example.com',
          designation: 'Signer',
          order: 1
        }
      ]
    })
  }
);

const signingRequest = await response.json();

Firma.dev durchsucht das PDF nach {{SIGN_HERE}}, platziert ein Unterschriftsfeld an dieser Stelle, weist es dem Empfänger zu und entfernt den Markertext aus dem Dokument. Das war’s.

Beachten Sie, dass Ankerkategorien nur mit der dokumentbasierten Signaturanfrage-Erstellung und nicht mit der vorlagenbasierten funktionieren. Sie senden das rohe PDF und überlassen dem Ankersystem die Feldplatzierung.

Unterstützte Feldtypen

Ankerkategorien unterstützen jeden Feldtyp, der in Firma.dev verfügbar ist. Setzen Sie die type-Eigenschaft auf jedem Anker-Tag auf einen der folgenden Werte:

signature für Unterschriftsfelder, initials für Initialfelder, text für einzeilige Texteingabe, textarea für mehrzeilige Texteingabe, date für Datumsfelder, checkbox für Kontrollkästchen, radio für Radiobutton-Gruppen, dropdown für Dropdown-Auswahlen, url für URL-Felder, stamp für Stempelfelder und file für Dateiupload-Felder.

Jeder Typ rendert das entsprechende Feld-Widget in der Signiererfahrung. Ein date-Ankertag erstellt einen Datumsauswahl, ein dropdown erstellt ein Auswahlmenü und so weiter.

Übereinstimmungs- und Positionierungsoptionen

Das Standard-Übereinstimmungsverhalten funktioniert in den meisten Fällen, aber Sie können die Art und Weise, wie Firma.dev Anker-erzeugte Felder findet und positioniert, feinabstimmen.

Groß- und Kleinschreibung: Setzen Sie case_sensitive auf true oder false (Standard ist false). Mit case-insensitiver Übereinstimmung stimmen {{sign_here}} und {{SIGN_HERE}} beide überein.

Exakte Wortübereinstimmung: Setzen Sie whole_word auf true, um Teilübereinstimmungen zu verhindern. Wenn Ihr Ankerstring SIGN ist und whole_word auf false gesetzt ist, würde er auch SIGNATURE oder COSIGN übereinstimmen. Setzen Sie ihn auf true, um sicherzustellen, dass nur das exakte Wort übereinstimmt.

Zielen auf spezifische Vorkommen: Wenn Ihr PDF denselben Ankerstring mehrmals enthält, können Sie mit occurrence spezifische Vorkommen anvisieren. Setzen Sie es auf 1 für das erste Übereinstimmung, 2 für das zweite usw. Lassen Sie es weg oder setzen match_all auf true, um Felder bei jedem Vorkommen zu platzieren.

Offsets bei der Positionierung: Feinabstimmung, wo das Feld im Verhältnis zum Ankertext landet, unter Verwendung von offset_x und offset_y. Sie können Offsets in Prozent (relativ zu Seitenabmessungen) oder Pixeln angeben. Dies ist nützlich, wenn Sie möchten, dass das Feld leicht unterhalb oder rechts vom Markierer positioniert wird, anstatt direkt darüber.

Elegantes Handhaben fehlender Anker: Setzen Sie ignore_if_not_present auf true, wenn der Ankerstring möglicherweise nicht in jedem Dokument vorhanden ist. Andernfalls führt ein fehlender Anker zu einem Fehler. Wenn diese Option aktiviert ist, überspringt Firma.dev dieses Tag stillschweigend und verarbeitet den Rest.

Erweiterte Konfiguration

Hier ist ein umfassenderes Beispiel, das mehrere Anker-Tag mit verschiedenen Feldtypen, benutzerdefinierten Abmessungen und Positionierungsoffsets kombiniert:

const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      workspace_id: workspaceId,
      document: documentBase64,
      name: 'Employment Agreement',
      anchor_tags: [
        {
          anchor_string: '{{EMPLOYEE_SIGNATURE}}',
          type: 'signature',
          recipient_id: 'temp_1',
          required: true,
          width: 30,
          height: 8,
          offset_y: 2
        },
        {
          anchor_string: '{{EMPLOYEE_DATE}}',
          type: 'date',
          recipient_id: 'temp_1',
          required: true
        },
        {
          anchor_string: '{{EMPLOYEE_INITIALS}}',
          type: 'initials',
          recipient_id: 'temp_1',
          required: true,
          match_all: true
        },
        {
          anchor_string: '{{MANAGER_SIGNATURE}}',
          type: 'signature',
          recipient_id: 'temp_2',
          required: true
        },
        {
          anchor_string: '{{BENEFITS_OPT_IN}}',
          type: 'checkbox',
          recipient_id: 'temp_1',
          required: false,
          ignore_if_not_present: true
        }
      ],
      recipients: [
        {
          id: 'temp_1',
          first_name: 'Sarah',
          last_name: 'Chen',
          email: 'sarah@example.com',
          designation: 'Signer',
          order: 1
        },
        {
          id: 'temp_2',
          first_name: 'Mike',
          last_name: 'Torres',
          email: 'mike@example.com',
          designation: 'Signer',
          order: 2
        }
      ]
    })
  }
);

const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      workspace_id: workspaceId,
      document: documentBase64,
      name: 'Employment Agreement',
      anchor_tags: [
        {
          anchor_string: '{{EMPLOYEE_SIGNATURE}}',
          type: 'signature',
          recipient_id: 'temp_1',
          required: true,
          width: 30,
          height: 8,
          offset_y: 2
        },
        {
          anchor_string: '{{EMPLOYEE_DATE}}',
          type: 'date',
          recipient_id: 'temp_1',
          required: true
        },
        {
          anchor_string: '{{EMPLOYEE_INITIALS}}',
          type: 'initials',
          recipient_id: 'temp_1',
          required: true,
          match_all: true
        },
        {
          anchor_string: '{{MANAGER_SIGNATURE}}',
          type: 'signature',
          recipient_id: 'temp_2',
          required: true
        },
        {
          anchor_string: '{{BENEFITS_OPT_IN}}',
          type: 'checkbox',
          recipient_id: 'temp_1',
          required: false,
          ignore_if_not_present: true
        }
      ],
      recipients: [
        {
          id: 'temp_1',
          first_name: 'Sarah',
          last_name: 'Chen',
          email: 'sarah@example.com',
          designation: 'Signer',
          order: 1
        },
        {
          id: 'temp_2',
          first_name: 'Mike',
          last_name: 'Torres',
          email: 'mike@example.com',
          designation: 'Signer',
          order: 2
        }
      ]
    })
  }
);

const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      workspace_id: workspaceId,
      document: documentBase64,
      name: 'Employment Agreement',
      anchor_tags: [
        {
          anchor_string: '{{EMPLOYEE_SIGNATURE}}',
          type: 'signature',
          recipient_id: 'temp_1',
          required: true,
          width: 30,
          height: 8,
          offset_y: 2
        },
        {
          anchor_string: '{{EMPLOYEE_DATE}}',
          type: 'date',
          recipient_id: 'temp_1',
          required: true
        },
        {
          anchor_string: '{{EMPLOYEE_INITIALS}}',
          type: 'initials',
          recipient_id: 'temp_1',
          required: true,
          match_all: true
        },
        {
          anchor_string: '{{MANAGER_SIGNATURE}}',
          type: 'signature',
          recipient_id: 'temp_2',
          required: true
        },
        {
          anchor_string: '{{BENEFITS_OPT_IN}}',
          type: 'checkbox',
          recipient_id: 'temp_1',
          required: false,
          ignore_if_not_present: true
        }
      ],
      recipients: [
        {
          id: 'temp_1',
          first_name: 'Sarah',
          last_name: 'Chen',
          email: 'sarah@example.com',
          designation: 'Signer',
          order: 1
        },
        {
          id: 'temp_2',
          first_name: 'Mike',
          last_name: 'Torres',
          email: 'mike@example.com',
          designation: 'Signer',
          order: 2
        }
      ]
    })
  }
);

Einige Dinge, die in diesem Beispiel zu beachten sind. Der {{EMPLOYEE_INITIALS}}-Tag verwendet match_all: true, sodass wenn das PDF Initialmarker auf den Seiten 1, 5 und 12 hat, alle drei Felder erhalten. Das {{BENEFITS_OPT_IN}}-Kontrollkästchen verwendet ignore_if_not_present: true, da nicht jede Version des Arbeitsvertrags diesen Abschnitt enthält. Und offset_y: 2 auf dem Unterschriftsfeld verlagert es leicht nach unten von der Ankertextposition.

Abmessungen (width und height) folgen demselben prozentbasierten Koordinatensystem, das von manuell positionierten Feldern verwendet wird. Anker-Tags und manuelle Felder arbeiten zusammen, sodass Sie Anker für den Großteil Ihrer Felder verwenden und in derselben Anfrage weiterhin manuelle, koordinatenbasierte Felder für Sonderfälle hinzufügen können.

Migration von anderen Plattformen

Wenn Sie von einem anderen E-Signatur-Anbieter migrieren, der textbasierte Feldplatzierung verwendet, stimmen die Konzepte direkt überein. Der Ankerstring-Syntax und die Eigenschaftsnamen unterscheiden sich, aber der zugrunde liegende Mechanismus ist derselbe: einbetten eines Markers, definieren des Feldtyps, die API übernimmt die Platzierung.

Von DocuSign Auto-Place: DocuSign verwendet anchorString, anchorXOffset, anchorYOffset und tab-spezifische Typen wie signHereTabs. In Firma.dev wird dies zu anchor_string, offset_x, offset_y und dem universellen type-Feld. DocuSigns anchorIgnoreIfNotPresent entspricht ignore_if_not_present. DocuSigns anchorCaseSensitive entspricht case_sensitive. Der Hauptunterschied in der Struktur besteht darin, dass Firma.dev ein einzelnes anchor_tags-Array mit einer type-Eigenschaft verwendet, anstatt separate Arrays für jeden Tabtypen.

Von Yousign Smart Anchors: Yousigns Konzept von "smart anchors" mit Feldtypenerkennung wird direkt übersetzt. Die Übereinstimmungs- und Positionierungsoptionen sind vergleichbar, obwohl die Eigenschaftsnamen die Snake-Case-Konvention von Firma.dev verwenden.

Das Limit beträgt 100 Anker-Tags pro Signaturanfrage, was die meisten Dokumenten-Workflows problemlos abdeckt. Wenn Sie Dokumente bearbeiten, die tatsächlich mehr als 100 Felder benötigen, sollten Sie in Erwägung ziehen, mehrere Signaturanfragen zu teilen oder eine Kombination aus Anker-Tags und vorlagenbasierten Felddefinitionen zu verwenden.

API-Referenz

Das anchor_tags-Array ist im dokumentbasierten Signaturanfrage-Erstellungsendpunkt verfügbar (POST /signing-requests). Jedes Element in dem Array ist ein AnchorTag-Objekt mit etwa 25 konfigurierbaren Eigenschaften.

Die Schlüsselfelder:

anchor_string (erforderlich) ist der Textmarker, nach dem im PDF gesucht wird. type (erforderlich) ist der zu erstellende Feldtyp. recipient_id ordnet das Feld einem bestimmten Empfänger zu und verwendet dessen ID oder temporäre ID. required kennzeichnet das Feld als obligatorisch oder optional. offset_x und offset_y passen die Feldposition relativ zur Ankerstelle an. width und height legen benutzerdefinierte Feldabmessungen fest. case_sensitive steuert, ob die Übereinstimmung Groß-/Kleinschreibung beachtet. whole_word verhindert Teilstring-Übereinstimmungen. occurrence zielt auf eine spezifische Instanz ab, wenn der Anker mehrfach angezeigt wird. match_all platziert Felder bei jedem Vorkommen. ignore_if_not_present überspringt das Tag, ohne einen Fehler zu verursachen, wenn der Ankertext im Dokument nicht gefunden wird.

Für das vollständige Schema mit allen Eigenschaften und deren Typen siehe das API-Changelog für v1.11.0.

Nächste Schritte

Ankerkategorien passen gut zu programmatischer Dokumentengenerierung. Wenn Ihre App Verträge, NDAs oder Onboarding-Dokumente aus Vorlagen generiert, können Sie während der Generierung Ankerstrings einbetten und Firma.dev auf jeder Anfrage die Feldplatzierung automatisch übernehmen lassen.

Kostenlos mit Firma.dev starten, keine Kreditkarte erforderlich.