Neu in Firma.dev: Unterzeichnen Sie das gesamte Vertragspaket in einer Anfrage – jede Datei einzeln versiegelt

Ein B2B-Deal wird in der Regel über einen Stapel von Dateien abgeschlossen: ein Rahmenvertrag (Master Services Agreement), ein Leistungsverzeichnis (Statement of Work), eine Vertraulichkeitsvereinbarung (NDA) und ein Bestellformular – die alle an denselben Kunden für dieselbe Unterschrift gehen. Ab API v1.39.0 kann dieses gesamte Paket als eine einzige Firma.dev-Signaturanfrage versendet werden, und jede darin enthaltene Datei wird als eigenes, versiegeltes Dokument zurückgegeben.

Multi-Dokumenten-Signieren ist für jedes Firma.dev-Konto verfügbar

Das ist neu und für jeden bereits aktiviert. Das Release bringt folgende Neuerungen:

• Eine Vorlage oder Signaturanfrage kann bis zu 20 Dokumente umfassen, mit einem Limit von 100 MB pro Dokumentensatz.

• POST /templates, POST /signing-requests und POST /signing-requests/create-and-send akzeptieren document_ids, eine Liste von Uploads in Dokumentenreihenfolge.

• Neue /documents-Routen ermöglichen das Hinzufügen, Ersetzen, Umbenennen, Neuanordnen, Entfernen und Herunterladen von Dokumenten einzeln nacheinander.

• Anker-Tags können mit document_index gezielt auf ein einzelnes Dokument verweisen.

• Jedes Dokument einer abgeschlossenen Signaturanfrage wird als eigene, individuell versiegelte Datei mit eigenem SHA-256-Hash heruntergeladen.

Das Changelog datiert das Release auf den 12. Oktober 2026, und Multi-Dokumenten-Funktionen stehen jedem Unternehmen seit dem 13. Oktober 2026 zur Verfügung. Es muss nichts aktiviert und kein Feature-Flag angefordert werden.

Auch an den Preisen ändert sich nichts. Eine Signaturanfrage entspricht einem Credit, 0,049 € (~5¢ USD), unabhängig davon, ob sie ein Dokument oder zwanzig enthält. Die Dokumentations-FAQ stellt dies unmissverständlich klar: Ein Credit entspricht einer Signaturanfrage, unabhängig davon, wie viele Unterzeichner oder Dokumente darin enthalten sind. Es bleibt weiterhin Pay-as-you-go ohne monatliche Mindestbeträge und ohne Gebühren pro Arbeitsplatz.

Was für ein Paket aus vier Dokumenten früher nötig war

Bis zu diesem Release enthielt eine Signaturanfrage genau ein Dokument. Ein Paket zu versenden bedeutete, Hilfscode um dieses Limit herum zu schreiben, was in der Regel so aussah:

An den Schritten 2 und 4 scheitert es oft. Ein Kunde tauscht eine dreiseitige NDA gegen eine zweiseitige aus, und jedes nachfolgende Feld landet auf der falschen Seite. Die Split-Bereiche verschieben sich auf die gleiche Weise ... und bei einer SaaS-Plattform, auf der eigene Kunden diese Pakete hochladen, sieht das Paket jedes Mandanten etwas anders aus – der Fehler tritt also bei einem Mandanten nach dem anderen auf.

Mit v1.39.0 entfallen die Schritte Zusammenführen, Offset berechnen und Aufteilen. Jede Datei wird als eigener Upload übergeben, durchläuft einen einzigen Signaturprozess und kommt eigenständig versiegelt zurück.

Paket mit document_ids versenden

Jede Datei mit POST /documents hochladen

Jedes Dokument im Set beginnt als Upload. POST /documents nimmt Dateiname, Größe und Content-Type entgegen und gibt eine temporäre document_id sowie eine vorab signierte upload_url zurück. An diese URL senden Sie die reinen Dateibytes per PUT. Es ist ein Upload pro Datei ... ein Paket aus vier Dokumenten erfordert also vier Uploads, noch bevor die Signaturanfrage überhaupt existiert.

