Nouveau sur Firma.dev : signez l'ensemble du dossier en une seule demande, chaque fichier étant scellé individuellement

Un contrat B2B se conclut généralement sur une pile de fichiers : un contrat-cadre de prestations de services, un cahier des charges, un accord de confidentialité et un bon de commande, tous destinés au même client pour la même signature. Depuis la version 1.39.0 de l'API, l'ensemble de ce dossier peut être envoyé sous la forme d'une seule demande de signature Firma.dev, et chaque fichier inclus revient scellé sous forme de document individuel.

La signature multi-documents est disponible pour tous les comptes Firma.dev

C'est une nouveauté, et elle est déjà activée pour tout le monde. Cette version ajoute :

• Un modèle ou une demande de signature peut contenir jusqu'à 20 documents, avec une limite de 100 Mo par ensemble de documents.

• POST /templates, POST /signing-requests et POST /signing-requests/create-and-send acceptent document_ids, une liste de fichiers téléversés dans l'ordre des documents.

• De nouvelles routes /documents permettent d'ajouter, remplacer, renommer, réorganiser, supprimer et télécharger des documents un par un.

• Les balises d'ancrage peuvent cibler un document spécifique grâce à document_index.

• Chaque document d'une demande de signature finalisée se télécharge sous la forme d'un fichier scellé individuellement, doté de son propre hachage SHA-256.

Le journal des modifications date cette version du 12 octobre 2026, et les fonctionnalités multi-documents sont accessibles à toutes les entreprises depuis le 13 octobre 2026. Il n'y a rien à activer ni aucun indicateur à demander.

La tarification ne change pas non plus. Une demande de signature équivaut à un crédit, soit 0,049 € (~5 ¢ USD), qu'elle contienne un document ou vingt. La FAQ de la documentation l'indique clairement : un crédit équivaut à une demande de signature, quel que soit le nombre de signataires ou de documents qu'elle contient. Le modèle reste à l'usage, sans minimum mensuel ni frais par utilisateur.

Ce que nécessitait auparavant un dossier de quatre documents

Jusqu'à cette version, une demande de signature ne contenait qu'un seul document. Envoyer un dossier complet imposait d'écrire du code intermédiaire pour contourner cette limite, et cela ressemblait généralement à ceci :

C'est aux étapes 2 et 4 que les erreurs surviennent. Un client remplace un accord de confidentialité de trois pages par un de deux pages, et tous les champs suivants se retrouvent sur la mauvaise page. Les plages de découpage dérivent de la même façon... et pour une plateforme SaaS dont les propres clients téléversent ces ensembles, le dossier de chaque client locataire est légèrement différent, de sorte que le bogue apparaît client après client.

Avec la v1.39.0, les étapes de fusion, de décalage et de découpage disparaissent. Chaque fichier est envoyé individuellement, suit un flux de signature unique et revient scellé de manière autonome.

Envoyer le dossier avec document_ids

Téléverser chaque fichier avec POST /documents

Chaque document de l'ensemble commence par un téléversement. POST /documents prend un nom de fichier, une taille et un type de contenu, puis renvoie un document_id temporaire ainsi qu'une upload_url pré-signée. Vous effectuez un PUT des octets bruts du fichier vers cette URL. Il y a un téléversement par fichier... un dossier de quatre documents nécessite donc quatre téléversements avant même que la demande de signature ne soit créée.

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;
}

Ce chemin est également celui à utiliser pour les fichiers volumineux. Depuis la v1.40.0, tout corps de requête supérieur à 6 Mio renvoie 413 REQUEST_TOO_LARGE, donc les gros fichiers PDF doivent de toute façon passer par POST /documents. Un seul téléversement peut atteindre 50 Mo (l'ensemble complet étant plafonné à 100 Mo).

Créer et envoyer dans l'ordre des documents

Passez de 1 à 20 identifiants de téléversement dans document_ids, dans l'ordre d'apparition souhaité pour les documents. POST /signing-requests/create-and-send les prend en charge. C'est également le cas de POST /signing-requests, pour un brouillon à envoyer plus tard, et de POST /templates.

Chaque création n'accepte qu'une seule source de documents : document, document_id, document_ids ou template_id. En transmettre plusieurs entraîne l'erreur 400 CONFLICTING_DOCUMENT_SOURCE de la part de l'API. Un identifiant en double renvoie 400 DUPLICATE_DOCUMENT_ID, plus de 20 documents renvoie 400 MAX_DOCUMENTS_EXCEEDED, et un ensemble dépassant 100 Mo renvoie 413 DOCUMENT_SET_TOO_LARGE.

Cibler le bon document avec les balises d'ancrage

Les balises d'ancrage acceptent désormais document_index, c'est-à-dire la position (base 1) du document ciblé dans document_ids. Avec un seul document, ce paramètre est facultatif et vaut 1 par défaut. Avec plusieurs documents, il devient obligatoire ; son omission renvoie 400 ANCHOR_DOCUMENT_REQUIRED. Grâce à lui, le {{SIGN_HERE}} de l'accord de confidentialité reste distinct du {{SIGN_HERE}} du cahier des charges, même si chaque fichier du dossier utilise le même marqueur.

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

Si vous découvrez les balises d'ancrage, le guide pratique des balises d'ancrage détaille les décalages, les occurrences et le dimensionnement.

Chaque document revient scellé de manière autonome

GET /signing-requests/{id} renvoie un tableau documents. Chaque entrée contient document_id, position, label, original_filename et page_count, et pour les demandes de signature, elle inclut également document_only_hash, le SHA-256 du document scellé individuellement une fois le certificat lié (null auparavant).

Pour récupérer un fichier, appelez GET /signing-requests/{id}/documents/{document_id}/download. Cette requête renvoie une URL signée valable pendant 1 heure :

• type=original (valeur par défaut) renvoie le document tel qu'il a été téléversé.

• type=document renvoie le document scellé individuellement une fois le certificat lié. Avant cette étape, la requête renvoie 404 DOCUMENT_SIGNED_NOT_AVAILABLE : traitez ce code comme « pas encore prêt » et réessayez un peu plus tard.

Pour une application SaaS, cela élimine les derniers pans de code de liaison. La boucle ci-dessous enregistre le contrat-cadre signé dans l'enregistrement du contrat, l'accord de confidentialité signé dans celui de l'accord de confidentialité, et ainsi de suite, le hachage de chaque fichier étant stocké à côté. Et puisque position respecte l'ordre fourni dans document_ids, la correspondance avec le dossier que vous avez composé est directe.

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,
    });
  }
}

