> ## 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.
# Créer une Demande de Signature
> Crée une nouvelle demande de signature soit à partir d'un document PDF (basé sur un document), soit à partir d'un modèle existant (basé sur un modèle). Pour une création basée sur un document, allow_editing_before_sending est automatiquement défini sur true. Pour une création basée sur un modèle, les propriétés sont héritées du modèle et peuvent être surchargées.
**Motif d'ID Temporaire** : Pour une création basée sur un document, tu peux référencer des destinataires avant qu'ils soient créés en utilisant des ID temporaires (format : 'temp_X' où X est un identifiant quelconque, par exemple 'temp_1', 'temp_alice'). Utilise ces ID temporaires dans recipient.id, field.recipient_id et reminder.recipient_id. L'API valide toutes les références et fait automatiquement correspondre les ID temporaires aux vrais UUID une fois les destinataires créés. La réponse ne contient que de vrais UUID.
**Validation des ID Temporaires** : Les ID temporaires doivent commencer par 'temp_', être uniques parmi tous les destinataires de la requête, et toutes les références de champ/rappel doivent pointer vers des destinataires définis dans la même requête. Un format invalide, des ID en double ou des références de destinataires manquantes renvoient une erreur 400 avec des messages de validation détaillés.
## OpenAPI
````yaml api-reference/v01.30.00/openapi-v01.30.00.fr.json post /signing-requests
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:
post:
tags:
- Signing Requests
summary: Créer une Demande de Signature
description: >-
Crée une nouvelle demande de signature soit à partir d'un document PDF
(basé sur un document), soit à partir d'un modèle existant (basé sur un
modèle). Pour une création basée sur un document,
allow_editing_before_sending est automatiquement défini sur true. Pour
une création basée sur un modèle, les propriétés sont héritées du modèle
et peuvent être surchargées.
**Motif d'ID Temporaire** : Pour une création basée sur un document, tu
peux référencer des destinataires avant qu'ils soient créés en utilisant
des ID temporaires (format : 'temp_X' où X est un identifiant
quelconque, par exemple 'temp_1', 'temp_alice'). Utilise ces ID
temporaires dans recipient.id, field.recipient_id et
reminder.recipient_id. L'API valide toutes les références et fait
automatiquement correspondre les ID temporaires aux vrais UUID une fois
les destinataires créés. La réponse ne contient que de vrais UUID.
**Validation des ID Temporaires** : Les ID temporaires doivent commencer
par 'temp_', être uniques parmi tous les destinataires de la requête, et
toutes les références de champ/rappel doivent pointer vers des
destinataires définis dans la même requête. Un format invalide, des ID
en double ou des références de destinataires manquantes renvoient une
erreur 400 avec des messages de validation détaillés.
operationId: createSigningRequest
requestBody:
$ref: '#/components/requestBodies/PatchSigningRequestBody'
responses:
'201':
description: >-
Demande de signature créée avec succès. La réponse peut inclure un
tableau 'warnings' pour les avertissements de validation de format
d'email (non bloquants).
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/SigningRequestCreateResponse'
'400':
$ref: '#/components/responses/ValidationError'
description: >-
Entrée invalide - tu dois fournir soit 'document' soit
'template_id', pas les deux. Le document doit être un PDF valide
encodé en base64 de moins de 20 Mo. Le modèle doit exister et
appartenir à l'espace de travail.
'401':
$ref: '#/components/responses/UnauthorizedError'
'404':
description: Modèle introuvable ou n'appartenant pas à l'espace de travail
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'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.createSigningRequest({
template_id: "template_id",
name: "Updated Contract Name",
expiration_hours: 72
});
console.log(response);
components:
requestBodies:
PatchSigningRequestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PatchSigningRequestBodySchema'
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
add-date-field:
summary: Ajouter un champ date avec formatage
value:
field:
type: date
position:
x: 70
'y': 45
width: 15
height: 3
page_number: 1
required: true
recipient_id: rec123-e89b-12d3-a456-426614174000
date_signing_default: true
format_rules:
dateFormat: MMMM dd, yyyy
add-read-only-static-field:
summary: Ajouter un champ en lecture seule avec valeur statique
description: >-
Crée un champ texte qui affiche une valeur fixe que le
signataire ne peut pas modifier
value:
field:
type: text
position:
x: 15
'y': 20
width: 40
height: 3
page_number: 1
required: false
recipient_id: rec123-e89b-12d3-a456-426614174000
read_only: true
read_only_value: 'Contract #12345 - Acme Corporation'
add-read-only-prefilled-field:
summary: >-
Ajouter un champ en lecture seule avec les données du
destinataire
description: >-
Crée un champ texte qui se remplit automatiquement avec
l'adresse e-mail du destinataire (le signataire ne peut pas le
modifier)
value:
field:
type: text
position:
x: 15
'y': 30
width: 30
height: 3
page_number: 1
required: false
recipient_id: rec123-e89b-12d3-a456-426614174000
read_only: true
prefilled_data: email
schemas:
SigningRequestCreateResponse:
type: object
description: >-
Demande de signature telle que renvoyée par les endpoints CREATE (POST
/signing-requests)
properties:
id:
type: string
format: uuid
description: Identifiant unique de la demande de signature
name:
type: string
description: Nom de la demande de signature
maxLength: 255
description:
type: string
nullable: true
description: Description de la demande de signature
status:
type: string
enum:
- draft
description: >-
Le statut est toujours 'draft' pour les demandes de signature
nouvellement créées
document_url:
type: string
format: uri
description: URL pré-signée vers le document PDF
page_count:
type: integer
minimum: 1
description: Nombre de pages dans le document
expiration_hours:
type: integer
minimum: 1
default: 168
description: >-
Nombre d'heures avant l'expiration de la demande de signature (par
défaut : 168 = 7 jours)
template_id:
type: string
format: uuid
nullable: true
description: ID du modèle si créé à partir d'un modèle
settings:
$ref: '#/components/schemas/SigningRequestSettings'
created_date:
type: string
format: date-time
description: Horodatage de création
updated_date:
type: string
format: date-time
description: Horodatage de dernière mise à jour
sent_date:
type: string
format: date-time
nullable: true
description: Date d'envoi de la demande de signature
finished_date:
type: string
format: date-time
nullable: true
description: Date à laquelle toutes les signatures ont été complétées
cancelled_date:
type: string
format: date-time
nullable: true
description: Date d'annulation de la demande de signature
recipients:
type: array
description: Destinataires de la demande de signature
items:
$ref: '#/components/schemas/SigningRequestCreateRecipient'
fields:
type: array
description: >-
Champs de la demande de signature avec des valeurs de position à
plat
items:
$ref: '#/components/schemas/SigningRequestCreateField'
warnings:
type: array
items:
type: string
description: >-
Avertissements optionnels de validation du format des e-mails.
Présents uniquement lorsque les e-mails des destinataires ont des
formats inhabituels.
required:
- id
- name
- status
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
PatchSigningRequestBodySchema:
oneOf:
- type: object
required:
- document
description: Créer une Demande de Signature à partir d'un document PDF
properties:
document:
type: string
format: byte
description: >-
Document PDF ou DOCX encodé en base64. Les fichiers DOCX sont
automatiquement convertis en PDF. Le nombre de pages sera
extrait automatiquement.
name:
type: string
maxLength: 255
description: Nom de la Demande de Signature
description:
type: string
description: Description de la Demande de Signature
expiration_hours:
type: integer
minimum: 1
default: 168
description: >-
Nombre d'heures avant l'expiration de la Demande de Signature
(par défaut : 168 = 7 jours)
recipients:
type: array
items:
$ref: '#/components/schemas/Recipient'
description: >-
Destinataires de la Demande de Signature. Utilise des ID
temporaires (ex. 'temp_1') dans le champ id pour référencer les
destinataires dans fields/reminders.
fields:
type: array
items:
$ref: '#/components/schemas/Field'
description: >-
Champs à placer sur le document. Utilise recipient_id pour
assigner les champs aux destinataires.
anchor_tags:
type: array
maxItems: 100
items:
$ref: '#/components/schemas/AnchorTag'
description: >-
Balises d'ancrage pour le placement automatique des champs. Les
marqueurs de texte dans le PDF sont localisés et convertis en
champs positionnés. Le texte d'ancrage est supprimé du PDF après
traitement. Les champs créés à partir de balises d'ancrage sont
ajoutés en plus des champs spécifiés manuellement. Disponible
uniquement pour la création basée sur un document (pas basée sur
un Modèle).
reminders:
type: array
items:
$ref: '#/components/schemas/SigningRequestReminder'
description: Rappels à envoyer aux destinataires
settings:
$ref: '#/components/schemas/SigningRequestSettings'
description: Paramètres de la Demande de Signature
- type: object
required:
- template_id
description: >-
Créer une Demande de Signature à partir d'un Modèle. Prend en charge
les mises à jour partielles pour les destinataires et les champs.
properties:
template_id:
type: string
format: uuid
description: >-
ID du Modèle à partir duquel créer la Demande de Signature. Le
document, les champs et les destinataires par défaut seront
copiés depuis le Modèle.
name:
type: string
maxLength: 255
description: >-
Nom personnalisé pour la Demande de Signature (par défaut, le
nom du Modèle si non fourni)
description:
type: string
description: >-
Description personnalisée (par défaut, la description du Modèle
si non fournie)
expiration_hours:
type: integer
minimum: 1
description: Remplace le nombre d'heures d'expiration du Modèle
recipients:
type: array
items:
$ref: '#/components/schemas/Recipient'
description: >-
Remplacements optionnels des destinataires. Utilise
template_user_id (préféré) ou order (en repli) pour faire
correspondre les utilisateurs du Modèle. Seules les informations
utilisateur (first_name, last_name, email, phone_number, les
champs d'adresse, title, company) peuvent être mises à jour -
order et designation sont toujours hérités du Modèle. Les
destinataires non fournis utiliseront les valeurs par défaut du
Modèle.
fields:
type: array
items:
$ref: '#/components/schemas/Field'
description: >-
Surcharges de champs optionnelles pour les mises à jour
partielles. Utilisez template_field_id (préféré) ou
variable_name (solution de repli) pour faire correspondre les
champs du modèle. Seules les propriétés fournies remplacent les
valeurs par défaut du modèle. Propriétés de surcharge prises en
charge : type, required, position, read_only, read_only_value,
format_rules, validation_rules, dropdown_options, date_default,
date_signing_default, multi_group_id. Les champs non trouvés
sont ignorés. Si le tableau fields est omis, tous les champs du
modèle sont utilisés tels quels.
settings:
$ref: '#/components/schemas/SigningRequestSettings'
description: Remplacer les paramètres du modèle
example:
template_id: 21424147-11c0-43d5-ac5f-a1f7001b5607
name: Contract for Client X
recipients:
- template_user_id: template-user-uuid-1
first_name: Toni
last_name: Campins
email: acampins@cocodin.com
fields:
- template_field_id: field-uuid-1
read_only: true
read_only_value: 'Contract #12345'
- variable_name: company_name
read_only_value: Acme Corporation
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é.
SigningRequestCreateRecipient:
type: object
description: >-
Destinataire tel que renvoyé dans les réponses CREATE des demandes de
signature
properties:
id:
type: string
format: uuid
description: Identifiant unique du destinataire
first_name:
type: string
nullable: true
description: Prénom du destinataire
last_name:
type: string
nullable: true
description: Nom de famille du destinataire
name:
type: string
nullable: true
description: >-
Nom complet combiné (construit automatiquement à partir de
first_name + last_name)
email:
type: string
format: email
description: Adresse e-mail du destinataire
designation:
type: string
enum:
- Signer
- Approver
- CC
description: >-
Rôle du destinataire. Signer signe le document, Approver approuve
avec des champs d'approbation, CC reçoit une copie une fois terminé.
order:
type: integer
minimum: 1
description: Ordre de signature
phone_number:
type: string
nullable: true
description: Numéro de téléphone du destinataire
street_address:
type: string
nullable: true
description: Adresse postale
city:
type: string
nullable: true
description: Ville
state_province:
type: string
nullable: true
description: État ou province
postal_code:
type: string
nullable: true
description: Code postal
country:
type: string
nullable: true
description: Pays
title:
type: string
nullable: true
description: Intitulé du poste
company:
type: string
nullable: true
description: Nom de l'entreprise
custom_fields:
type: object
nullable: true
description: Paires clé-valeur personnalisées
finished_date:
type: string
format: date-time
nullable: true
description: Date à laquelle ce destinataire a terminé de signer
required:
- first_name
- email
- designation
SigningRequestCreateField:
type: object
description: >-
Champ tel que renvoyé dans les réponses CREATE des demandes de signature
(position à plat, style base de données)
properties:
id:
type: string
format: uuid
description: Identifiant unique du champ
type:
type: string
enum:
- text
- signature
- date
- checkbox
- dropdown
- radio_buttons
- number
- text_area
- file
- initial
- stamp
- approval_signature
- approval_checkmark
- approval_date
description: Type du champ
recipient_id:
type: string
format: uuid
nullable: true
description: ID du destinataire assigné
page_number:
type: integer
minimum: 1
description: Numéro de page (indexé à partir de 1)
x_position:
type: number
description: Coordonnée X en pourcentage (0-100)
y_position:
type: number
description: Coordonnée Y en pourcentage (0-100)
width:
type: number
description: Largeur en pourcentage (0-100)
height:
type: number
description: Hauteur en pourcentage (0-100)
required:
type: boolean
description: Indique si le champ est requis
read_only:
type: boolean
description: Indique si ce champ est en lecture seule
read_only_value:
type: string
nullable: true
description: Valeur statique pour les champs en lecture seule
variable_name:
type: string
nullable: true
description: Nom de variable pour le mappage des données préremplies
variable_defined_name:
type: string
nullable: true
description: >-
Nom de champ lisible provenant de la définition du champ
personnalisé (par ex. 'artist_name'). Présent uniquement pour les
champs liés à une définition de champ personnalisé, null sinon.
dropdown_options:
nullable: true
description: Options pour les champs déroulants
oneOf:
- type: array
items:
type: string
- type: object
format_rules:
type: object
nullable: true
description: Règles de formatage (par exemple, format de date)
validation_rules:
type: object
nullable: true
description: Règles de validation pour le champ
date_signing_default:
type: boolean
description: >-
Indique s'il faut utiliser la date de signature comme valeur par
défaut
final_value:
type: string
nullable: true
description: Valeur pré-remplie ou finale du champ
required:
- type
- recipient_id
- page_number
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
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'
AnchorTag:
type: object
required:
- anchor_string
- type
- recipient_id
description: >-
Définition d'un tag d'ancrage pour le placement automatique de champs.
Les tags d'ancrage sont des marqueurs de texte intégrés dans un document
PDF (ex. '{{SIGN_HERE}}') qui sont automatiquement localisés et
convertis en champs positionnés. Le texte d'ancrage est retiré du PDF
après traitement par défaut.
properties:
anchor_string:
type: string
minLength: 1
maxLength: 200
description: >-
Chaîne de texte à rechercher dans le document PDF. Les patterns
courants incluent '{{SIGN_HERE}}', '{{DATE}}', etc.
example: '{{SIGN_HERE}}'
type:
type: string
enum:
- signature
- initial
- initials
- text
- date
- checkbox
- radio_buttons
- radio
- dropdown
- textarea
- text_area
- url
- approval_signature
- approval_checkmark
- approval_date
description: Type de champ à placer à l'emplacement de l'ancrage
recipient_id:
oneOf:
- type: integer
- type: string
description: >-
ID du destinataire assigné à ce champ. Utilisez un ID temporaire
(ex. 'temp_1') pour la création basée sur un document, ou un ordre
entier pour la création basée sur un modèle.
example: temp_1
x_offset:
type: number
description: >-
Décalage horizontal par rapport à la position de l'ancrage. Les
unités sont déterminées par offset_units (par défaut : pourcentage
de la largeur de la page).
default: 0
y_offset:
type: number
description: >-
Décalage vertical par rapport à la position de l'ancrage. Les unités
sont déterminées par offset_units (par défaut : pourcentage de la
hauteur de la page).
default: 0
offset_units:
type: string
enum:
- percent
- pixels
default: percent
description: >-
Type d'unité pour x_offset et y_offset. 'percent' = pourcentage des
dimensions de la page, 'pixels' = points PDF (72 DPI).
width:
type: number
minimum: 0
exclusiveMinimum: true
description: >-
Largeur du champ en pourcentage de la largeur de la page. Les
valeurs par défaut varient selon le type de champ (ex. signature=25,
text=20, checkbox=3).
height:
type: number
minimum: 0
exclusiveMinimum: true
description: >-
Hauteur du champ en pourcentage de la hauteur de la page. Les
valeurs par défaut varient selon le type de champ (ex. signature=5,
text=3, checkbox=3).
case_sensitive:
type: boolean
default: false
description: >-
Indique si la correspondance de la chaîne d'ancrage est sensible à
la casse
match_whole_word:
type: boolean
default: true
description: >-
Indique s'il faut faire correspondre uniquement des mots entiers
(délimités par des caractères non-alphanumériques)
ignore_if_not_present:
type: boolean
default: false
description: >-
Si true, ignore cette ancre sans erreur si elle n'est pas trouvée
dans le document. Si false (par défaut), une ancre manquante
provoque une erreur de validation.
occurrence:
type: integer
minimum: 0
maximum: 1000
default: 0
description: >-
Quelle occurrence utiliser pour placer un champ. 0 = toutes les
occurrences (par défaut), 1 = la première seulement, 2 = la deuxième
seulement, etc.
remove_anchor_text:
type: boolean
default: true
description: >-
Indique s'il faut retirer le texte d'ancrage du PDF en dessinant un
rectangle blanc par-dessus
required:
type: boolean
default: true
description: Indique si le champ doit être complété par le signataire
read_only:
type: boolean
default: false
description: Indique si le champ est en lecture seule (pré-rempli)
read_only_value:
type: string
nullable: true
maxLength: 10000
description: Valeur statique pour les champs en lecture seule
variable_name:
type: string
nullable: true
maxLength: 255
description: Nom de variable pour le champ
variable_defined_name:
type: string
maxLength: 100
nullable: true
description: >-
Nom de définition de champ personnalisé lisible par un humain. Peut
être utilisé comme alternative à variable_name pour cibler des
champs dans la création basée sur un modèle.
background_color:
type: string
nullable: true
pattern: ^#([0-9A-Fa-f]{3}|[0-9A-Fa-f]{6})$
description: Couleur de fond en hexadécimal (ex. '#FFFDE7')
example: '#FFFDE7'
dropdown_options:
description: Options pour les champs déroulants
oneOf:
- type: array
items:
type: string
- type: object
date_default:
type: string
nullable: true
maxLength: 50
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
nullable: true
maxLength: 255
description: ID de groupe pour lier des champs checkbox/radio
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:
ValidationError:
description: Requête Incorrecte - Échec de la validation
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: Validation Error
message: Invalid input data
details:
name: Name is required
email: Invalid email format
UnauthorizedError:
description: Non Autorisé - Clé API invalide ou manquante
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: Unauthorized
message: Invalid API key
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.
````