Envoi d’une demande de signature

Ce guide couvre la création d’une demande de signature, l’ajout d’un modèle ou d’un document, et l’invitation des destinataires à signer.

Créer vs. créer et envoyer

POST /signing-requests crée uniquement un brouillon - cela n’envoie jamais d’email, quels que soient les paramètres que vous transmettez. Pour notifier immédiatement les destinataires, utilisez plutôt POST /signing-requests/create-and-send, ou appelez .../send sur le brouillon par la suite. C’est la cause la plus fréquente des signalements « j’ai créé une demande de signature mais rien n’a été envoyé ».

Firma propose deux façons de démarrer une demande de signature, et choisir la mauvaise est l’erreur d’intégration la plus courante :

	`POST /signing-requests` (création)	`POST /signing-requests/create-and-send`
Résultat	Un brouillon (`status: "draft"`). Rien n’est envoyé.	La demande est créée et envoyée, de manière atomique, en un seul appel.
Destinataires notifiés ?	Jamais - quel que soit `send_signing_email` ou tout autre paramètre.	Par défaut, oui. Voir `send_signing_email` ci-dessous.
Crédit facturé / `sent_on` défini ?	Non	Oui, immédiatement.
Toujours modifiable via PATCH/PUT ?	Oui, jusqu’à ce que vous appeliez `/send`	Non - la demande est déjà dans un état envoyé.
Idéal pour	Un workflow de type brouillon puis édition : construire la demande, ajuster les destinataires ou les champs, la faire relire en interne, puis l’envoyer une fois prête.	Un appel envoyer et oublier lorsque vous avez déjà tout ce dont vous avez besoin.

Utilisez create lorsque votre workflow nécessite une étape de relecture ou d’édition avant qu’un destinataire ne soit atteint. Utilisez create-and-send lorsque vous voulez que la demande soit active et les destinataires notifiés en un seul appel.

Le paramètre `send_signing_email`

Ce paramètre se trouve dans settings.send_signing_email, mais il signifie quelque chose de différent selon le endpoint que vous appelez :

Endpoint	Effet de `send_signing_email: false`
`POST /signing-requests` (création)	Aucun. Ce endpoint n’envoie jamais d’email de lui-même, donc le paramètre est simplement stocké pour plus tard - il ne prend effet qu’une fois le brouillon réellement envoyé.
`POST /signing-requests/create-and-send`	La demande est quand même créée et envoyée : le crédit est facturé, `sent_on` est défini, le webhook `signing_request.sent` se déclenche, et le lien de signature est actif. Seul l’email de notification au destinataire est supprimé.

send_signing_email: false sur create-and-send n’est pas un brouillon silencieux - c’est une demande de signature entièrement envoyée et facturée, sans email associé. Utilisez-le lorsque vous prévoyez de transmettre vous-même le lien de signature (en l’intégrant, ou en envoyant votre propre notification). Si vous voulez quelque chose que vous puissiez encore annuler ou modifier avant qu’il ne devienne définitif, utilisez plutôt create (le endpoint de brouillon).

Le paramètre `allow_presigning_download`

Contrôle si les destinataires peuvent télécharger le document non signé avant d’avoir terminé leur part du processus de signature. Il se comporte de la même manière sur les deux endpoints :

Si vous le définissez explicitement dans settings, cette valeur est stockée sur la demande de signature.
Si vous l’omettez, il se résout au moment de la consultation/du téléchargement via une chaîne d’héritage : demande de signature → espace de travail → paramètre de l’entreprise, avec comme valeur par défaut non autorisé si aucun de ces niveaux n’est défini.
Lors de la création à partir d’un modèle et en l’omettant, la demande hérite de la propre valeur allow_presigning_download du modèle.

Le schéma OpenAPI public de create-and-send ne liste pas actuellement allow_presigning_download dans son objet settings, mais le endpoint l’accepte et l’applique de façon identique à POST /signing-requests.

Étapes

Créez ou sélectionnez un modèle
Créez une demande de signature référençant le modèle
Ajoutez des destinataires avec les informations requises (prénom, nom, email)
Ajoutez éventuellement des champs de formulaire avec un positionnement basé sur des pourcentages
Envoyez la demande par email ou intégrez la vue de signature

Schéma du destinataire (champs requis)

Les destinataires nécessitent first_name et last_name comme champs distincts - il n’existe pas de champ name unique.

Chaque destinataire doit inclure :