const API = "https://api.firma.dev/functions/v1/signing-request-api";
const headers = {
  Authorization: process.env.FIRMA_API_KEY,
  "Content-Type": "application/json",
};

async function upload(fileName, bytes) {
  const res = await fetch(`${API}/documents`, {
    method: "POST",
    headers,
    body: JSON.stringify({
      file_name: fileName,
      file_size: bytes.length,
      content_type: "application/pdf",
    }),
  });
  const { document_id, upload_url } = await res.json();

  await fetch(upload_url, {
    method: "PUT",
    headers: { "Content-Type": "application/pdf" },
    body: bytes,
  });
  return document_id;
}

const API = "https://api.firma.dev/functions/v1/signing-request-api";
const headers = {
  Authorization: process.env.FIRMA_API_KEY,
  "Content-Type": "application/json",
};

async function upload(fileName, bytes) {
  const res = await fetch(`${API}/documents`, {
    method: "POST",
    headers,
    body: JSON.stringify({
      file_name: fileName,
      file_size: bytes.length,
      content_type: "application/pdf",
    }),
  });
  const { document_id, upload_url } = await res.json();

  await fetch(upload_url, {
    method: "PUT",
    headers: { "Content-Type": "application/pdf" },
    body: bytes,
  });
  return document_id;
}

const API = "https://api.firma.dev/functions/v1/signing-request-api";
const headers = {
  Authorization: process.env.FIRMA_API_KEY,
  "Content-Type": "application/json",
};

async function upload(fileName, bytes) {
  const res = await fetch(`${API}/documents`, {
    method: "POST",
    headers,
    body: JSON.stringify({
      file_name: fileName,
      file_size: bytes.length,
      content_type: "application/pdf",
    }),
  });
  const { document_id, upload_url } = await res.json();

  await fetch(upload_url, {
    method: "PUT",
    headers: { "Content-Type": "application/pdf" },
    body: bytes,
  });
  return document_id;
}

Dieser Weg ist auch für große Dateien vorgesehen. Seit v1.40.0 gibt jeder Request-Body über 6 MiB den Fehler 413 REQUEST_TOO_LARGE zurück; große PDFs gehören daher ohnehin über POST /documents hochgeladen. Ein einzelner Upload darf bis zu 50 MB groß sein (das gesamte Set ist auf 100 MB begrenzt).

In Dokumentenreihenfolge erstellen und senden

Übergeben Sie 1 bis 20 Upload-IDs in document_ids, in der Reihenfolge, in der die Dokumente erscheinen sollen. POST /signing-requests/create-and-send akzeptiert diese. Dasselbe gilt für POST /signing-requests (für einen Entwurf, den Sie später versenden) und POST /templates.

Jeder Erstellungsvorgang akzeptiert genau eine Dokumentenquelle: document, document_id, document_ids oder template_id. Wenn Sie mehr als eine übergeben, gibt die API 400 CONFLICTING_DOCUMENT_SOURCE zurück. Eine doppelte ID führt zu 400 DUPLICATE_DOCUMENT_ID, mehr als 20 Dokumente führen zu 400 MAX_DOCUMENTS_EXCEEDED und ein Dokumentensatz über 100 MB zu 413 DOCUMENT_SET_TOO_LARGE.

Anker-Tags auf das richtige Dokument ausrichten

Anker-Tags unterstützen jetzt document_index, die 1-basierte Position des Zieldokuments in document_ids. Bei einem einzelnen Dokument ist dies optional und standardmäßig auf 1 gesetzt. Bei mehr als einem Dokument ist die Angabe erforderlich; das Weglassen führt zu 400 ANCHOR_DOCUMENT_REQUIRED. Damit bleibt das {{SIGN_HERE}} in der NDA von dem {{SIGN_HERE}} im SOW getrennt, selbst wenn jede Datei im Paket dieselbe Markierung verwendet.

const packet = [
  { name: "msa.pdf", bytes: msa },
  { name: "sow.pdf", bytes: sow },
  { name: "nda.pdf", bytes: nda },
  { name: "order-form.pdf", bytes: orderForm },
];
const documentIds = await Promise.all(packet.map((d) => upload(d.name, d.bytes)));

