> ## 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 et Envoyer une Demande de Signature (Atomique)
> Crée et envoie immédiatement une demande de signature en une seule opération atomique. Ce endpoint combine les fonctionnalités de POST /signing-requests et POST /signing-requests/{id}/send.
**Avantages Clés :**
- Un seul appel API au lieu de deux requêtes séparées
- Valide toutes les exigences d'envoi AVANT de créer la demande de signature
- Déduction de crédit atomique - facture uniquement si tout réussit
- Renvoie status: 'sent' immédiatement avec les détails du premier signataire
- Plus efficace (économise 1 appel API + le temps d'aller-retour)
**Validation :**
- Toutes les validations de création standard (document/modèle, destinataires, champs)
- Validations d'envoi supplémentaires :
- Tous les signataires doivent avoir un first_name et un email valide
- Les champs en lecture seule requis doivent avoir un final_value renseigné
- Les champs de données prérempliées (variable_name) doivent avoir les données utilisateur correspondantes
- L'entreprise doit disposer de crédits suffisants (≥1)
**Atomicité :**
- Si une validation échoue, rien n'est créé
- Le crédit n'est déduit qu'après la création réussie et avant l'envoi de l'email
- Si l'envoi de l'email échoue après la création, la demande de signature reste au statut 'draft' et le crédit N'est PAS déduit
**Motif d'ID Temporaire :** Pour une création basée sur un document, utilise des ID temporaires (format : 'temp_X') pour référencer les destinataires avant leur création. L'API valide toutes les références et fait automatiquement correspondre les ID temporaires aux vrais UUID.
**Limite de Débit :** 120 requêtes/minute (identique aux opérations d'écriture)
## OpenAPI
````yaml api-reference/v01.30.00/openapi-v01.30.00.fr.json post /signing-requests/create-and-send
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/create-and-send:
post:
tags:
- Signing Requests
summary: Créer et Envoyer une Demande de Signature (Atomique)
description: >-
Crée et envoie immédiatement une demande de signature en une seule
opération atomique. Ce endpoint combine les fonctionnalités de POST
/signing-requests et POST /signing-requests/{id}/send.
**Avantages Clés :**
- Un seul appel API au lieu de deux requêtes séparées
- Valide toutes les exigences d'envoi AVANT de créer la demande de
signature
- Déduction de crédit atomique - facture uniquement si tout réussit
- Renvoie status: 'sent' immédiatement avec les détails du premier
signataire
- Plus efficace (économise 1 appel API + le temps d'aller-retour)
**Validation :**
- Toutes les validations de création standard (document/modèle,
destinataires, champs)
- Validations d'envoi supplémentaires :
- Tous les signataires doivent avoir un first_name et un email valide
- Les champs en lecture seule requis doivent avoir un final_value renseigné
- Les champs de données prérempliées (variable_name) doivent avoir les données utilisateur correspondantes
- L'entreprise doit disposer de crédits suffisants (≥1)
**Atomicité :**
- Si une validation échoue, rien n'est créé
- Le crédit n'est déduit qu'après la création réussie et avant l'envoi
de l'email
- Si l'envoi de l'email échoue après la création, la demande de
signature reste au statut 'draft' et le crédit N'est PAS déduit
**Motif d'ID Temporaire :** Pour une création basée sur un document,
utilise des ID temporaires (format : 'temp_X') pour référencer les
destinataires avant leur création. L'API valide toutes les références et
fait automatiquement correspondre les ID temporaires aux vrais UUID.
**Limite de Débit :** 120 requêtes/minute (identique aux opérations
d'écriture)
operationId: createAndSendSigningRequest
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- name
properties:
name:
type: string
maxLength: 255
description: Nom de la demande de signature
example: Employment Contract - John Doe
description:
type: string
description: Description de la demande de signature
example: Full-time employment contract for Software Engineer position
document:
type: string
format: byte
description: >-
Document PDF ou DOCX encodé en base64 (mutuellement exclusif
avec template_id et document_id). Les fichiers DOCX sont
automatiquement convertis en PDF. Taille maximale : 50 Mo.
example: >-
JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PC9UeXBlIC9QYWdlCi9QYXJlbnQgMSAwIFIKL1Jlc291c...
template_id:
type: string
format: uuid
description: >-
ID du modèle à utiliser (mutuellement exclusif avec document
et document_id)
example: 123e4567-e89b-12d3-a456-426614174000
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)
example: 168
recipients:
type: array
description: >-
Tableau de destinataires. Au moins un doit être un
Signataire. Pour une création basée sur un document :
obligatoire. Pour une création basée sur un modèle :
optionnel (utilise les destinataires du modèle si omis).
Utilisez template_user_id (préféré) ou order (solution de
repli) pour faire correspondre les utilisateurs du modèle.
minItems: 1
items:
$ref: '#/components/schemas/Recipient'
fields:
type: array
description: >-
Tableau de champs à remplir (basé sur un document
uniquement)
items:
type: object
required:
- type
- page
- x
- 'y'
properties:
recipient_id:
type: string
description: >-
ID temporaire ou UUID du destinataire assigné à ce
champ
example: temp_signer_1
type:
type: string
enum:
- signature
- initial
- text
- date
- checkbox
- dropdown
- radio_buttons
- text_area
- url
- file
- stamp
- approval_signature
- approval_checkmark
- approval_date
description: >-
Type de champ. Accepte les alias : "initials"
(normalisé en "initial"), "textarea" (normalisé en
"text_area"), "radio" (normalisé en "radio_buttons").
example: signature
page:
type: integer
minimum: 1
description: Numéro de page du PDF (indexé à partir de 1)
example: 1
x:
type: number
description: Coordonnée X sur la page
example: 100
'y':
type: number
description: Coordonnée Y sur la page
example: 200
width:
type: number
default: 200
example: 200
height:
type: number
default: 50
example: 50
variable_name:
type: string
description: >-
Nom de variable pour les données préremplies (par ex.
'phone_number', 'company'). Si défini, le champ
correspondant du destinataire doit être renseigné.
enum:
- first_name
- last_name
- full_name
- email
- phone_number
- street_address
- city
- state_province
- postal_code
- country
- title
- company
example: phone_number
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 d'une création basée sur
un modèle.
required:
type: boolean
default: false
description: Indique si le champ est obligatoire
read_only:
type: boolean
default: false
description: Indique si le champ est en lecture seule (prérempli)
final_value:
type: string
description: >-
Valeur préremplie pour les champs en lecture seule
(obligatoire si read_only=true et required=true)
example: Software Engineer
background_color:
type: string
nullable: true
pattern: ^#([0-9A-Fa-f]{3}|[0-9A-Fa-f]{6})$
description: >-
Couleur d'arrière-plan en hexadécimal (par ex.
'#FFFDE7')
example: '#FFFDE7'
dropdown_options:
description: >-
Options pour les champs de type liste déroulante.
Obligatoire quand type vaut "dropdown".
example:
- Option A
- Option B
- Option C
oneOf:
- type: array
items:
type: string
- type: object
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 puis
convertis en champs positionnés. Le texte d'ancrage est
supprimé du PDF après traitement. Les champs créés à partir
des balises d'ancrage s'ajoutent aux champs spécifiés
manuellement. Disponible uniquement pour la création basée
sur un document (pas pour celle basée sur un modèle).
reminders:
type: array
description: Tableau de configurations de rappels
items:
type: object
required:
- hours_before_expiration
properties:
hours_before_expiration:
type: integer
minimum: 1
description: Heures avant expiration pour l'envoi du rappel
example: 24
settings:
type: object
description: Paramètres de la demande de signature
properties:
use_signing_order:
type: boolean
default: true
description: >-
Impose l'ordre de signature basé sur recipient.order. Si
false, tous les signataires reçoivent le document
simultanément.
allow_download:
type: boolean
default: true
description: Autoriser les destinataires à télécharger le document
attach_pdf_on_finish:
type: boolean
default: true
description: Joindre le PDF finalisé à l'e-mail de fin de signature
send_signing_email:
type: boolean
default: true
description: Envoyer une notification par e-mail aux signataires
send_finish_email:
type: boolean
default: true
description: >-
Envoyer un e-mail quand toutes les signatures sont
terminées
send_expiration_email:
type: boolean
default: true
description: Envoyer un e-mail quand la demande expire
send_cancellation_email:
type: boolean
default: true
description: Envoyer un e-mail quand la demande est annulée
hand_drawn_only:
type: boolean
default: false
description: >-
Exiger que les signataires dessinent leur signature à la
main plutôt que d'utiliser une signature saisie
identity_editable_fields:
type: array
nullable: true
items:
type: string
enum:
- name
- company
- title
- phone
- address
description: >-
Champs d'identité que les signataires peuvent modifier
avant de signer. null = désactivé. Si défini, une boîte
de dialogue de confirmation apparaît pour permettre aux
signataires de modifier les champs spécifiés.
example:
- name
- company
notify_identity_change_webhook:
type: boolean
default: false
description: >-
Envoyer un événement webhook quand un signataire modifie
son identité
notify_identity_change_email:
type: boolean
default: false
description: >-
Envoyer une notification par e-mail quand un signataire
modifie son identité
document_id:
type: string
format: uuid
description: >-
ID d'un document précédemment téléversé (mutuellement
exclusif avec document et template_id). À obtenir en
appelant d'abord POST /documents.
example: 123e4567-e89b-12d3-a456-426614174000
oneOf:
- required:
- document
- required:
- template_id
examples:
document-based:
summary: Créer et envoyer avec un document
value:
name: Employment Contract - John Doe
description: Contrat de travail à temps plein
document: JVBERi0xLjQKJeLjz9MK...
expiration_hours: 168
recipients:
- id: temp_signer_1
first_name: John
last_name: Doe
email: john.doe@example.com
designation: Signer
order: 1
phone_number: +1-555-0123
company: Acme Corp
title: Ingénieur logiciel
fields:
- recipient_id: temp_signer_1
type: signature
page: 1
x: 100
'y': 500
width: 200
height: 50
- recipient_id: temp_signer_1
type: text
page: 1
x: 100
'y': 400
width: 150
height: 30
variable_name: phone_number
required: true
read_only: true
settings:
use_signing_order: true
send_signing_email: true
template-based:
summary: Créer et envoyer à partir d'un modèle
value:
name: NDA - Jane Smith
template_id: 123e4567-e89b-12d3-a456-426614174000
recipients:
- first_name: Jane
last_name: Smith
email: jane.smith@example.com
designation: Signer
order: 1
company: Tech Startup Inc
expiration_hours: 72
responses:
'201':
description: Demande de signature créée et envoyée avec succès
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/CreateAndSendResponse'
example:
id: 550e8400-e29b-41d4-a716-446655440000
name: Employment Contract - John Doe
description: Contrat de travail à temps plein
status: sent
document_url: https://storage.supabase.co/...
page_count: 3
expiration_hours: 168
settings:
use_signing_order: true
allow_download: true
attach_pdf_on_finish: true
send_signing_email: true
send_finish_email: true
send_expiration_email: true
send_cancellation_email: true
hand_drawn_only: false
created_date: '2026-01-12T10:30:00Z'
sent_date: '2026-01-12T10:30:00Z'
template_id: null
first_signer:
id: rec456-e89b-12d3-a456-426614174000
name: John Doe
email: john.doe@example.com
signing_link: >-
https://app.firma.dev/signing/rec456-e89b-12d3-a456-426614174000
recipients:
- id: rec456-e89b-12d3-a456-426614174000
first_name: John
last_name: Doe
name: John Doe
email: john.doe@example.com
designation: Signer
order: 1
fields:
- id: field123-e89b-12d3-a456-426614174000
type: signature
page: 1
x: 100
'y': 500
width: 200
height: 50
required: true
recipient_id: rec456-e89b-12d3-a456-426614174000
credits_remaining: 99
'400':
description: >-
Erreur de validation - entrée invalide ou données de signataire
obligatoires manquantes
content:
application/json:
schema:
$ref: '#/components/schemas/CreateAndSendValidationError'
examples:
missing-recipient-data:
value:
error: >-
One or more signers are missing required information for
sending
phase: send_validation
validation_errors:
- recipient_index: 1
recipient_email: john@example.com
missing_fields:
- phone_number
- company
invalid-document:
value:
error: Document must be valid base64-encoded PDF
phase: create_validation
'401':
$ref: '#/components/responses/UnauthorizedError'
'402':
description: Crédits insuffisants
content:
application/json:
schema:
$ref: '#/components/schemas/InsufficientCreditsError'
'404':
description: Modèle introuvable ou n'appartenant pas à l'espace de travail
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'422':
description: >-
L'adresse e-mail du destinataire est suspendue (rejet précédent ou
signalée comme spam) et l'envoi est impossible
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableEntityError'
'429':
$ref: '#/components/responses/RateLimitError'
'500':
description: >-
Erreur serveur inattendue. Toute demande de signature partiellement
créée est annulée, donc aucun brouillon n'est laissé derrière. Les
échecs actionnables côté client lors de l'étape d'envoi renvoient
plutôt 400, 402 ou 422.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
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.createAndSendSigningRequest({
"name": "Employment Contract - John Doe",
"description": "Full-time employment contract",
"document": "JVBERi0xLjQKJeLjz9MK...",
"expiration_hours": 168,
"recipients": [
{
"id": "temp_signer_1",
"first_name": "John",
"last_name": "Doe",
"email": "john.doe@example.com",
"designation": "Signer",
"order": 1,
"phone_number": "+1-555-0123",
"company": "Acme Corp",
"title": "Software Engineer"
}
],
"fields": [
{
"recipient_id": "temp_signer_1",
"type": "signature",
"page": 1,
"x": 100,
"y": 500,
"width": 200,
"height": 50
},
{
"recipient_id": "temp_signer_1",
"type": "text",
"page": 1,
"x": 100,
"y": 400,
"width": 150,
"height": 30,
"variable_name": "phone_number",
"required": true,
"read_only": true
}
],
"settings": {
"use_signing_order": true,
"send_signing_email": true
}
});
console.log(response);
components:
schemas:
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
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
CreateAndSendResponse:
type: object
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
status:
type: string
enum:
- sent
description: Toujours 'sent' pour ce endpoint
document_url:
type: string
format: uri
description: URL signée pour accéder au document
page_count:
type: integer
description: Nombre de pages du document
expiration_hours:
type: integer
description: Nombre d'heures avant expiration
settings:
$ref: '#/components/schemas/SigningRequestSettings'
created_date:
type: string
format: date-time
sent_date:
type: string
format: date-time
description: Date d'envoi de la demande
template_id:
type: string
format: uuid
nullable: true
first_signer:
type: object
description: Détails du premier signataire ayant reçu l'email
properties:
id:
type: string
format: uuid
name:
type: string
email:
type: string
format: email
signing_link:
type: string
format: uri
description: Lien direct pour que le signataire accède à la vue de signature
recipients:
type: array
description: Tous les destinataires avec leurs véritables UUID
items:
type: object
properties:
id:
type: string
format: uuid
first_name:
type: string
last_name:
type: string
nullable: true
name:
type: string
email:
type: string
format: email
designation:
type: string
order:
type: integer
fields:
type: array
description: Tous les champs avec les véritables UUID de destinataire
items:
$ref: '#/components/schemas/Field'
credits_remaining:
type: integer
description: Crédits restants pour l'entreprise après déduction
description: Demande de signature créée et envoyée
required:
- id
- name
- status
CreateAndSendValidationError:
type: object
properties:
error:
type: string
code:
type: string
description: Code d'erreur exploitable par une machine
example: VALIDATION_ERROR
phase:
type: string
enum:
- create_validation
- send_validation
description: Quelle phase de validation a échoué
validation_errors:
type: array
description: Erreurs de validation détaillées pour la phase d'envoi
items:
type: object
properties:
recipient_index:
type: integer
description: Index du destinataire (base 1)
recipient_email:
type: string
missing_fields:
type: array
items:
type: string
description: Liste des champs requis manquants
description: Erreur de validation lors du create-and-send
required:
- error
- code
InsufficientCreditsError:
type: object
properties:
error:
type: string
example: >-
Insufficient credits. Please purchase more credits to send signing
requests.
code:
type: string
example: INSUFFICIENT_CREDITS
current_credits:
type: integer
example: 0
description: Erreur de crédits insuffisants
required:
- error
- code
- current_credits
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
UnprocessableEntityError:
type: object
properties:
error:
type: string
example: A recipient's email address cannot receive messages.
code:
type: string
example: RECIPIENT_EMAIL_SUPPRESSED
description: Erreur d'entité non traitable
required:
- error
- code
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é.
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'
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
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.
````