first_name (requis) - Prénom du destinataire
last_name (optionnel) - Nom du destinataire (requis uniquement lors de la création via POST /signing-requests avec un document brut)
email (requis) - Adresse email (create avertit en cas de format invalide ; create-and-send et /send le rejettent)
designation (requis) - Rôle : "Signer", "CC", ou "Approver". Les approbateurs examinent et approuvent le document (sans signature) via les types de champs approval_* ci-dessous
order (optionnel) - Ordre de signature pour les workflows séquentiels

Champs optionnels :

phone_number, street_address, city, state_province, postal_code, country, title, company
custom_fields - Objet avec des paires clé-valeur personnalisées

Créer une demande de signature à partir d’un modèle (API)

Endpoint : POST /signing-requests

Exemple curl (création d’une demande à partir d’un modèle) :

curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "template_id": "tmpl_123",
    "name": "NDA - Acme Corp",
    "recipients": [
      { 
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'

Une réponse réussie (201) renvoie une ressource Document incluant id (le signing_request_id) et document_url le cas échéant.

Créer une demande de signature (exemple serveur) - Node (fetch)

const fetch = require('node-fetch')

async function createFromTemplate(templateId) {
  const resp = 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({
      template_id: templateId,
      name: 'NDA - Acme Corp',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer',
          order: 1
        }
      ]
    })
  })
  if (!resp.ok) throw new Error('failed to create')
  const body = await resp.json()
  return body // contient id, document_url, recipients, etc.
}

Créer une demande de signature (exemple serveur) - Python (requests)

import os
import requests

def create_from_template(template_id):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/signing-requests'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={
        'template_id': template_id,
        'name': 'NDA - Acme Corp',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer',
                'order': 1
            }
        ]
    })
    resp.raise_for_status()
    return resp.json()

Créer une demande de signature à partir d’un document

Au lieu d’utiliser un modèle, vous pouvez créer une demande de signature en téléversant directement un document PDF ou DOCX. Choisissez la méthode en fonction de la taille de votre fichier :

Le base64 en ligne (document) fonctionne pour les petits fichiers, mais l’envoi d’un document volumineux de cette façon peut échouer avec une erreur 502 avant même que votre requête n’atteigne la validation applicative - la charge utile atteint une limite de taille au niveau de la plateforme, et non une erreur que vous pouvez intercepter et retenter proprement. Si un document approche les 5 Mo, utilisez plutôt le flux de téléversement en deux étapes (document_id) décrit ci-dessous plutôt que le base64 en ligne, même si cela demande d’écrire plus de code.

Petits fichiers (moins de 5 Mo)
Fichiers volumineux (jusqu'à 50 Mo)

Pour les documents de moins de 5 Mo, incluez le fichier encodé en base64 directement dans le corps de la requête :

curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document": "JVBERi0xLjQK... (base64-encoded PDF)",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'

Pour les documents de plus de 5 Mo, utilisez le flux de téléversement en deux étapes :Étape 1 : demander une URL de téléversement

curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/documents" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "file_name": "contract.pdf",
    "file_size": 15000000,
    "content_type": "application/pdf"
  }'

Réponse :

{
  "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
  "upload_url": "https://...",
  "upload_token": "eyJ...",
  "expires_in": 3600
}

Étape 2 : téléverser le fichier

curl -X PUT "UPLOAD_URL_FROM_STEP_1" \
 -H "Content-Type: application/pdf" \
 --data-binary @contract.pdf

Étape 3 : créer la demande de signature

curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ]
  }'

L’URL de téléversement expire après 1 heure et ne peut être utilisée qu’une seule fois. Chaque document_id ne peut être utilisé que dans une seule demande de signature.

Vous devez fournir exactement un seul des paramètres document, document_id, ou template_id. Ils sont mutuellement exclusifs.

Ajout de champs de formulaire (positionnement basé sur des pourcentages)

Important : toutes les coordonnées de position des champs (x, y, width, height) doivent être des pourcentages (0-100) relatifs aux dimensions de la page, et non des pixels. Le champ page_number est requis.

Vous voulez qu’un champ affiche une valeur avant que le signataire ne le touche - une valeur fixe que vous connaissez déjà, ou les propres données de profil du destinataire ? Consultez le guide de préremplissage des champs. variable_name seul ne fait pas cela.

