> ## 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.
# Mise à jour complète de la demande de signature
> Effectue des mises à jour complètes d'une demande de signature, y compris les propriétés, les destinataires, les champs et les rappels. Impossible de mettre à jour après que la demande de signature a été envoyée, complétée ou annulée. Toutes les sections sont optionnelles, mais au moins une doit être fournie.
**Modèle d'ID temporaire pour les nouveaux destinataires** : lors de l'ajout de nouveaux destinataires dans une mise à jour complète, utilisez le champ '_temp_id' (format : 'temp_X') au lieu de 'id' pour établir des relations avec les champs et les rappels. Cela permet de créer de nouveaux destinataires et de les référencer dans les champs/rappels en une seule requête. Utilisez le champ 'id' pour mettre à jour des destinataires existants. Règles de validation : (1) les ID temporaires doivent commencer par 'temp_' ; (2) chaque ID temporaire doit être unique au sein de la requête ; (3) les champs et rappels peuvent référencer des ID temporaires dans leur propriété recipient_id ; (4) l'API résout automatiquement les ID temporaires en véritables UUID après la création du destinataire.
## OpenAPI
````yaml api-reference/v01.30.00/openapi-v01.30.00.fr.json put /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}:
put:
tags:
- Signing Requests
summary: Mise à jour complète de la demande de signature
description: >-
Effectue des mises à jour complètes d'une demande de signature, y
compris les propriétés, les destinataires, les champs et les rappels.
Impossible de mettre à jour après que la demande de signature a été
envoyée, complétée ou annulée. Toutes les sections sont optionnelles,
mais au moins une doit être fournie.
**Modèle d'ID temporaire pour les nouveaux destinataires** : lors de
l'ajout de nouveaux destinataires dans une mise à jour complète,
utilisez le champ '_temp_id' (format : 'temp_X') au lieu de 'id' pour
établir des relations avec les champs et les rappels. Cela permet de
créer de nouveaux destinataires et de les référencer dans les
champs/rappels en une seule requête. Utilisez le champ 'id' pour mettre
à jour des destinataires existants. Règles de validation : (1) les ID
temporaires doivent commencer par 'temp_' ; (2) chaque ID temporaire
doit être unique au sein de la requête ; (3) les champs et rappels
peuvent référencer des ID temporaires dans leur propriété recipient_id ;
(4) l'API résout automatiquement les ID temporaires en véritables UUID
après la création du destinataire.
operationId: updateSigningRequest
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
description: ID de la demande de signature
requestBody:
$ref: '#/components/requestBodies/UpdateSigningRequestBody'
responses:
'200':
description: >-
Demande de signature mise à jour avec succès. Renvoie la demande de
signature mise à jour et un résumé des modifications effectuées.
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:
$ref: '#/components/schemas/SigningRequestUpdateResponse'
'400':
description: >-
Erreurs de validation. Toutes les erreurs de section sont renvoyées
ensemble.
content:
application/json:
schema:
$ref: '#/components/schemas/SigningRequestUpdateError'
example:
error: Validation failed
message: Multiple validation errors occurred
details:
recipients:
- 'Recipient 1: email is invalid'
deleted_recipients:
- 'Cannot reassign: designations must match'
fields:
- 'Field 2: x coordinate must be between 0 and 100'
'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.updateSigningRequest({
id: "id",
signing_request_properties: {
name: "Updated Contract Name",
expiration_hours: 72
},
recipients: [{
id: "rec1-e89b-12d3-a456-426614174000",
first_name: "John",
last_name: "Smith",
email: "john.smith@example.com",
designation: "Signer",
order: 1
}, {
first_name: "Jane",
last_name: "Doe",
email: "jane@example.com",
designation: "Signer",
order: 2
}],
deleted_recipients: [{
recipient_id: "rec2-e89b-12d3-a456-426614174000",
field_action: "reassign",
reassign_to_recipient_id: "rec1-e89b-12d3-a456-426614174000"
}],
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"
}],
reminders: [{
hours: 48,
all_users: true,
subject: "Reminder: Please sign the document",
message: "This is a reminder to complete your signature."
}]
});
console.log(response);
components:
requestBodies:
UpdateSigningRequestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateSigningRequestBodySchema'
examples:
comprehensive-update:
summary: Mise à jour complète avec toutes les sections
value:
signing_request_properties:
name: Updated Contract Name
expiration_hours: 72
recipients:
- id: rec1-e89b-12d3-a456-426614174000
first_name: John
last_name: Smith
email: john.smith@example.com
designation: Signer
order: 1
- first_name: Jane
last_name: Doe
email: jane@example.com
designation: Signer
order: 2
deleted_recipients:
- recipient_id: rec2-e89b-12d3-a456-426614174000
field_action: reassign
reassign_to_recipient_id: rec1-e89b-12d3-a456-426614174000
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
reminders:
- hours: 48
all_users: true
subject: 'Reminder: Please sign the document'
message: This is a reminder to complete your signature.
update-with-temp-ids:
summary: >-
Mise à jour avec de nouveaux destinataires via des ID
temporaires
description: >-
Mise à jour complète ajoutant de nouveaux destinataires avec des
ID temporaires en plus des destinataires existants
value:
signing_request_properties:
name: Updated NDA Agreement
recipients:
- id: existing-recipient-uuid
email: updated@example.com
- _temp_id: temp_new_signer
first_name: New
last_name: Signer
email: newsigner@example.com
designation: Signer
order: 2
fields:
- id: existing-field-uuid
position:
x: 10
'y': 70
width: 30
height: 10
- recipient_id: temp_new_signer
type: signature
page_number: 1
position:
x: 10
'y': 55
width: 30
height: 10
required: true
reminders:
- recipient_id: temp_new_signer
hours: 24
all_users: false
subject: 'Reminder: Sign Document'
message: Please sign the updated NDA.
schemas:
SigningRequestUpdateResponse:
type: object
properties:
id:
type: string
format: uuid
description: ID de la demande de signature (pour compatibilité ascendante)
name:
type: string
description: Nom de la demande de signature (pour compatibilité ascendante)
signing_request:
type: object
description: >-
Résumé de la demande de signature mise à jour (sous-ensemble du
schéma complet SigningRequest)
properties:
id:
type: string
format: uuid
description: ID de la demande de signature
name:
type: string
description: Nom de la demande de signature
description:
type: string
nullable: true
description: >-
Description de la demande de signature (mappée depuis
template_description)
document_url:
type: string
format: uri
description: URL pré-signée vers le document PDF
document_url_expires_at:
type: string
format: date-time
nullable: true
description: Quand l'URL du document expire
document_page_count:
type: integer
description: Nombre de pages dans le document
status:
type: string
description: Statut actuel de la demande de signature
expiration_hours:
type: integer
description: Heures avant l'expiration de la demande de signature
settings:
type: object
description: >-
Sous-ensemble des paramètres de la demande de signature renvoyé
dans la réponse PUT
properties:
allow_download:
type: boolean
description: Indique si les destinataires peuvent télécharger le document
attach_pdf_on_finish:
type: boolean
description: Indique si le PDF doit être joint à la fin
hand_drawn_only:
type: boolean
description: Indique si seules les signatures manuscrites sont autorisées
template_id:
type: string
format: uuid
nullable: true
description: ID du modèle si créé à partir d'un modèle
expires_at:
type: string
format: date-time
nullable: true
description: Horodatage ISO 8601 de l'expiration de la demande de signature
created_date:
type: string
format: date-time
description: Horodatage de création
sent_date:
type: string
format: date-time
nullable: true
description: Quand la demande de signature a été envoyée
finished_date:
type: string
format: date-time
nullable: true
description: Quand toutes les signatures ont été complétées
cancelled_date:
type: string
format: date-time
nullable: true
description: Quand la demande de signature a été annulée
recipients:
type: array
items:
$ref: '#/components/schemas/Recipient'
description: Liste mise à jour des destinataires
reminders:
type: array
items:
$ref: '#/components/schemas/Reminder'
description: Liste mise à jour des rappels
summary:
type: object
description: Résumé de tous les changements effectués dans cette mise à jour
properties:
properties_updated:
type: boolean
description: Indique si des propriétés ont été mises à jour
recipients_created:
type: integer
description: Nombre de nouveaux destinataires créés
recipients_updated:
type: integer
description: Nombre de destinataires existants mis à jour
recipients_deleted:
type: integer
description: Nombre de destinataires supprimés en soft-delete
fields_created:
type: integer
description: Nombre de nouveaux champs créés
fields_updated:
type: integer
description: Nombre de champs existants mis à jour
fields_reassigned:
type: integer
description: Nombre de champs réassignés à un autre destinataire
fields_deleted:
type: integer
description: Nombre de champs supprimés en soft-delete
reminders_created:
type: integer
description: Nombre de nouveaux rappels créés
reminders_updated:
type: integer
description: Nombre de rappels existants mis à jour
warnings:
type: array
items:
type: string
description: >-
Avertissements de format d'email pour les destinataires (non
bloquants)
description: Résultat de la mise à jour de la demande de signature
required:
- id
- name
SigningRequestUpdateError:
type: object
properties:
error:
type: string
message:
type: string
details:
type: object
properties:
signing_request_properties:
type: array
items:
type: string
recipients:
type: array
items:
type: string
deleted_recipients:
type: array
items:
type: string
fields:
type: array
items:
type: string
reminders:
type: array
items:
type: string
description: Erreur de validation lors de la mise à jour de la demande de signature
required:
- error
UpdateSigningRequestBodySchema:
type: object
properties:
signing_request_properties:
type: object
description: Mettre à jour les propriétés de la demande de signature
properties:
name:
type: string
maxLength: 255
description:
type: string
document:
type: string
format: byte
description: Remplacer le document (PDF encodé en base64)
expiration_hours:
type: integer
minimum: 1
settings:
$ref: '#/components/schemas/SigningRequestSettings'
recipients:
type: array
items:
$ref: '#/components/schemas/Recipient'
description: >-
Upsert des destinataires - incluez 'id' pour mettre à jour des
destinataires existants, utilisez '_temp_id' (par ex. 'temp_1') pour
les nouveaux destinataires afin de les référencer dans les champs et
rappels au sein de la même requête
deleted_recipients:
type: array
items:
$ref: '#/components/schemas/DeletedRecipient'
description: Destinataires à supprimer et comment gérer leurs champs
force_remove_conditions:
type: boolean
default: false
description: >-
Lors de la suppression de destinataires dont les champs sont
référencés par des conditions dans d'autres champs : si true, retire
automatiquement les références de condition ; si false (par défaut),
la requête sera rejetée avec une erreur listant les champs
dépendants.
fields:
type: array
items:
$ref: '#/components/schemas/Field'
description: >-
Upsert des champs - incluez id pour mettre à jour, omettez id pour
créer un nouveau champ
reminders:
type: array
items:
$ref: '#/components/schemas/SigningRequestReminder'
description: >-
Upsert des rappels - incluez id pour mettre à jour, omettez id pour
créer un nouveau rappel
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
Reminder:
type: object
properties:
id:
type: string
format: uuid
description: Identifiant unique du rappel
hours:
type: integer
minimum: 1
description: Nombre d'heures après l'envoi avant l'envoi du rappel
subject:
type: string
description: Objet de l'email pour le rappel
maxLength: 255
message:
type: string
description: Corps du message de l'email pour le rappel
maxLength: 5000
all_users:
type: boolean
description: Indique si le rappel s'applique à tous les utilisateurs
template_user_id:
type: string
format: uuid
nullable: true
description: >-
Utilisateur spécifique auquel envoyer le rappel (utilisé dans le
contexte d'un modèle)
recipient_id:
type: string
format: uuid
nullable: true
description: >-
Destinataire spécifique auquel envoyer le rappel (utilisé dans le
contexte d'une demande de signature, identique à template_user_id)
sent_on:
type: string
format: date-time
nullable: true
description: Horodatage du moment où le rappel a réellement été envoyé
created_at:
type: string
format: date-time
description: Horodatage de création du rappel
updated_at:
type: string
format: date-time
description: Horodatage de dernière mise à jour du rappel
required:
- id
- hours
- subject
- message
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
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é.
DeletedRecipient:
type: object
required:
- recipient_id
- field_action
properties:
recipient_id:
type: string
format: uuid
description: ID du destinataire à supprimer
field_action:
type: string
enum:
- delete
- reassign
description: Action à effectuer sur les champs assignés à ce destinataire
reassign_to_recipient_id:
type: string
format: uuid
description: >-
Destinataire vers lequel réassigner les champs (requis si
field_action est 'reassign')
Field:
type: object
required:
- type
- position
- page_number
description: >-
Définition de champ pour les demandes de signature. **Champs en lecture
seule** : définissez read_only=true pour pré-remplir une valeur de champ
que les signataires ne peuvent pas modifier. Utilisez read_only_value
pour du texte statique, ou prefilled_data pour remplir automatiquement à
partir des attributs du destinataire. **Fusion de champs basée sur un
modèle** : lors de la création à partir d'un modèle avec un tableau
fields, utilisez template_field_id (préféré) ou variable_name (repli)
pour faire correspondre les champs du modèle. Seules les propriétés
fournies remplacent les valeurs par défaut du modèle (mise à jour
partielle). Les champs non appariés sont ignorés.
properties:
id:
type: string
format: uuid
description: >-
Identifiant unique (à inclure pour les mises à jour, à omettre pour
les nouveaux champs)
template_field_id:
type: string
format: uuid
description: >-
ID du champ du modèle à faire correspondre pour les mises à jour
partielles (création basée sur un modèle uniquement). Utilisez ceci
pour identifier quel champ du modèle remplacer. A priorité sur
variable_name pour la correspondance.
type:
type: string
enum:
- signature
- text
- date
- checkbox
- dropdown
- initial
- initials
- text_area
- textarea
- image
- stamp
- approval_signature
- approval_checkmark
- approval_date
description: >-
Type de champ. Accepte 'initial' ou 'initials' (normalisé en
'initial'), 'textarea' ou 'text_area' (normalisé en 'text_area').
position:
type: object
required:
- x
- 'y'
- width
- height
description: >-
Le champ doit tenir dans les limites de la page : x + width <= 100
et y + height <= 100
properties:
x:
type: number
minimum: 0
maximum: 100
description: Coordonnée X en pourcentage (0-100)
'y':
type: number
minimum: 0
maximum: 100
description: Coordonnée Y en pourcentage (0-100)
width:
type: number
minimum: 0
maximum: 100
description: Largeur en pourcentage (0-100). x + width doit être <= 100
height:
type: number
minimum: 0
maximum: 100
description: Hauteur en pourcentage (0-100). y + height doit être <= 100
page_number:
type: integer
minimum: 1
description: >-
Numéro de la page où se trouve le champ (indexé à partir de 1). Ne
doit pas dépasser le nombre total de pages du document.
required:
type: boolean
default: false
description: Indique si le champ doit être complété
recipient_id:
type: string
description: >-
ID du destinataire assigné à ce champ. Utilisez un véritable UUID
pour la création ou les mises à jour basées sur un modèle, ou un ID
temporaire (par ex. 'temp_1') pour la création basée sur un document
afin de référencer les destinataires définis dans la même requête.
variable_name:
type: string
maxLength: 100
nullable: true
description: >-
Nom de variable pour le champ (utilisé dans les modèles). Également
utilisé comme repli pour la correspondance de champs lors de la
création basée sur un modèle quand template_field_id n'est pas
fourni.
variable_defined_name:
type: string
maxLength: 100
nullable: true
description: >-
Nom lisible et personnalisé de définition du champ. Peut être
utilisé comme alternative à variable_name pour cibler des champs
lors de la création basée sur un modèle.
dropdown_options:
description: Options pour les champs de liste déroulante
oneOf:
- type: array
items:
type: string
- type: object
date_default:
type: string
format: date
nullable: true
description: Valeur de date par défaut
date_signing_default:
type: boolean
default: false
description: Utiliser la date de signature comme valeur par défaut
multi_group_id:
type: string
format: uuid
nullable: true
description: >-
ID de groupe pour lier plusieurs champs de case à cocher ou de
bouton radio ensemble. Les champs partageant le même multi_group_id
se comportent comme un groupe mutuellement exclusif (comme des
boutons radio) - en sélectionner un désélectionne automatiquement
les autres du groupe. Utilisez le même UUID sur plusieurs champs
pour créer un groupe où une seule option peut être sélectionnée à la
fois.
format_rules:
oneOf:
- $ref: '#/components/schemas/DateFormatRules'
- $ref: '#/components/schemas/FileFormatRules'
- type: object
additionalProperties: true
nullable: true
description: >-
Règles de formatage pour la valeur du champ. Pour les champs de
date, utilisez le schéma DateFormatRules avec la propriété
dateFormat. Pour les champs de fichier, utilisez le schéma
FileFormatRules avec la propriété acceptedFileTypes (image_and_pdf,
image, ou pdf). Pour les champs url, utilisez { urlDisplayText:
string }.
validation_rules:
$ref: '#/components/schemas/FieldValidationRules'
read_only:
type: boolean
default: false
description: >-
Indique si ce champ est en lecture seule (pré-rempli avant la
signature). Quand c'est true, le signataire ne peut pas modifier la
valeur du champ. Utile pour afficher les termes du contrat, les
infos du destinataire, ou d'autres données fixes.
read_only_value:
type: string
nullable: true
description: >-
Valeur statique pour les champs en lecture seule. Prend le dessus
sur prefilled_data si les deux sont spécifiés. Applicable uniquement
quand read_only est true. Exemple : 'Contract #12345' ou 'Acme
Corporation'.
prefilled_data:
type: string
nullable: true
enum:
- first_name
- last_name
- full_name
- email
- phone_number
- company
- title
- street_address
- city
- state_province
- postal_code
- country
description: >-
Attribut utilisateur à auto-remplir quand read_only est true. La
valeur est récupérée depuis les données du destinataire assigné au
moment de la signature. Peut aussi référencer des clés custom_fields
définies sur le destinataire (pas limité aux valeurs enum).
Applicable uniquement quand read_only est true et que
read_only_value n'est pas défini. Exemple : Mettre 'email' pour
afficher l'adresse email du destinataire.
required_conditions:
$ref: '#/components/schemas/ConditionSet'
nullable: true
description: >-
Règles conditionnelles pour déterminer quand ce champ est requis.
Quand c'est défini, ça prend le dessus sur le flag statique
'required'. Le champ n'est requis que quand les conditions évaluent
à true en fonction des valeurs d'autres champs.
visibility_conditions:
$ref: '#/components/schemas/ConditionSet'
nullable: true
description: >-
Règles conditionnelles pour déterminer quand ce champ est visible.
Quand c'est défini, le champ est caché sauf si les conditions
évaluent à true. Les champs cachés ne sont pas validés à la
soumission.
background_color:
type: string
nullable: true
pattern: ^#([0-9A-Fa-f]{3}|[0-9A-Fa-f]{6})$
description: >-
Couleur de fond du champ sous forme de chaîne hexadécimale (ex.
'#FFFDE7', '#fff'). Utile pour mettre en évidence les champs qui
nécessitent de l'attention.
example: '#FFFDE7'
SigningRequestReminder:
type: object
required:
- hours
- subject
- message
properties:
id:
type: string
format: uuid
description: >-
Identifiant unique (à inclure pour les mises à jour, à omettre pour
les nouveaux rappels)
hours:
type: integer
minimum: 1
description: Heures avant l'expiration pour envoyer le rappel
all_users:
type: boolean
default: false
description: Envoyer le rappel à tous les destinataires
recipient_id:
type: string
nullable: true
description: >-
ID de destinataire spécifique (requis si all_users est false).
Utilisez un véritable UUID pour les destinataires existants ou un ID
temporaire (par exemple, 'temp_1') pour la création basée sur un
document afin de référencer des destinataires dans la même demande.
subject:
type: string
maxLength: 255
description: Objet de l'email
message:
type: string
maxLength: 5000
description: Corps du message de l'email
DateFormatRules:
type: object
description: >-
Règles de formatage pour les champs de date. Spécifie comment les
valeurs de date doivent être affichées et formatées.
properties:
dateFormat:
type: string
description: >-
Modèle de format de date. Utilisez des formats prédéfinis ou des
modèles personnalisés avec : yyyy (année sur 4 chiffres), MM (mois
sur 2 chiffres), dd (jour sur 2 chiffres), MMMM (nom complet du
mois), MMM (nom abrégé du mois), HH (heure sur 24h), mm (minute), ss
(seconde). Exemples : 'MM/dd/yyyy' s'affiche comme 01/31/2024, 'MMMM
dd, yyyy' s'affiche comme January 31, 2024.
enum:
- MM/dd/yyyy
- dd/MM/yyyy
- yyyy-MM-dd
- MMMM dd, yyyy
- MMM dd, yyyy
- dd MMMM yyyy
default: MM/dd/yyyy
example:
dateFormat: MMMM dd, yyyy
FileFormatRules:
type: object
description: >-
Règles de formatage pour les champs de téléversement de fichier.
Spécifie quels types de fichiers les signataires sont autorisés à
téléverser.
properties:
acceptedFileTypes:
type: string
enum:
- image_and_pdf
- image
- pdf
default: image_and_pdf
description: >-
Types de fichiers acceptés pour le téléversement. 'image_and_pdf'
accepte les JPG, PNG et PDF. 'image' accepte uniquement les JPG et
PNG. 'pdf' accepte uniquement les PDF. Les fichiers sont validés par
leurs magic bytes, pas seulement par l'extension. La taille maximale
du fichier est de 10 Mo.
example:
acceptedFileTypes: image_and_pdf
FieldValidationRules:
type: object
nullable: true
description: >-
Règles de validation pour les valeurs des champs. Réservé pour un usage
futur, actuellement non appliqué pour aucun type de champ.
additionalProperties: true
ConditionSet:
type: object
required:
- logic
- groups
description: >-
Un ensemble de groupes de conditions avec une logique imbriquée.
L'opérateur 'logic' externe combine les groupes, tandis que les
conditions de chaque groupe utilisent l'opérateur opposé. Exemple :
logic='and' signifie que tous les groupes doivent correspondre, et qu'au
sein de chaque groupe n'importe quelle condition peut correspondre (OR).
properties:
logic:
type: string
enum:
- and
- or
description: >-
Opérateur logique pour combiner les groupes. 'and' = tous les
groupes doivent correspondre, 'or' = n'importe quel groupe peut
correspondre.
groups:
type: array
items:
$ref: '#/components/schemas/ConditionGroup'
description: Tableau de groupes de conditions
ConditionGroup:
type: object
required:
- conditions
properties:
conditions:
type: array
items:
$ref: '#/components/schemas/Condition'
description: >-
Tableau de conditions au sein de ce groupe. Combinées en utilisant
l'opérateur logique opposé à celui du ConditionSet parent.
Condition:
type: object
required:
- field_id
- operator
description: Une condition unique qui évalue la valeur d'un champ.
properties:
field_id:
type: string
format: uuid
description: ID du champ à évaluer
operator:
type: string
enum:
- is_filled
- is_empty
- equals
- not_equals
- contains
- not_contains
- greater_than
- less_than
- greater_than_or_equal
- less_than_or_equal
description: >-
Opérateur de comparaison. 'is_filled'/'is_empty' ne nécessitent pas
de valeur. Opérateurs de texte : equals, not_equals, contains,
not_contains. Opérateurs numériques/date : greater_than, less_than,
greater_than_or_equal, less_than_or_equal.
value:
oneOf:
- type: string
- type: number
nullable: true
description: >-
Valeur à comparer. Non requise pour les opérateurs
is_filled/is_empty.
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.
````