const res = await fetch(`${API}/signing-requests/create-and-send`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    name: "Acme Corp - Q4 deal packet",
    document_ids: documentIds, // MSA, SOW, NDA, order form
    recipients: [
      {
        id: "temp_1",
        first_name: "Dana",
        last_name: "Reyes",
        email: "dana@acme.example",
        designation: "Signer",
        order: 1,
      },
    ],
    anchor_tags: [
      { anchor_string: "{{SIGN_HERE}}", type: "signature", recipient_id: "temp_1", document_index: 1 },
      { anchor_string: "{{SIGN_HERE}}", type: "signature", recipient_id: "temp_1", document_index: 2 },
      { anchor_string: "{{SIGN_HERE}}", type: "signature", recipient_id: "temp_1", document_index: 3 },
      { anchor_string: "{{SIGN_HERE}}", type: "signature", recipient_id: "temp_1", document_index: 4 },
      { anchor_string: "{{DATE}}", type: "date", recipient_id: "temp_1", document_index: 4 },
    ],
  }),
});
const signingRequest = await res.json(); // signingRequest.id

const packet = [
  { name: "msa.pdf", bytes: msa },
  { name: "sow.pdf", bytes: sow },
  { name: "nda.pdf", bytes: nda },
  { name: "order-form.pdf", bytes: orderForm },
];
const documentIds = await Promise.all(packet.map((d) => upload(d.name, d.bytes)));

const res = await fetch(`${API}/signing-requests/create-and-send`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    name: "Acme Corp - Q4 deal packet",
    document_ids: documentIds, // MSA, SOW, NDA, order form
    recipients: [
      {
        id: "temp_1",
        first_name: "Dana",
        last_name: "Reyes",
        email: "dana@acme.example",
        designation: "Signer",
        order: 1,
      },
    ],
    anchor_tags: [
      { anchor_string: "{{SIGN_HERE}}", type: "signature", recipient_id: "temp_1", document_index: 1 },
      { anchor_string: "{{SIGN_HERE}}", type: "signature", recipient_id: "temp_1", document_index: 2 },
      { anchor_string: "{{SIGN_HERE}}", type: "signature", recipient_id: "temp_1", document_index: 3 },
      { anchor_string: "{{SIGN_HERE}}", type: "signature", recipient_id: "temp_1", document_index: 4 },
      { anchor_string: "{{DATE}}", type: "date", recipient_id: "temp_1", document_index: 4 },
    ],
  }),
});
const signingRequest = await res.json(); // signingRequest.id

const packet = [
  { name: "msa.pdf", bytes: msa },
  { name: "sow.pdf", bytes: sow },
  { name: "nda.pdf", bytes: nda },
  { name: "order-form.pdf", bytes: orderForm },
];
const documentIds = await Promise.all(packet.map((d) => upload(d.name, d.bytes)));

const res = await fetch(`${API}/signing-requests/create-and-send`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    name: "Acme Corp - Q4 deal packet",
    document_ids: documentIds, // MSA, SOW, NDA, order form
    recipients: [
      {
        id: "temp_1",
        first_name: "Dana",
        last_name: "Reyes",
        email: "dana@acme.example",
        designation: "Signer",
        order: 1,
      },
    ],
    anchor_tags: [
      { anchor_string: "{{SIGN_HERE}}", type: "signature", recipient_id: "temp_1", document_index: 1 },
      { anchor_string: "{{SIGN_HERE}}", type: "signature", recipient_id: "temp_1", document_index: 2 },
      { anchor_string: "{{SIGN_HERE}}", type: "signature", recipient_id: "temp_1", document_index: 3 },
      { anchor_string: "{{SIGN_HERE}}", type: "signature", recipient_id: "temp_1", document_index: 4 },
      { anchor_string: "{{DATE}}", type: "date", recipient_id: "temp_1", document_index: 4 },
    ],
  }),
});
const signingRequest = await res.json(); // signingRequest.id

Wenn Anker-Tags neu für Sie sind, erläutert die Anker-Tags-Anleitung Offsets, Vorkommen und Größenanpassung.

Jedes Dokument kommt eigenständig versiegelt zurück