Lors de la création directe d’une demande de signature (POST /signing-requests) ou de sa mise à jour, vous pouvez ajouter des champs de formulaire :

Exemple de positionnement de champ

{
  "name": "Contract with Fields",
  "recipients": [
    {
      "first_name": "Bob",
      "last_name": "Smith",
      "email": "bob@example.com",
      "designation": "Signer",
      "order": 1
    }
  ],
  "fields": [
    {
      "type": "signature",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "page_number": 1,
      "position": {
        "x": 10,
        "y": 80,
        "width": 30,
        "height": 8
      }
    },
    {
      "type": "text",
      "required": true,
      "recipient_id": "recipient_uuid_here",
      "variable_name": "company_name",
      "page_number": 1,
      "position": {
        "x": 50,
        "y": 20,
        "width": 40,
        "height": 5
      }
    },
    {
      "type": "date",
      "required": true,
      "page_number": 1,
      "date_signing_default": true,
      "position": {
        "x": 10,
        "y": 90,
        "width": 20,
        "height": 4
      }
    }
  ]
}

Types de champs

signature - Champ de signature
text - Saisie de texte sur une seule ligne
date - Sélecteur de date
checkbox - Case à cocher
dropdown - Sélecteur déroulant (nécessite dropdown_options)
initial - Champ d’initiales (accepte également initials comme alias)
approval_signature - Tampon APPROVED (Approbateur uniquement)
approval_checkmark - Coche d’approbation (Approbateur uniquement)
approval_date - Date d’approbation (Approbateur uniquement)

Les types de champs approval_* ne peuvent être attribués qu’à un destinataire dont la designation est "Approver" (en attribuer un à un Signataire renvoie une erreur 400). Leur valeur est établie côté serveur lorsque l’approbateur termine son examen, vous n’avez donc pas à soumettre de valeur pour eux, et le tampon d’approbation est apposé sur le certificat d’achèvement.

Directives de positionnement

Le système de coordonnées utilise des pourcentages pour une mise à l’échelle responsive :

x : 0 (bord gauche) à 100 (bord droit)
y : 0 (bord supérieur) à 100 (bord inférieur)
width : pourcentage de la largeur de la page (par ex., 30 = 30 % de largeur)
height : pourcentage de la hauteur de la page (par ex., 8 = 8 % de hauteur)

Pour une page US Letter (8,5” × 11”), utilisez ces conversions approximatives :

1 pouce ≈ 11,76 % de largeur
1 pouce ≈ 9,09 % de hauteur

Mise à jour des demandes de signature

Avant qu’une demande de signature ne soit envoyée, vous pouvez mettre à jour ses détails via l’API. L’API propose deux méthodes :

Impossible de mettre à jour après l’envoi : une fois qu’une demande de signature est envoyée, elle ne peut plus être modifiée. Les mises à jour ne fonctionnent que pour les demandes ayant le statut not_sent.

Mise à jour complète (PUT)

Utilisez comprehensive-update-signing-request pour les mises à jour complexes impliquant plusieurs sections. Quand l’utiliser :

Mise à jour de plusieurs destinataires à la fois
Suppression de destinataires (avec réattribution/suppression des champs)
Mise à jour des champs et des rappels ensemble
Effectuer des modifications coordonnées sur plusieurs sections

Structure : toutes les sections sont optionnelles, mais au moins une doit être fournie :

signing_request_properties - Mettre à jour le nom, la description, le document, l’expiration, les paramètres
recipients - Upsert des destinataires (inclure id pour mettre à jour, omettre pour créer)
deleted_recipients - Supprimer des destinataires avec field_action (supprimer ou réattribuer les champs)
fields - Upsert des champs (inclure id pour mettre à jour, omettre pour créer)
reminders - Upsert des rappels (inclure id pour mettre à jour, omettre pour créer)

Exigences :

✅ Peut mettre à jour plusieurs sections en une seule requête
✅ Prend en charge la suppression de destinataires avec gestion des champs
✅ Ne fonctionne que si la demande n’a pas encore été envoyée

Exemple (Node.js) :