Si vous souhaitez également télécharger les éléments au niveau de la requête (le PDF contenant uniquement le document et le certificat séparé), ils sont présentés dans l'article sur les téléchargements de PDF scindés. Chaque demande de signature conserve également sa piste d'audit.

Des modèles qui intègrent un ensemble de documents

Un modèle peut également héberger l'ensemble du dossier, ce qui convient parfaitement aux plateformes qui transmettent le même groupe de fichiers à chaque nouveau client. Créez-le avec document_ids via POST /templates, puis gérez chaque fichier sous /templates/{id}/documents :

• POST /templates/{id}/documents ajoute un document à la position position, ou à la fin si la position n'est pas précisée.

• PATCH /templates/{id}/documents/{document_id} remplace le document par un nouveau téléversement (document_id) ou le renomme (label). Transmettez exactement une de ces deux propriétés par appel.

• PUT /templates/{id}/documents/order réorganise l'ensemble. La liste doit énumérer chaque document exactement une fois, faute de quoi l'API renvoie 400 INVALID_DOCUMENT_ORDER.

• DELETE /templates/{id}/documents/{document_id} en supprime un. Le dernier document restant ne peut pas être supprimé.

Un remplacement préserve l'emplacement des champs tant que le nouveau fichier présente le même nombre de pages et que chaque page a les mêmes dimensions à 1 pt près. Dans le cas contraire, vous obtenez 400 PAGE_COUNT_MISMATCH ou 400 DIMENSION_MISMATCH. Ainsi, lorsque le service juridique met à jour l'accord de confidentialité, vous ne remplacez que ce fichier... et les champs du contrat-cadre, du cahier des charges et du bon de commande restent à leur place. La page sur la fonctionnalité de remplacement de document de modèle aborde le sujet plus en détail.

Un contrôle de concurrence est également en place, ce qui s'avère essentiel dans les architectures multi-locataires (deux services, ou deux administrateurs, modifiant le même modèle). Le champ documents_layout_version s'incrémente dès que des documents sont ajoutés, retirés ou réordonnés. Les écritures de champs via PUT et PATCH sur /templates/{id} et /signing-requests/{id} transmettent la valeur obtenue lors de votre dernière lecture. Cette valeur est requise dès qu'il y a plus d'un document ou que la version de mise en page dépasse 1 (409 DOCUMENTS_LAYOUT_VERSION_REQUIRED en cas d'absence), et une valeur obsolète renvoie 409 DOCUMENT_SET_VERSION_CONFLICT. Si un administrateur locataire réorganise le dossier dans votre interface pendant qu'une tâche de fond déplace un champ, la seconde écriture échoue avec un code 409 et aucune modification n'est écrasée à votre insu.

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");
}

Les demandes de signature utilisent les mêmes routes /signing-requests/{id}/documents tant qu'elles sont à l'état de brouillon. Dès qu'une demande est envoyée, terminée, annulée ou refusée, toute écriture sur un document renvoie 409 DOCUMENT_SET_LOCKED.

Les changements apportés à une intégration existante

Cette version est additive. Les requêtes qui n'utilisent jamais document_ids, document_index ni les routes /documents continuent de fonctionner exactement comme avant. Trois points méritent d'être vérifiés :

1. Clients générés. Si vous générez un client à partir de la spécification OpenAPI, document est désormais facultatif sur POST /templates, et le schéma du participant au scellement dans les réponses de demande de signature est désormais nommé SealParticipantApi (au lieu de SealParticipant).

2. Analyse stricte des erreurs. Si votre code rejette les codes d'erreur inconnus, ajoutez les nouveaux. Le schéma MultiDocumentErrorCode dans la référence de l'API les liste tous.

3. Copies de modèles. POST /templates/{id}/copy transforme un modèle multi-documents en un modèle doté d'un seul document fusionné. Le contenu des champs et les numéros de page absolus sont conservés. Les libellés et les positions par document sont supprimés, un élément à anticiper si vous copiez des modèles vers des espaces de travail clients.

Sur le plan juridique, rien ne change. Firma.dev est conforme à la loi ESIGN, à l'UETA, à eIDAS (SES et AES) ainsi qu'à l'eIDAS britannique, et les signatures ont une valeur juridique contraignante dans plus de 55 pays, pour chaque document du dossier.

Résumé

La signature multi-documents est disponible dans l'API Firma.dev pour tous les comptes. Téléversez chaque fichier avec POST /documents, passez jusqu'à 20 identifiants dans document_ids, positionnez les balises d'ancrage avec document_index et téléchargez chaque document scellé individuellement avec son propre document_only_hash. Les modèles peuvent contenir les mêmes ensembles et se mettre à jour un fichier à la fois, documents_layout_version protégeant contre les modifications simultanées. Le dossier complet coûte un crédit, soit 0,049 € (~5 ¢ USD). Tous les détails sont consultables dans le journal des modifications de l'API.

Commencez gratuitement avec Firma.dev, sans carte bancaire.