GET /signing-requests/{id} gibt ein documents-Array zurück. Jeder Eintrag enthält document_id, position, label, original_filename und page_count. Bei Signaturanfragen enthält er zudem document_only_hash, den SHA-256-Hash des individuell versiegelten Dokuments, sobald das Zertifikat gebunden ist (davor null).

Um eine Datei abzurufen, rufen Sie GET /signing-requests/{id}/documents/{document_id}/download auf. Dies gibt eine signierte URL zurück, die für 1 Stunde gültig ist:

• type=original (der Standardwert) gibt das Dokument so zurück, wie es hochgeladen wurde.

• type=document gibt das individuell versiegelte Dokument zurück, sobald das Zertifikat gebunden ist. Davor wird 404 DOCUMENT_SIGNED_NOT_AVAILABLE zurückgegeben – werten Sie diesen Code also als „noch nicht bereit“ und versuchen Sie es kurz darauf erneut.

Für eine SaaS-App macht dies den letzten Rest an Hilfscode überflüssig. Die folgende Schleife schreibt die signierte MSA in den Vertragsdatensatz, die signierte NDA in den NDA-Datensatz usw., wobei der Hash jeder Datei direkt daneben gespeichert wird. Und da position der Reihenfolge entspricht, die Sie in document_ids übergeben haben, lässt sie sich direkt wieder dem von Ihnen erstellten Paket zuordnen.

async function storeSignedPacket(signingRequestId, packetRecords) {
  const sr = await fetch(`${API}/signing-requests/${signingRequestId}`, { headers })
    .then((r) => r.json());

  for (const doc of sr.documents) {
    const res = await fetch(
      `${API}/signing-requests/${signingRequestId}/documents/${doc.document_id}/download?type=document`,
      { headers }
    );
    const body = await res.json();

    if (body.code === "DOCUMENT_SIGNED_NOT_AVAILABLE") {
      return scheduleRetry(signingRequestId); // certificate not bound yet
    }
    if (!res.ok) throw new Error(`${body.code}: ${body.error}`);

    const pdf = Buffer.from(await (await fetch(body.download_url)).arrayBuffer());

    await records.saveSignedFile({
      record: packetRecords[doc.position - 1], // contract, SOW, NDA, order form
      file: pdf,
      sha256: doc.document_only_hash,
    });
  }
}

async function storeSignedPacket(signingRequestId, packetRecords) {
  const sr = await fetch(`${API}/signing-requests/${signingRequestId}`, { headers })
    .then((r) => r.json());

  for (const doc of sr.documents) {
    const res = await fetch(
      `${API}/signing-requests/${signingRequestId}/documents/${doc.document_id}/download?type=document`,
      { headers }
    );
    const body = await res.json();

    if (body.code === "DOCUMENT_SIGNED_NOT_AVAILABLE") {
      return scheduleRetry(signingRequestId); // certificate not bound yet
    }
    if (!res.ok) throw new Error(`${body.code}: ${body.error}`);

    const pdf = Buffer.from(await (await fetch(body.download_url)).arrayBuffer());

    await records.saveSignedFile({
      record: packetRecords[doc.position - 1], // contract, SOW, NDA, order form
      file: pdf,
      sha256: doc.document_only_hash,
    });
  }
}

async function storeSignedPacket(signingRequestId, packetRecords) {
  const sr = await fetch(`${API}/signing-requests/${signingRequestId}`, { headers })
    .then((r) => r.json());

  for (const doc of sr.documents) {
    const res = await fetch(
      `${API}/signing-requests/${signingRequestId}/documents/${doc.document_id}/download?type=document`,
      { headers }
    );
    const body = await res.json();

    if (body.code === "DOCUMENT_SIGNED_NOT_AVAILABLE") {
      return scheduleRetry(signingRequestId); // certificate not bound yet
    }
    if (!res.ok) throw new Error(`${body.code}: ${body.error}`);

    const pdf = Buffer.from(await (await fetch(body.download_url)).arrayBuffer());

    await records.saveSignedFile({
      record: packetRecords[doc.position - 1], // contract, SOW, NDA, order form
      file: pdf,
      sha256: doc.document_only_hash,
    });
  }
}