const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    signing_request_properties: {
      name: 'Updated Contract Name',
      expiration_hours: 72
    },
    recipients: [
      {
        id: 'rec1-e89b-12d3-a456-426614174000', // Inclure id pour mettre à jour un destinataire existant
        first_name: 'Jane',
        last_name: 'Smith',
        email: 'jane@example.com',
        designation: 'Signer',
        order: 1
      },
      {
        // Omettre id pour créer un nouveau destinataire
        first_name: 'Bob',
        last_name: 'Johnson',
        email: 'bob@example.com',
        designation: 'CC',
        order: 2
      }
    ],
    fields: [
      {
        id: 'field1-e89b-12d3-a456-426614174000',
        type: 'signature',
        position: { x: 15, y: 85, width: 30, height: 10 },
        page_number: 1,
        required: true,
        recipient_id: 'rec1-e89b-12d3-a456-426614174000'
      }
    ]
  })
});

const updatedRequest = await response.json();

Mise à jour partielle (PATCH)

Utilisez partially-update-signing-request pour mettre à jour des propriétés spécifiques ou un seul destinataire. Quand l’utiliser :

Mise à jour du nom, de la description ou des paramètres
Ajout ou mise à jour d’un destinataire à la fois
Effectuer des modifications ciblées sans affecter les autres données

Important : impossible de mettre à jour à la fois les propriétés ET un destinataire dans la même requête. Choisissez l’un ou l’autre :

Mettre à jour uniquement les propriétés (name, description, document, expiration_hours, settings)
OU mettre à jour/créer un seul destinataire

Avantages :

✅ N’envoyez que les champs que vous souhaitez modifier
✅ Plus efficace pour les petits changements
✅ Les autres champs restent inchangés
✅ Plus sûr pour les modifications concurrentes

Exemple (Node.js) :

