> ## Documentation Index
> Fetch the complete documentation index at: https://docs.firma.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Mettre à Jour Partiellement une Demande de Signature
> Mettre à jour les propriétés de la demande de signature, un seul destinataire, OU un seul champ. Impossible de mettre à jour plusieurs types d'entités dans une même requête. Impossible de mettre à jour après que la demande de signature a été envoyée, terminée ou annulée.
## OpenAPI
````yaml api-reference/v01.30.00/openapi-v01.30.00.fr.json patch /signing-requests/{id}
openapi: 3.0.3
info:
title: API Partenaire Firma
description: >-
API RESTful pour la signature de documents et la gestion de modèles.
**Authentification** : Tous les endpoints nécessitent une authentification
par clé API via l'en-tête `Authorization`. Utilisez votre clé API
directement sans préfixe (par exemple, `your-api-key`). Le préfixe Bearer
est optionnel mais pas obligatoire.
**Fonctionnalités de sécurité** :
- Validation des entrées avec des schémas Zod incluant des messages d'erreur
détaillés au niveau des champs
- Jetons JWT signés RSA-256 pour l'accès aux modèles intégrés
**Limitation de débit** : Les limites de débit sont hiérarchisées selon le
type d'opération :
- Opérations de lecture (GET) : 200 requêtes par minute
- Opérations d'écriture (POST/PUT/PATCH/DELETE) : 120 requêtes par minute
- Opérations CRUD sur les webhooks : 60 requêtes par minute
- Test de webhook : 10 requêtes par minute
- Régénération/expiration de clé API : 1 requête par minute
- Rotation du secret de webhook : 1 requête par minute
Lorsque les limites de débit sont dépassées, l'API renvoie une réponse `429
Too Many Requests` avec les en-têtes suivants :
- `X-RateLimit-Limit` : Nombre maximal de requêtes par minute pour cet
endpoint
- `X-RateLimit-Remaining` : Requêtes restantes dans la fenêtre actuelle
- `X-RateLimit-Reset` : Horodatage Unix de la réinitialisation de la limite
- `Retry-After` : Secondes à attendre avant de pouvoir réessayer
**Gestion des erreurs** : Toutes les erreurs renvoient des réponses JSON
structurées avec `error` (message lisible par un humain), `code`
(identifiant lisible par une machine) et `details` (erreurs de validation au
niveau des champs, le cas échéant).
**Intégration de l'Éditeur de Modèles intégré** : L'Éditeur de Modèles Firma
peut être intégré dans votre application à l'aide d'une bibliothèque
JavaScript autonome.
```html
```
version: 01.30.00
contact:
name: API Support
url: https://firma.com/support
servers:
- url: https://api.firma.dev/functions/v1/signing-request-api
description: API de Production - Recommandée (Actuelle)
- url: https://api.firma.dev/api/v1
description: API de Production - Prévue
security:
- ApiKeyAuth: []
tags:
- name: Company
description: Informations et paramètres de l'entreprise
- name: Workspaces
description: Opérations de gestion des Espaces de Travail
- name: Templates
description: Opérations de gestion des Modèles
- name: Signing Requests
description: Opérations de Demande de Signature de documents
- name: Custom Fields
description: >-
Gestion des définitions de champs personnalisés pour les espaces de
travail, modèles et demandes de signature
- name: Webhooks
description: Configuration et gestion des webhooks
- name: JWT Management
description: Génération et révocation de jetons JWT pour les modèles intégrés
- name: Workspace Settings
description: Configuration et paramètres de l'espace de travail
- name: Email Domains
description: >-
Configuration et vérification de domaine e-mail pour l'envoi d'e-mails de
demande de signature depuis des domaines personnalisés
- name: Email Templates
description: >-
Gestion des modèles d'e-mail pour la personnalisation des notifications de
demande de signature au niveau de l'espace de travail et de l'entreprise
- name: Signer Terms
description: >-
Conditions d'utilisation / déclarations de consentement personnalisées
pour le signataire, au niveau de l'entreprise avec des surcharges par
espace de travail et par langue
paths:
/signing-requests/{id}:
patch:
tags:
- Signing Requests
summary: Mettre à Jour Partiellement une Demande de Signature
description: >-
Mettre à jour les propriétés de la demande de signature, un seul
destinataire, OU un seul champ. Impossible de mettre à jour plusieurs
types d'entités dans une même requête. Impossible de mettre à jour après
que la demande de signature a été envoyée, terminée ou annulée.
operationId: patchSigningRequest
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
description: ID de la demande de signature
requestBody:
required: true
content:
application/json:
schema:
oneOf:
- type: object
description: >-
Mettre à jour uniquement les propriétés de la demande de
signature
properties:
name:
type: string
maxLength: 255
description: Nouveau nom pour la demande de signature
description:
type: string
description: Nouvelle description
document:
type: string
format: byte
description: >-
Remplace le document par un nouveau PDF encodé en
base64. Le nombre de pages est extrait automatiquement.
expiration_hours:
type: integer
minimum: 1
description: Nouvelles heures d'expiration
settings:
$ref: '#/components/schemas/SigningRequestSettings'
description: Mettre à jour les paramètres
- type: object
required:
- recipient
description: Créer ou mettre à jour un seul destinataire
properties:
recipient:
$ref: '#/components/schemas/Recipient'
description: >-
Destinataire à créer (omettre id) ou à mettre à jour
(inclure id). Lors de la mise à jour de first_name ou
last_name, le champ name est automatiquement reconstruit
à partir des valeurs existantes en base de données pour
tout champ non fourni. Résultat : 'First Last' si les
deux existent, 'First' si seul first_name est présent.
- type: object
required:
- field
description: Créer ou mettre à jour un seul champ
properties:
field:
type: object
properties:
id:
type: string
format: uuid
description: >-
Inclure pour mettre à jour un champ existant,
omettre pour en créer un nouveau
type:
type: string
enum:
- text
- signature
- date
- checkbox
- initial
- initials
- dropdown
- radio_buttons
- textarea
- text_area
- url
- file
- stamp
- approval_signature
- approval_checkmark
- approval_date
description: >-
Type de champ. Accepte 'initial' ou 'initials',
'textarea' ou 'text_area'. Requis pour les nouveaux
champs. Les champs url sont automatiquement en
lecture seule. Les champs file permettent aux
signataires de téléverser des pièces jointes
(images/PDF). Les champs stamp affichent une image
préconfigurée.
position:
type: object
properties:
x:
type: number
description: Position X sur le document
'y':
type: number
description: Position Y sur le document
width:
type: number
description: Largeur du champ
height:
type: number
description: Hauteur du champ
description: >-
Objet position. Toutes les propriétés sont requises
pour les nouveaux champs.
page_number:
type: integer
minimum: 1
description: >-
Numéro de page (indexé à partir de 1). Requis pour
les nouveaux champs.
required:
type: boolean
description: Indique si le champ est requis
recipient_id:
type: string
format: uuid
nullable: true
description: ID du destinataire auquel assigner le champ
variable_name:
type: string
description: >-
Nom de variable pour le mappage des données
préremplies
variable_defined_name:
type: string
maxLength: 100
nullable: true
description: >-
Nom lisible et personnalisé de la définition du
champ. Peut être utilisé comme alternative à
variable_name pour cibler des champs lors de la
création à partir d'un modèle.
dropdown_options:
description: Options pour les champs de type liste déroulante
oneOf:
- type: array
items:
type: string
- type: object
format_rules:
type: object
description: >-
Règles de format (ex. format de date, urlDisplayText
pour les champs url, acceptedFileTypes pour les
champs file)
validation_rules:
type: object
description: Règles de validation pour le champ
multi_group_id:
type: string
format: uuid
description: ID de groupe pour les groupes de boutons radio
date_default:
type: string
description: Valeur de date par défaut
date_signing_default:
type: boolean
description: >-
Pour les champs de type date, utiliser la date de
signature comme valeur par défaut
read_only:
type: boolean
description: >-
Indique si le champ est en lecture seule
(automatiquement vrai pour les champs url)
read_only_value:
type: string
description: >-
Valeur statique pour les champs en lecture seule.
Pour les champs url, il s'agit de l'URL vers
laquelle pointer le lien.
final_value:
type: string
description: >-
Valeur finale du champ (pour les champs préremplis
en lecture seule)
examples:
update-properties:
summary: Mettre à jour les propriétés
value:
name: Updated Contract Name
expiration_hours: 72
update-recipient:
summary: Mettre à jour un seul destinataire
value:
recipient:
id: rec123-e89b-12d3-a456-426614174000
first_name: John
last_name: Smith
email: john.smith@example.com
designation: Signer
order: 1
add-recipient:
summary: Ajouter un nouveau destinataire
value:
recipient:
first_name: Jane
last_name: Doe
email: jane@example.com
designation: Signer
order: 2
create-url-field:
summary: Créer un champ URL
value:
field:
type: url
position:
x: 100
'y': 200
width: 150
height: 30
page_number: 1
read_only_value: https://example.com/terms
format_rules:
urlDisplayText: View Terms & Conditions
create-file-field:
summary: Créer un champ de téléversement de fichier
value:
field:
type: file
position:
x: 100
'y': 300
width: 200
height: 40
page_number: 1
required: true
format_rules:
acceptedFileTypes: image_and_pdf
update-field:
summary: Mettre à jour la position d'un champ existant
value:
field:
id: field123-e89b-12d3-a456-426614174000
position:
x: 120
'y': 220
responses:
'200':
description: >-
Demande de signature mise à jour avec succès. La forme de la réponse
dépend de ce qui a été mis à jour : une mise à jour des propriétés
renvoie {id, name, template_description, document_url,
expiration_hours} ; une mise à jour de destinataire renvoie l'objet
destinataire complet ; une mise à jour de champ renvoie l'objet
champ complet. La réponse peut inclure un champ 'warning' pour les
avertissements de validation de format d'email (non bloquant).
headers:
X-RateLimit-Limit:
schema:
type: integer
description: 'Limite de débit : 120 requêtes par minute'
X-RateLimit-Remaining:
schema:
type: integer
X-RateLimit-Reset:
schema:
type: integer
content:
application/json:
schema:
oneOf:
- type: object
description: Réponse lors de la mise à jour des propriétés
properties:
id:
type: string
format: uuid
name:
type: string
template_description:
type: string
nullable: true
document_url:
type: string
format: uri
expiration_hours:
type: integer
- type: object
description: Réponse lors de la mise à jour/création d'un destinataire
- type: object
description: Réponse lors de la mise à jour/création d'un champ
'400':
description: >-
Requête invalide - Impossible de mettre à jour à la fois les
propriétés et le destinataire dans la même requête, ou la demande de
signature a déjà été envoyée/complétée/annulée
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
cannot-update-sent:
value:
error: Cannot update signing request
message: >-
Signing request has already been sent and cannot be
modified
mixed-update:
value:
error: Invalid request
message: >-
Cannot update both properties and recipient in the same
request
'401':
$ref: '#/components/responses/UnauthorizedError'
'404':
$ref: '#/components/responses/NotFoundError'
'429':
$ref: '#/components/responses/RateLimitError'
security:
- ApiKeyAuth: []
x-codeSamples:
- lang: TypeScript
label: '@firma-dev/sdk'
source: |-
import { FirmaClient } from "@firma-dev/sdk";
const firma = new FirmaClient({ apiKey: "YOUR_API_KEY" });
const response = await firma.signingRequests.patchSigningRequest({
id: "id",
body: {
name: "Updated Contract Name",
expiration_hours: 72
}
});
console.log(response);
components:
schemas:
SigningRequestSettings:
type: object
description: >-
Paramètres renvoyés par les endpoints de liste et de détail des demandes
de signature. Les modèles utilisent le schéma TemplateSettings (sans
champs d'identité).
properties:
allow_download:
type: boolean
description: Indique si les destinataires peuvent télécharger le document
default: true
attach_pdf_on_finish:
type: boolean
description: Indique s'il faut joindre le PDF une fois la signature terminée
default: true
allow_editing_before_sending:
type: boolean
description: Indique si la demande de signature peut être modifiée avant l'envoi
default: false
use_signing_order:
type: boolean
description: >-
Indique si l'ordre de signature est imposé entre les destinataires.
Quand c'est vrai, les signataires reçoivent le document dans l'ordre
défini par leur order. Quand c'est faux, tous les signataires
reçoivent le document simultanément.
default: true
hand_drawn_only:
type: boolean
description: >-
Lorsque cette option est activée, les signataires ne peuvent que
dessiner leur signature à la main et ne peuvent pas utiliser de
signatures dactylographiées
default: false
send_signing_email:
type: boolean
description: >-
Indique s'il faut envoyer des e-mails de notification de demande de
signature aux signataires
default: true
send_finish_email:
type: boolean
description: >-
Indique s'il faut envoyer un e-mail de fin lorsque tous les
signataires ont terminé
default: true
send_expiration_email:
type: boolean
description: >-
Indique s'il faut envoyer un e-mail de notification d'expiration
quand la demande expire
default: true
send_cancellation_email:
type: boolean
description: >-
Indique s'il faut envoyer un e-mail de notification d'annulation
quand la demande est annulée
default: true
require_otp_verification:
type: boolean
nullable: true
description: >-
Indique si les signataires doivent vérifier leur e-mail avec un code
à usage unique avant d'accéder au document. null = hérite du
paramètre de l'espace de travail/de l'entreprise.
default: null
disable_guided_navigation:
type: boolean
nullable: true
description: >-
Désactive le défilement automatique vers le prochain champ requis
pendant la signature. Hérite de l'espace de travail ou de
l'entreprise si non défini.
allow_presigning_download:
type: boolean
nullable: true
description: >-
Permet aux signataires de télécharger le document original avant de
signer. Hérite du paramètre de l'espace de travail ou de
l'entreprise quand null.
show_qr_code:
type: boolean
nullable: true
description: >-
Affiche un QR code sur la page de signature qui permet aux
signataires de continuer sur leur téléphone. Hérite du paramètre de
l'espace de travail ou de l'entreprise quand null.
identity_editable_fields:
type: array
nullable: true
items:
type: string
description: >-
Champs d'identité que les signataires peuvent modifier avant de
signer (par exemple ["name", "company"]). null = désactivé. Quand
c'est défini, une boîte de dialogue de confirmation permet aux
signataires de modifier les champs spécifiés.
notify_identity_change_email:
type: boolean
default: false
description: >-
Envoie une notification par e-mail quand un signataire modifie son
identité.
Recipient:
type: object
required:
- first_name
- email
- designation
description: >-
Schéma Destinataire avec comportements de construction automatique et de
mapping. **Champ name** : Construit automatiquement à partir de
first_name et last_name ('Prénom Nom' si les deux sont présents, sinon
'Prénom'). Les valeurs manuelles du nom sont écrasées. **Attribution de
l'ordre** : TOUS les destinataires DOIVENT avoir une valeur order
explicite. L'ordre détermine la séquence de signature, qui est toujours
imposée. Les destinataires doivent signer dans l'ordre, les numéros les
plus bas signant en premier. **Champs personnalisés** : Prend en charge
à la fois la structure plate (par exemple, company_name à la racine) et
la structure imbriquée (objet custom_fields). Les deux formats sont
normalisés en interne. **Mapping des champs de modèle** : Lors de la
création à partir d'un modèle avec des destinataires personnalisés,
utilisez template_user_id ou order pour faire correspondre les
utilisateurs du modèle. Seules les informations utilisateur (nom,
e-mail, téléphone, etc.) peuvent être mises à jour - order et
designation sont hérités du modèle. **IDs temporaires** : Pour la
création basée sur un document, utilisez des IDs temporaires (format :
'temp_1', 'temp_2', etc.) pour référencer les destinataires dans les
champs et les rappels avant leur création. **Destinataires en copie
(CC)** : Les destinataires en copie reçoivent une copie terminée mais ne
peuvent ni signer ni se voir attribuer de champs. Au moins un Signataire
est requis.
properties:
id:
type: string
description: >-
Identifiant unique. Pour les mises à jour : utilisez l'UUID
existant. Pour la création basée sur un document : utilisez
éventuellement un ID temporaire (format : 'temp_1', 'temp_2', etc.)
pour référencer les destinataires dans les champs et les rappels
avant la création. Les IDs temporaires sont automatiquement résolus
en UUID réels dans la réponse.
_temp_id:
type: string
description: >-
Identifiant temporaire pour les nouveaux destinataires dans les
requêtes PUT (mise à jour complète) (par exemple, 'temp_1').
Utilisez-le lors de la création de nouveaux destinataires en même
temps que des destinataires existants dans des mises à jour
complètes. Doit commencer par 'temp_' et être unique au sein de la
requête. Non utilisé pour les requêtes POST (création) - utilisez
plutôt le champ 'id'.
template_user_id:
type: string
format: uuid
description: >-
Lors de la création à partir d'un modèle, l'ID de l'utilisateur du
modèle à mettre à jour. Si fourni, les données de ce destinataire
mettront à jour l'utilisateur du modèle correspondant. Si non
fourni, la correspondance se fait par ordre. Seules les infos
utilisateur (nom, email, téléphone, adresse, titre, entreprise)
peuvent être mises à jour - l'ordre et la désignation sont toujours
hérités du modèle.
first_name:
type: string
maxLength: 100
description: Prénom du destinataire
last_name:
type: string
maxLength: 100
description: >-
Nom de famille du destinataire (optionnel, mais requis si vous
utilisez les variables prédéfinies full_name ou last_name)
email:
type: string
format: email
maxLength: 255
description: Adresse email du destinataire
designation:
type: string
enum:
- Signer
- Approver
- CC
description: >-
Rôle du destinataire. Signataire signe le document, Approbateur
approuve avec des champs d'approbation, CC reçoit une copie une fois
terminé.
order:
type: integer
minimum: 1
description: >-
Numéro de séquence de signature. Les destinataires doivent signer
dans l'ordre, les numéros les plus bas signant en premier. Ce champ
est requis pour tous les destinataires.
phone_number:
type: string
maxLength: 50
nullable: true
description: Numéro de téléphone du destinataire
street_address:
type: string
maxLength: 255
nullable: true
description: Adresse postale
city:
type: string
maxLength: 100
nullable: true
description: Ville
state_province:
type: string
maxLength: 100
nullable: true
description: État ou province
postal_code:
type: string
maxLength: 20
nullable: true
description: Code postal
country:
type: string
maxLength: 100
nullable: true
description: Pays
title:
type: string
maxLength: 100
nullable: true
description: Titre du poste
company:
type: string
maxLength: 255
nullable: true
description: Nom de l'entreprise
custom_fields:
type: object
additionalProperties: true
description: >-
Paires clé-valeur personnalisées pour des données supplémentaires
sur le destinataire
Error:
type: object
properties:
error:
type: string
description: Message d'erreur lisible par un humain
message:
type: string
description: Description détaillée de l'erreur
details:
type: object
description: Détails d'erreur supplémentaires
additionalProperties: true
required:
- error
responses:
UnauthorizedError:
description: Non Autorisé - Clé API invalide ou manquante
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: Unauthorized
message: Invalid API key
NotFoundError:
description: Non Trouvé - La ressource n'existe pas
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: Not Found
message: The requested resource was not found
RateLimitError:
description: Trop de requêtes - Limite de débit dépassée
headers:
X-RateLimit-Limit:
schema:
type: integer
description: Nombre maximum de requêtes par minute
X-RateLimit-Remaining:
schema:
type: integer
description: Requêtes restantes
X-RateLimit-Reset:
schema:
type: integer
description: Timestamp Unix de la réinitialisation
Retry-After:
schema:
type: integer
description: Secondes avant de pouvoir réessayer
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: Rate Limit Exceeded
message: Too many requests. Please wait before retrying.
details:
retry_after: 45
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: Authorization
description: >-
Clé API pour l'authentification. Utilisez votre clé API directement sans
préfixe (par exemple, 'your-api-key'). Le préfixe Bearer est optionnel
mais pas obligatoire.
````