Wenn Sie auch die Downloads auf Anfrageebene benötigen (die reine Dokumenten-PDF und das separate Zertifikat), werden diese im Beitrag zu separaten PDF-Downloads behandelt. Jede Signaturanfrage behält zudem ihren Audit-Trail.

Vorlagen, die einen Dokumentensatz enthalten

Eine Vorlage kann ebenfalls das gesamte Paket enthalten, was sich für Plattformen eignet, die jedem neuen Kunden denselben Satz senden. Erstellen Sie sie mit document_ids über POST /templates und verwalten Sie anschließend jede Datei unter /templates/{id}/documents:

• POST /templates/{id}/documents fügt ein Dokument an der angegebenen position hinzu, oder als letztes, wenn die Position weggelassen wird.

• PATCH /templates/{id}/documents/{document_id} ersetzt das Dokument durch einen neuen Upload (document_id) oder benennt es um (label). Übergeben Sie genau einen der beiden Werte pro Aufruf.

• PUT /templates/{id}/documents/order ordnet den Satz neu an. Die Liste muss jedes Dokument genau einmal enthalten, andernfalls wird 400 INVALID_DOCUMENT_ORDER zurückgegeben.

• DELETE /templates/{id}/documents/{document_id} entfernt ein Dokument. Das letzte verbleibende Dokument kann nicht entfernt werden.

Ein Austausch behält die Felder an ihrer Stelle, solange die neue Datei dieselbe Seitenzahl hat und jede Seite innerhalb von 1 pt dieselbe Größe aufweist. Andernfalls erhalten Sie 400 PAGE_COUNT_MISMATCH oder 400 DIMENSION_MISMATCH. Wenn die Rechtsabteilung also die NDA aktualisiert, tauschen Sie nur diese eine Datei aus ... und die Felder auf MSA, SOW und Bestellformular bleiben genau dort, wo sie waren. Die Funktionsseite zum Ersetzen von Vorlagendokumenten behandelt den Austausch ausführlicher.

Es gibt auch einen Schutz vor Nebenläufigkeit (Concurrency Guard), der besonders bei mandantenfähigen Setups wichtig ist (zwei Dienste oder zwei Administratoren, die dieselbe Vorlage bearbeiten). documents_layout_version erhöht sich, sobald Dokumente hinzugefügt, entfernt oder neu geordnet werden. Schreibvorgänge auf Feldern über PUT und PATCH auf /templates/{id} und /signing-requests/{id} senden den Wert Ihres letzten Lesevorgangs mit. Dies ist erforderlich, sobald mehr als ein Dokument vorhanden ist oder die Layout-Version höher als 1 ist (409 DOCUMENTS_LAYOUT_VERSION_REQUIRED, falls fehlend), und ein veralteter Wert führt zu 409 DOCUMENT_SET_VERSION_CONFLICT. Wenn ein Mandantenadministrator das Paket in Ihrer Benutzeroberfläche neu anordnet, während ein Hintergrundjob ein Feld verschiebt, schlägt der zweite Schreibvorgang mit einem 409-Fehler fehl und die Änderungen von niemandem werden unbemerkt überschrieben.

async function moveField(templateId, fieldId, x, y, attempts = 3) {
  for (let i = 0; i < attempts; i++) {
    const tpl = await fetch(`${API}/templates/${templateId}`, { headers })
      .then((r) => r.json());

    const res = await fetch(`${API}/templates/${templateId}`, {
      method: "PATCH",
      headers,
      body: JSON.stringify({
        field: { id: fieldId, x, y },
        documents_layout_version: tpl.documents_layout_version,
      }),
    });
    if (res.ok) return res.json();

    const err = await res.json();
    if (err.code !== "DOCUMENT_SET_VERSION_CONFLICT") {
      throw new Error(`${err.code}: ${err.error}`);
    }
    // The document set changed between our read and our write. Reload and retry.
  }
  throw new Error("Document set kept changing; giving up");
}