// Mettre à jour un seul destinataire
const response = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequestId}`, {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    recipient: {
      id: 'rec123-e89b-12d3-a456-426614174000', // Inclure id pour mettre à jour un destinataire existant
      first_name: 'John',
      last_name: 'Updated',
      email: 'john.updated@example.com',
      designation: 'Signer',
      order: 1
    }
  })
});

const updatedRequest = await response.json();

Exemple (Python) :

import requests
import os

# Mettre à jour uniquement les propriétés (nom et expiration)
response = requests.patch(
    f"https://api.firma.dev/functions/v1/signing-request-api/signing-requests/{signing_request_id}",
    headers={
        "Authorization": f"Bearer {os.getenv('FIRMA_API_KEY')}",
        "Content-Type": "application/json"
    },
    json={
        "name": "Updated Contract Name",
        "expiration_hours": 72
    }
)

updated_request = response.json()

Choisir entre PUT et PATCH

Scénario	Utiliser	Raison
Reconstruction complète de la demande de signature	PUT	Remplacement complet avec toutes les sections (properties, recipients, fields, reminders)
Mise à jour du nom ou des paramètres uniquement	PATCH	Plus efficace, préserve les destinataires et les champs
Ajout/mise à jour d’un destinataire	PATCH	Mode destinataire unique, les autres destinataires restent inchangés
Mise à jour de plusieurs destinataires	PUT	Peut upserter plusieurs destinataires en une seule requête
Suppression de destinataires avec réattribution des champs	PUT	Prend en charge deleted_recipients avec field_action
Modification du document et de tous les champs	PUT	Changements structurels majeurs
Mise à jour des champs personnalisés	PATCH	Préserve la demande de signature principale
Remplacement de tous les destinataires	PUT	Approche table rase

Important : les deux méthodes de mise à jour ne fonctionnent qu’avant l’envoi de la demande de signature. Une fois envoyée, la demande de signature devient immuable pour empêcher toute altération des workflows de signature actifs.

Bonnes pratiques :

Mettez à jour les demandes de signature avant d’appeler /send
Validez les données des destinataires avant de mettre à jour
Utilisez PATCH pour les modifications incrémentales
Implémentez une logique de nouvelle tentative avec un backoff exponentiel

Envoi (invitations par email)

Une fois que vous avez un ID de demande de signature (et avez effectué les mises à jour nécessaires), appelez POST /signing-requests/{signing_request_id}/send pour envoyer des emails à tous les destinataires.

Exemple

curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/sr_abc123/send" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "custom_message": "Please sign this NDA by EOD." }'

L’endpoint /send vérifie que tous les destinataires disposent des informations requises (first_name et email - last_name est optionnel) et que tous les champs préremplis disposent des données correspondantes du destinataire.

Intégration de la vue de signature

Pour intégrer l’expérience de signature dans votre propre application, récupérez l’id du destinataire depuis GET /signing-requests/{id}/users et construisez l’URL de signature :

https://app.firma.dev/signing/{recipient_id}

Affichez cette URL dans un iframe. Pour la configuration complète de l’intégration - y compris les événements postMessage, le dimensionnement de l’iframe et les autorisations caméra/presse-papiers - consultez le guide Signature intégrable.

Cas particuliers et astuces

Ordre de signature : assurez-vous que les destinataires ont des valeurs order séquentielles (1, 2, 3…) pour les workflows de signature séquentiels
Piste d’audit : téléchargez la piste d’audit via GET /signing-requests/{id}/tracking pour voir toutes les actions des utilisateurs
Téléchargement du PDF terminé : utilisez GET /signing-requests/{id}/download après l’achèvement
Webhooks : abonnez-vous à des événements comme signing_request.completed plutôt que d’effectuer du polling (voir le guide Webhooks)

Prochaines étapes

Préremplissez les champs avec les données du destinataire ou des données statiques avant l’envoi
Configurer des webhooks pour recevoir des notifications d’événements en temps réel (60 req/min)
Ajouter des rappels automatisés pour les destinataires en attente
Intégrer l’éditeur de modèles avec authentification JWT (120 req/min)
Configurer les paramètres de l’espace de travail pour des modèles d’email personnalisés (100-200 req/min)
Éditeur de modèles intégrable avec authentification JWT pour des workflows intégrés sécurisés

Pour les workflows de signature séquentiels avec plusieurs signataires, assurez-vous que chaque destinataire a une valeur order séquentielle (1, 2, 3…).
Pour l’audit et la conformité, téléchargez le PDF final via GET /signing-requests/signing_request_id/download après l’achèvement.
Utilisez les webhooks (voir le Guide Webhooks) pour réagir aux événements de signature plutôt que d’effectuer du polling.

Guides de Démarrage

Guides avancés

Envoi d'une demande de signature

Envoi d’une demande de signature

Créer vs. créer et envoyer

Le paramètre `send_signing_email`

Le paramètre `allow_presigning_download`

Étapes

Schéma du destinataire (champs requis)

Créer une demande de signature à partir d’un modèle (API)

Créer une demande de signature (exemple serveur) - Node (fetch)

Créer une demande de signature (exemple serveur) - Python (requests)

Créer une demande de signature à partir d’un document

Ajout de champs de formulaire (positionnement basé sur des pourcentages)

Exemple de positionnement de champ

Types de champs

Directives de positionnement

Mise à jour des demandes de signature

Mise à jour complète (PUT)

Mise à jour partielle (PATCH)

Choisir entre PUT et PATCH

Envoi (invitations par email)

Exemple

Intégration de la vue de signature

Cas particuliers et astuces

Prochaines étapes

​Envoi d’une demande de signature

​Créer vs. créer et envoyer

​Le paramètre send_signing_email

​Le paramètre allow_presigning_download

​Étapes

​Schéma du destinataire (champs requis)

​Créer une demande de signature à partir d’un modèle (API)

​Créer une demande de signature (exemple serveur) - Node (fetch)

​Créer une demande de signature (exemple serveur) - Python (requests)

​Créer une demande de signature à partir d’un document

​Ajout de champs de formulaire (positionnement basé sur des pourcentages)

​Exemple de positionnement de champ

​Types de champs

​Directives de positionnement

​Mise à jour des demandes de signature

​Mise à jour complète (PUT)

​Mise à jour partielle (PATCH)

​Choisir entre PUT et PATCH

​Envoi (invitations par email)

​Exemple

​Intégration de la vue de signature

​Cas particuliers et astuces

​Prochaines étapes

Envoi d’une demande de signature

Créer vs. créer et envoyer

Le paramètre `send_signing_email`

Le paramètre `allow_presigning_download`

Étapes

Schéma du destinataire (champs requis)

Créer une demande de signature à partir d’un modèle (API)

Créer une demande de signature (exemple serveur) - Node (fetch)

Créer une demande de signature (exemple serveur) - Python (requests)

Créer une demande de signature à partir d’un document

Ajout de champs de formulaire (positionnement basé sur des pourcentages)

Exemple de positionnement de champ

Types de champs

Directives de positionnement

Mise à jour des demandes de signature

Mise à jour complète (PUT)

Mise à jour partielle (PATCH)

Choisir entre PUT et PATCH

Envoi (invitations par email)

Exemple

Intégration de la vue de signature

Cas particuliers et astuces

Prochaines étapes