async function moveField(templateId, fieldId, x, y, attempts = 3) {
  for (let i = 0; i < attempts; i++) {
    const tpl = await fetch(`${API}/templates/${templateId}`, { headers })
      .then((r) => r.json());

    const res = await fetch(`${API}/templates/${templateId}`, {
      method: "PATCH",
      headers,
      body: JSON.stringify({
        field: { id: fieldId, x, y },
        documents_layout_version: tpl.documents_layout_version,
      }),
    });
    if (res.ok) return res.json();

    const err = await res.json();
    if (err.code !== "DOCUMENT_SET_VERSION_CONFLICT") {
      throw new Error(`${err.code}: ${err.error}`);
    }
    // The document set changed between our read and our write. Reload and retry.
  }
  throw new Error("Document set kept changing; giving up");
}

async function moveField(templateId, fieldId, x, y, attempts = 3) {
  for (let i = 0; i < attempts; i++) {
    const tpl = await fetch(`${API}/templates/${templateId}`, { headers })
      .then((r) => r.json());

    const res = await fetch(`${API}/templates/${templateId}`, {
      method: "PATCH",
      headers,
      body: JSON.stringify({
        field: { id: fieldId, x, y },
        documents_layout_version: tpl.documents_layout_version,
      }),
    });
    if (res.ok) return res.json();

    const err = await res.json();
    if (err.code !== "DOCUMENT_SET_VERSION_CONFLICT") {
      throw new Error(`${err.code}: ${err.error}`);
    }
    // The document set changed between our read and our write. Reload and retry.
  }
  throw new Error("Document set kept changing; giving up");
}

Signaturanfragen verwenden dieselben /signing-requests/{id}/documents-Routen, solange sie sich noch im Entwurfsstatus befinden. Sobald eine Anfrage gesendet, abgeschlossen, storniert oder abgelehnt wurde, gibt jeder Schreibzugriff auf Dokumente 409 DOCUMENT_SET_LOCKED zurück.

Was sich bei einer bestehenden Integration ändert

Das Release ist rein additiv. Anfragen, die document_ids, document_index oder die /documents-Routen niemals verwenden, verhalten sich genau wie zuvor. Drei Punkte sollten Sie prüfen:

1. Generierte Clients. Wenn Sie einen Client aus der OpenAPI-Spezifikation generieren: document ist jetzt bei POST /templates optional, und das Siegel-Teilnehmer-Schema in Signaturanfrage-Antworten heißt jetzt SealParticipantApi (zuvor SealParticipant).

2. Strikte Fehleranalyse. Wenn Ihr Code unbekannte Fehlercodes abweist, fügen Sie die neuen hinzu. Das Schema MultiDocumentErrorCode in der API-Referenz listet sie alle auf.

3. Vorlagenkopien. POST /templates/{id}/copy wandelt eine Vorlage mit mehreren Dokumenten in eine Vorlage mit einem einzigen, zusammengeführten Dokument um. Feldinhalte und absolute Seitenzahlen bleiben erhalten. Dokumentenspezifische Labels und Positionen werden verworfen; das sollten Sie einplanen, wenn Sie Vorlagen in Kunden-Workspaces kopieren.

Rechtlich ändert sich nichts. Firma.dev ist konform mit dem ESIGN Act, UETA, eIDAS (EES und FES) sowie UK eIDAS, und Unterschriften sind in über 55 Ländern für jedes Dokument im Satz rechtsverbindlich.

Zusammenfassung

Multi-Dokumenten-Signieren ist in der Firma.dev-API für jedes Konto live geschaltet. Laden Sie jede Datei mit POST /documents hoch, übergeben Sie bis zu 20 IDs in document_ids, steuern Sie Anker-Tags mit document_index an und laden Sie jedes Dokument individuell versiegelt mit eigenem document_only_hash herunter. Vorlagen können dieselben Sätze verwalten und einzelne Dateien aktualisieren, wobei documents_layout_version vor gleichzeitigen Bearbeitungen schützt. Das gesamte Paket kostet einen Credit, 0,049 € (~5¢ USD). Alle Details finden Sie im API-Changelog.

Starten Sie jetzt kostenlos mit Firma.dev – keine Kreditkarte erforderlich.