> ## 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.39.01/openapi-v01.39.01.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 ``` **En-tête X-Firma-Deprecation** : Certaines opérations de création de cachet et de mise à jour d'image renvoient un en-tête de réponse `X-Firma-Deprecation` lorsqu'elles sont appelées via l'edge gateway, indiquant que l'opération doit être effectuée sur l'hôte principal de l'API. **Documents multiples (API 01.39.00, activation requise)** : un modèle ou une demande de signature peut contenir jusqu'à 20 documents. Les routes de la sous-ressource `/documents` et les clés `documents`, `documents_version` et `documents_layout_version` ne sont servies qu'aux entreprises activées pour les documents multiples ; pour toute autre entreprise, les routes répondent `404 NOT_FOUND` et les clés sont absentes. **Cachets de modèle à la création (API 01.39.01)** : créer une demande de signature à partir d'un modèle avec `POST /signing-requests` ou `POST /signing-requests/create-and-send` hérite désormais des participants de cachet du modèle, et des champs du modèle qui leur appartiennent, lorsque `seal_participants` est absent ou vaut `null`. Cela change le comportement de v1 sans changement de version ; envoyez `seal_participants: []` pour créer la demande sans cachets. `POST /templates/{id}/duplicate` reporte aussi les participants de cachet du modèle ; consultez cette opération pour voir en quoi cela diffère pour les entreprises activées pour les documents multiples. `GET /templates/{id}` renvoie `seal_participants`, et `POST /templates` répond `warnings` lorsque son corps contient des clés qu'il ignore. version: 01.39.01 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: Organization Seals description: >- Gestion des cachets d'organisation : créer, mettre à jour, révoquer et effacer les cachets appliqués aux demandes de signature - 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: required: true content: application/json: schema: 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 est extrait automatiquement. Pour les documents de plus de 5 Mo, utilisez POST /documents et transmettez le document_id à la place. 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: allOf: - $ref: '#/components/schemas/Field' - type: object properties: seal_attribute: type: string enum: - display_name - signatory_title - null nullable: true description: >- Quel texte affiche un champ de texte propre à un cachet : le nom d'affichage du cachet (`display_name`) ou la fonction du signataire (`signatory_title`). Il s'applique à un champ détenu par un participant de cachet (un champ avec `seal_participant_temp_id`, ou un champ de modèle qui appartient à un participant de cachet) et est ignoré sur tout autre champ. Il est stocké sur le champ sous la forme `format_rules.sealAttribute` ; sur une demande basée sur un modèle, il remplace le `sealAttribute` que porte le champ du modèle et laisse inchangé le reste des `format_rules` du champ du modèle. Toute autre valeur répond 400 `VALIDATION_ERROR` ; cette vérification s'applique à chaque champ du corps, qu'un cachet le détienne ou non. 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 language: type: string nullable: true enum: - en - es - it - pt - fr - de - el - ru - pl - cs - sv - nl - ro - nb - ca description: >- Langue facultative des e-mails pour cette demande de signature. Lorsqu'elle est définie, tous les e-mails destinés au signataire (et le format de date) l'utilisent. Omettez-la ou utilisez null pour revenir à la langue par défaut de l'espace de travail, puis de l'entreprise (comportement inchangé). completion_title: type: string nullable: true description: >- Titre affiché sur la page de finalisation après la signature. Hérite de l'espace de travail, puis de l'entreprise, lorsqu'il est omis ou null. maxLength: 200 completion_message: type: string nullable: true description: >- Texte principal affiché sur la page de finalisation après la signature. Hérite de l'espace de travail, puis de l'entreprise, lorsqu'il est omis ou null. maxLength: 1000 completion_redirect_url: type: string format: uri nullable: true description: >- URL vers laquelle le signataire est redirigé depuis la page de finalisation. Doit utiliser https:// (http://localhost et http://127.0.0.1 sont également acceptés sur les demandes de signature en mode test). Hérite de l'espace de travail, puis de l'entreprise, lorsqu'elle est omise ou null. maxLength: 2000 completion_redirect_delay: type: integer nullable: true description: >- Secondes d'attente de la page de finalisation avant redirection (0 redirige immédiatement). S'applique uniquement lorsqu'une URL de redirection est résolue ; la page utilise 5 secondes lorsqu'aucun niveau ne définit de délai. Hérite de l'espace de travail, puis de l'entreprise, lorsqu'il est omis ou null. minimum: 0 maximum: 30 seal_participants: type: array items: $ref: '#/components/schemas/SealParticipantInput' description: >- Participants de cachet d'organisation à inclure dans la séquence de signature. `null` est traité comme une clé absente ; toute autre valeur qui n'est pas un tableau répond 400 `VALIDATION_ERROR`. Les valeurs `order` des cachets et les valeurs `order` des destinataires doivent former une seule séquence contiguë commençant à 1 : un trou répond 400 `INVALID_SIGNING_ORDER`, deux d'entre eux (destinataires ou cachets) qui partagent un `order` répondent 400 `SEAL_ORDER_COLLISION`, et chaque destinataire a besoin d'un `order` lorsqu'un cachet est présent. Un tableau non vide exige que les cachets d'organisation soient activés ; sinon l'appel répond 503 `SEALS_DISABLED`. nullable: true - 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. **Cachets.** Si le modèle a des participants de cachet et que `seal_participants` est absent ou vaut `null`, la demande les hérite, ainsi que les champs du modèle qui leur appartiennent. Un tableau, y compris `[]`, les remplace : les participants de cachet du modèle et leurs champs ne sont pas copiés. Tout autre type répond 400 `VALIDATION_ERROR`. Un cachet conservé et les destinataires sont renumérotés ensemble en une seule séquence d'ordre contiguë qui garde l'ordre relatif du modèle. Lorsque le modèle n'a pas de destinataires propres, les cachets hérités sont placés après les destinataires de la demande. Un cachet de modèle suit la version courante de sa lignée : la demande rattache la version courante, et non la version vers laquelle pointe le modèle. Si cette version courante est révoquée ou supprimée, ou si la lignée n'a pas de version courante, l'appel répond 409 `SEAL_UNAVAILABLE` et ne crée rien. Un cachet de modèle que l'entreprise de la clé API ne peut pas voir, ou dont la version courante est limitée à un espace de travail autre que celui de la clé API, n'est pas copié, et ses champs non plus ; la demande est tout de même créée et `seal_participants` liste le cachet comme une entrée écartée (`dropped: true`). Si un cachet devait être conservé alors que les cachets d'organisation ne sont pas activés, l'appel répond 503 `SEALS_DISABLED`. 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. Les destinataires dont la designation est CC ne sont jamais associés aux utilisateurs du modèle ; ils sont ajoutés comme destinataires en copie (CC). Les destinataires en copie (CC) du modèle sont copiés dans la demande de signature, en ignorant ceux dont l'adresse e-mail correspond, sans distinction entre majuscules et minuscules, à celle d'un destinataire en copie (CC) de la demande. fields: type: array items: allOf: - $ref: '#/components/schemas/Field' - type: object properties: seal_attribute: type: string enum: - display_name - signatory_title - null nullable: true description: >- Quel texte affiche un champ de texte propre à un cachet : le nom d'affichage du cachet (`display_name`) ou la fonction du signataire (`signatory_title`). Il s'applique à un champ détenu par un participant de cachet (un champ avec `seal_participant_temp_id`, ou un champ de modèle qui appartient à un participant de cachet) et est ignoré sur tout autre champ. Il est stocké sur le champ sous la forme `format_rules.sealAttribute` ; sur une demande basée sur un modèle, il remplace le `sealAttribute` que porte le champ du modèle et laisse inchangé le reste des `format_rules` du champ du modèle. Toute autre valeur répond 400 `VALIDATION_ERROR` ; cette vérification s'applique à chaque champ du corps, qu'un cachet le détienne ou non. 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 language: type: string nullable: true enum: - en - es - it - pt - fr - de - el - ru - pl - cs - sv - nl - ro - nb - ca description: >- Langue facultative des e-mails pour cette demande de signature. Lorsqu'elle est définie, tous les e-mails destinés au signataire (et le format de date) l'utilisent. Omettez-la ou utilisez null pour revenir à la langue par défaut de l'espace de travail, puis de l'entreprise (comportement inchangé). completion_title: type: string nullable: true description: >- Titre affiché sur la page de finalisation après la signature. Se rabat sur la valeur du modèle, puis sur les valeurs par défaut de l'espace de travail et de l'entreprise, lorsqu'il est omis ou null. maxLength: 200 completion_message: type: string nullable: true description: >- Texte principal affiché sur la page de finalisation après la signature. Se rabat sur la valeur du modèle, puis sur les valeurs par défaut de l'espace de travail et de l'entreprise, lorsqu'il est omis ou null. maxLength: 1000 completion_redirect_url: type: string format: uri nullable: true description: >- URL vers laquelle le signataire est redirigé depuis la page de finalisation. Doit utiliser https:// (http://localhost et http://127.0.0.1 sont également acceptés sur les demandes de signature en mode test). Se rabat sur la valeur du modèle, puis sur les valeurs par défaut de l'espace de travail et de l'entreprise, lorsqu'elle est omise ou null. maxLength: 2000 completion_redirect_delay: type: integer nullable: true description: >- Secondes d'attente de la page de finalisation avant redirection (0 redirige immédiatement). S'applique uniquement lorsqu'une URL de redirection est résolue ; la page utilise 5 secondes lorsqu'aucun niveau ne définit de délai. Se rabat sur la valeur du modèle, puis sur les valeurs par défaut de l'espace de travail et de l'entreprise, lorsqu'il est omis ou null. minimum: 0 maximum: 30 seal_participants: type: array items: $ref: '#/components/schemas/SealParticipantInput' description: >- Participants de cachet d'organisation pour la nouvelle demande de signature : avec `template_id`, omettez la clé ou envoyez `null` pour hériter des cachets du modèle, envoyez `[]` pour n'avoir aucun cachet, ou envoyez un tableau pour les remplacer. Un cachet de modèle remplacé et ses champs ne sont pas copiés. Tout autre type répond 400 `VALIDATION_ERROR`. Sur une demande basée sur un modèle, les ordres des cachets et les ordres des destinataires sont renumérotés ensemble en une seule séquence contiguë, que les cachets soient hérités ou envoyés dans le tableau. Un tableau non vide, ou un cachet hérité qui serait conservé, exige que les cachets d'organisation soient activés ; sinon l'appel répond 503 `SEALS_DISABLED`. nullable: true 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 - type: object required: - document_ids description: >- Créer une demande de signature à partir de plusieurs documents téléversés (multi-documents, activation requise) properties: document_ids: type: array minItems: 1 maxItems: 20 items: type: string format: uuid description: >- Identifiants de téléversement temporaire de POST /documents, dans l'ordre des documents, pour créer une demande de signature multi-documents (activation requise). Exactement un parmi document, document_id, document_ids ou template_id (`400 CONFLICTING_DOCUMENT_SOURCE`) ; un identifiant répété répond `400 DUPLICATE_DOCUMENT_ID`, plus de 20 `400 MAX_DOCUMENTS_EXCEEDED`, un téléversement inconnu ou expiré `400 DOCUMENT_UPLOAD_NOT_FOUND`, un ensemble de plus de 100 Mo `413 DOCUMENT_SET_TOO_LARGE` ; plus d'un identifiant pour une entreprise non activée répond `409 MULTI_DOCUMENT_READ_ONLY`. 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: allOf: - $ref: '#/components/schemas/Field' - type: object properties: seal_attribute: type: string enum: - display_name - signatory_title - null nullable: true description: >- Quel texte affiche un champ de texte propre à un cachet : le nom d'affichage du cachet (`display_name`) ou la fonction du signataire (`signatory_title`). Il s'applique à un champ détenu par un participant de cachet (un champ avec `seal_participant_temp_id`, ou un champ de modèle qui appartient à un participant de cachet) et est ignoré sur tout autre champ. Il est stocké sur le champ sous la forme `format_rules.sealAttribute` ; sur une demande basée sur un modèle, il remplace le `sealAttribute` que porte le champ du modèle et laisse inchangé le reste des `format_rules` du champ du modèle. Toute autre valeur répond 400 `VALIDATION_ERROR` ; cette vérification s'applique à chaque champ du corps, qu'un cachet le détienne ou non. 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 language: type: string nullable: true enum: - en - es - it - pt - fr - de - el - ru - pl - cs - sv - nl - ro - nb - ca description: >- Langue facultative des e-mails pour cette demande de signature. Lorsqu'elle est définie, tous les e-mails destinés au signataire (et le format de date) l'utilisent. Omettez-la ou utilisez null pour revenir à la langue par défaut de l'espace de travail, puis de l'entreprise (comportement inchangé). completion_title: type: string nullable: true description: >- Titre affiché sur la page de finalisation après la signature. Hérite de l'espace de travail, puis de l'entreprise, lorsqu'il est omis ou null. maxLength: 200 completion_message: type: string nullable: true description: >- Texte principal affiché sur la page de finalisation après la signature. Hérite de l'espace de travail, puis de l'entreprise, lorsqu'il est omis ou null. maxLength: 1000 completion_redirect_url: type: string format: uri nullable: true description: >- URL vers laquelle le signataire est redirigé depuis la page de finalisation. Doit utiliser https:// (http://localhost et http://127.0.0.1 sont également acceptés sur les demandes de signature en mode test). Hérite de l'espace de travail, puis de l'entreprise, lorsqu'elle est omise ou null. maxLength: 2000 completion_redirect_delay: type: integer nullable: true description: >- Secondes d'attente de la page de finalisation avant redirection (0 redirige immédiatement). S'applique uniquement lorsqu'une URL de redirection est résolue ; la page utilise 5 secondes lorsqu'aucun niveau ne définit de délai. Hérite de l'espace de travail, puis de l'entreprise, lorsqu'il est omis ou null. minimum: 0 maximum: 30 seal_participants: type: array items: $ref: '#/components/schemas/SealParticipantInput' description: >- Participants de cachet d'organisation à inclure dans la séquence de signature. `null` est traité comme une clé absente ; toute autre valeur qui n'est pas un tableau répond 400 `VALIDATION_ERROR`. Les valeurs `order` des cachets et les valeurs `order` des destinataires doivent former une seule séquence contiguë commençant à 1 : un trou répond 400 `INVALID_SIGNING_ORDER`, deux d'entre eux (destinataires ou cachets) qui partagent un `order` répondent 400 `SEAL_ORDER_COLLISION`, et chaque destinataire a besoin d'un `order` lorsqu'un cachet est présent. Un tableau non vide exige que les cachets d'organisation soient activés ; sinon l'appel répond 503 `SEALS_DISABLED`. nullable: true properties: seal_participants: type: array items: $ref: '#/components/schemas/SealParticipantInput' description: >- Participants de cachet d'organisation pour la nouvelle demande de signature : avec `template_id`, omettez la clé ou envoyez `null` pour hériter des cachets du modèle, envoyez `[]` pour n'avoir aucun cachet, ou envoyez un tableau pour les remplacer. Un cachet de modèle remplacé et ses champs ne sont pas copiés. Tout autre type répond 400 `VALIDATION_ERROR`. Sur une demande basée sur un modèle, les ordres des cachets et les ordres des destinataires sont renumérotés ensemble en une seule séquence contiguë, que les cachets soient hérités ou envoyés dans le tableau. Un tableau non vide, ou un cachet hérité qui serait conservé, exige que les cachets d'organisation soient activés ; sinon l'appel répond 503 `SEALS_DISABLED`. nullable: true fields: type: array items: allOf: - $ref: '#/components/schemas/Field' - type: object properties: seal_participant_temp_id: type: string description: >- ID temporaire du participant de cachet auquel ce champ est affecté (correspond à temp_id dans le tableau seal_participants) seal_attribute: type: string enum: - display_name - signatory_title - null nullable: true description: >- Quel texte affiche un champ de texte propre à un cachet : le nom d'affichage du cachet (`display_name`) ou la fonction du signataire (`signatory_title`). Il s'applique à un champ détenu par un participant de cachet (un champ avec `seal_participant_temp_id`, ou un champ de modèle qui appartient à un participant de cachet) et est ignoré sur tout autre champ. Il est stocké sur le champ sous la forme `format_rules.sealAttribute` ; sur une demande basée sur un modèle, il remplace le `sealAttribute` que porte le champ du modèle et laisse inchangé le reste des `format_rules` du champ du modèle. Toute autre valeur répond 400 `VALIDATION_ERROR` ; cette vérification s'applique à chaque champ du corps, qu'un cachet le détienne ou non. properties: seal_participant_temp_id: type: string description: >- ID temporaire du participant de cachet auquel ce champ est affecté (correspond à temp_id dans le tableau seal_participants) seal_attribute: type: string enum: - display_name - signatory_title - null nullable: true description: >- Quel texte affiche un champ de texte propre à un cachet : le nom d'affichage du cachet (`display_name`) ou la fonction du signataire (`signatory_title`). Il s'applique à un champ détenu par un participant de cachet (un champ avec `seal_participant_temp_id`, ou un champ de modèle qui appartient à un participant de cachet) et est ignoré sur tout autre champ. Il est stocké sur le champ sous la forme `format_rules.sealAttribute` ; sur une demande basée sur un modèle, il remplace le `sealAttribute` que porte le champ du modèle et laisse inchangé le reste des `format_rules` du champ du modèle. Toute autre valeur répond 400 `VALIDATION_ERROR` ; cette vérification s'applique à chaque champ du corps, qu'un cachet le détienne ou non. description: Champs à placer sur le document 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 responses: '201': description: >- Demande de signature créée avec succès. La réponse peut inclure des avertissements non bloquants liés aux e-mails ou aux balises d'ancrage. 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': description: >- Entrée invalide - vous devez fournir soit 'document' soit 'template_id', pas les deux. Le document doit être un PDF valide encodé en base64 sous 6 Mo de charge utile de requête (~4,5 Mo bruts). Multi-documents : `CONFLICTING_DOCUMENT_SOURCE`, `DUPLICATE_DOCUMENT_ID`, `MAX_DOCUMENTS_EXCEEDED`, `DOCUMENT_UPLOAD_NOT_FOUND`, `ANCHOR_DOCUMENT_REQUIRED`. Cachets d'organisation : `VALIDATION_ERROR` lorsque `seal_participants` n'est ni un tableau ni `null`, lorsque l'une de ses entrées n'a pas de `temp_id`, répète un `temp_id` ou a un `order` qui n'est pas un entier positif, ou lorsque le `seal_attribute` d'un champ n'est ni `display_name`, ni `signatory_title`, ni `null` ; `SEAL_UNAVAILABLE` lorsqu'une entrée omet `seal_id` et que ni l'espace de travail ni l'entreprise n'ont de cachet par défaut actif ; sur une demande basée sur un document avec des participants de cachet, `INVALID_SIGNING_ORDER` lorsqu'un destinataire n'a pas d'`order` ou que les destinataires et les cachets ne forment pas une seule séquence commençant à 1, et `SEAL_ORDER_COLLISION` lorsque deux d'entre eux (destinataires ou cachets) partagent un `order`. 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 '401': $ref: '#/components/responses/UnauthorizedError' '403': description: >- Le modèle n'est pas dans l'espace de travail de la clé API (`INVALID_TEMPLATE`). content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: >- Le modèle est introuvable ; un modèle hors de l'espace de travail de la clé API peut aussi répondre 404 au lieu de 403. Un cachet désigné dans `seal_participants` n'existe pas, appartient à une autre entreprise ou est limité à un autre espace de travail (`NOT_FOUND`). content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: >- Conflit : `SEAL_UNAVAILABLE` (un cachet désigné dans `seal_participants` est révoqué ou supprimé, ou n'est pas la version courante de sa lignée ; ou la version courante d'un cachet de modèle hérité est révoquée ou supprimée, ou ce cachet n'a pas de version courante), `MULTI_DOCUMENT_READ_ONLY`, `DOCUMENT_SET_BUSY`, `DOCUMENT_SET_INCONSISTENT`, `DOCUMENT_SET_VERSION_CONFLICT`, `DOCUMENT_SET_DISPATCH_STALE` content: application/json: schema: anyOf: - $ref: '#/components/schemas/MultiDocumentError' - allOf: - $ref: '#/components/schemas/Error' - type: object required: - error - code properties: code: type: string enum: - SEAL_UNAVAILABLE '413': description: DOCUMENT_SET_TOO_LARGE content: application/json: schema: $ref: '#/components/schemas/MultiDocumentError' '429': $ref: '#/components/responses/RateLimitError' '503': description: >- Le traitement des balises d'ancrage est désactivé sur la route de repli périphérique (`ANCHOR_DISABLED_EDGE`) : réessayez par la route principale de l'API. Ou les cachets d'organisation ne sont pas activés et soit `seal_participants` est un tableau non vide (répondu avant la vérification de ses entrées), soit l'héritage du modèle conserve au moins un cachet (`SEALS_DISABLED`). content: application/json: schema: type: object required: - error - code properties: error: type: string code: type: string enum: - ANCHOR_DISABLED_EDGE - SEALS_DISABLED 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: 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. Un destinataire dont la designation est CC n'est jamais associé à un utilisateur du modèle ; il est ajouté comme destinataire en copie (CC), et les destinataires en copie (CC) du modèle sont copiés dans la demande de signature, en ignorant ceux dont l'adresse e-mail correspond, sans distinction entre majuscules et minuscules, à celle d'un destinataire en copie (CC) de la demande. **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. Un destinataire existant ne peut pas passer de CC à Signataire/Approbateur, ni inversement (400) ; supprimez-le et recréez-le. 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. Non utilisé pour les destinataires en copie (CC), qui ne sont jamais associés à un utilisateur 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 }. Les champs textuels (text, textarea, email, name, phone, company, title, number, dropdown, url, date) acceptent en plus une propriété facultative fontSize (entier en px, 8-48, bornée) — voir TextFormatRules. 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' seal_participant_temp_id: type: string nullable: true description: >- ID temporaire du participant de cachet auquel ce champ est affecté (correspond à temp_id dans le tableau seal_participants). Utilisé lors de la création pour lier des champs aux participants de cachet définis dans la même requête. AnchorTag: type: object additionalProperties: false 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 supprimer le texte d'ancrage en utilisant une géométrie de glyphes corrigée et une suppression de texte au sous-pixel. Par défaut true. add_white_background: type: boolean default: false description: >- Indique s'il faut dessiner un fond blanc sur l'ensemble du rectangle du champ résolu. Indépendant de la suppression du texte d'ancrage. 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' font_size: type: integer minimum: 8 maximum: 48 description: >- Taille de police initiale/maximale facultative en pixels pour les types de champs textuels, enregistrée sur le champ résolu sous format_rules.fontSize (voir TextFormatRules). Le texte se réduit automatiquement pour tenir dans le cadre du champ. Omettez-la pour un dimensionnement automatique. Les valeurs hors de la plage 8-48 sont ramenées à cette plage ; les valeurs non numériques sont ignorées. example: 12 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 document_index: type: integer minimum: 1 description: >- Index (à partir de 1) dans `document_ids` du document dans lequel cette balise est recherchée. Facultatif avec un seul document (1 par défaut) ; obligatoire avec plusieurs (`400 ANCHOR_DOCUMENT_REQUIRED`) ; une valeur hors limites répond `400 VALIDATION_ERROR`. 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 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 ou 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 ; `null` hérite du paramètre de l'espace de travail ou de l'entreprise. 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ésactive la modification. Lorsqu'il est défini, une boîte de dialogue de confirmation permet aux signataires de modifier les champs indiqués. notify_identity_change_email: type: boolean default: false description: >- Envoie une notification par e-mail quand un signataire modifie son identité. SealParticipantInput: type: object required: - temp_id - order description: >- Un participant de cachet d'organisation d'une nouvelle demande de signature : un élément de `seal_participants` sur `POST /signing-requests` et `POST /signing-requests/create-and-send`. properties: seal_id: type: string format: uuid description: >- ID du cachet d'organisation à appliquer ; omettez-le pour utiliser le cachet par défaut de l'espace de travail ou, lorsque celui-ci n'en a pas, celui de l'entreprise. L'appel répond 400 `SEAL_UNAVAILABLE` lorsqu'aucun des deux n'existe. order: type: integer minimum: 1 description: Position dans la séquence de signature temp_id: type: string description: >- ID temporaire de ce participant de cachet, obligatoire et unique dans `seal_participants` ; les champs de la même demande le nomment dans `seal_participant_temp_id`. 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 non bloquants, incluant des formats d'e-mail de destinataire inhabituels, des propriétés de balise d'ancrage inconnues pendant la fenêtre de compatibilité et des avertissements de traitement des ancrages. seal_participants: type: array description: >- Participants de cachet d'organisation dans l'ordre de signature. Vide lorsque la demande n'a pas de cachet. Chaque élément est soit un participant de cachet persisté (`dropped: false`), soit, sur une demande basée sur un modèle, une entrée pour un cachet de modèle qui n'a pas été copié parce que l'entreprise de la clé API ne peut pas voir le cachet ou parce que le cachet est limité à un autre espace de travail (`dropped: true`, `id` et `order` null, `seal_out_of_scope: true`). Les entrées écartées viennent après les entrées persistées, dans l'ordre du modèle. Les cachets de modèle qu'un tableau `seal_participants` explicite a remplacés ne sont pas listés. items: oneOf: - $ref: '#/components/schemas/SealParticipantCreated' - $ref: '#/components/schemas/SealParticipantDropped' required: - id - name - status Error: type: object properties: error: type: string description: Message d'erreur lisible par un humain code: type: string description: >- Code d'erreur lisible par machine. Codes liés aux cachets : SEALS_DISABLED, SEAL_ALREADY_REVOKED, SEAL_CREATION_DISABLED_EDGE, SEAL_ERASE_NOT_ELIGIBLE, SEAL_IMAGE_INVALID, SEAL_MUTATION_NOT_ALLOWED, SEAL_NOT_FOUND, SEAL_NO_IMAGE_FIELD, SEAL_ORDER_COLLISION, SEAL_PAUSED, SEAL_SCOPE_FORBIDDEN, SEAL_UNAVAILABLE Codes multi-documents : voir MultiDocumentErrorCode (41 codes). errors: type: array description: >- Toutes les erreurs de validation lorsque plusieurs échecs sont signalés ensemble. L'erreur de premier niveau répète le premier élément pour la rétrocompatibilité. items: type: object required: - message properties: message: type: string 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 description: >- Codes d'erreur des cachets d'organisation : SEALS_DISABLED, SEAL_ALREADY_REVOKED, SEAL_CREATION_DISABLED_EDGE, SEAL_ERASE_NOT_ELIGIBLE, SEAL_IMAGE_INVALID, SEAL_MUTATION_NOT_ALLOWED, SEAL_NOT_FOUND, SEAL_NO_IMAGE_FIELD, SEAL_ORDER_COLLISION, SEAL_PAUSED, SEAL_SCOPE_FORBIDDEN, SEAL_UNAVAILABLE MultiDocumentError: description: Une erreur renvoyée par une route multi-documents. allOf: - $ref: '#/components/schemas/Error' - type: object required: - error - code properties: code: $ref: '#/components/schemas/MultiDocumentErrorCode' 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 fontSize: type: integer minimum: 8 maximum: 48 description: >- Taille de police initiale/maximale facultative en pixels pour la valeur du champ affichée. Le texte se réduit automatiquement pour tenir dans le cadre du champ. Omettez-la pour un dimensionnement automatique. Les valeurs hors de la plage 8-48 sont ramenées à cette plage. 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 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 SealParticipantCreated: description: >- Un participant de cachet persisté du nouveau document : toutes les clés de SealParticipantApi, plus `dropped: false`. allOf: - $ref: '#/components/schemas/SealParticipantApi' - type: object required: - dropped properties: dropped: type: boolean enum: - false SealParticipantDropped: type: object description: >- Un cachet de modèle qui n'a pas été copié dans la nouvelle demande de signature ou le nouveau modèle parce qu'il n'y est pas disponible : l'entreprise de la clé ne peut pas voir le cachet, ou le cachet est limité à un espace de travail autre que l'espace de travail cible. Les champs qui appartiennent au cachet n'ont pas non plus été copiés. `seal` est le résumé de la version courante du cachet, ou null lorsque le cachet n'est pas visible pour l'entreprise de la clé. required: - id - order - seal - seal_out_of_scope - dropped properties: id: type: string nullable: true enum: - null description: 'Toujours null : aucun participant n''a été créé.' order: type: integer nullable: true enum: - null description: 'Toujours null : aucun participant n''a été créé.' seal: type: object nullable: true description: >- Résumé de la version courante du cachet ; null lorsque l'entreprise de la clé API ne peut pas voir le cachet. required: - id - lineage_id - name - version - display_name properties: id: type: string format: uuid lineage_id: type: string format: uuid description: Partagé entre les versions du même cachet name: type: string version: type: integer display_name: type: string seal_out_of_scope: type: boolean enum: - true dropped: type: boolean enum: - true MultiDocumentErrorCode: type: string enum: - ALREADY_CANCELLED - ALREADY_FINISHED - ALREADY_SENT - ANCHOR_DOCUMENT_REQUIRED - ANCHOR_MISMATCH - CONFLICTING_DOCUMENT_SOURCE - DIMENSION_MISMATCH - DOCUMENTS_LAYOUT_VERSION_REQUIRED - DOCUMENT_CANDIDATE_EXPIRED - DOCUMENT_NOT_FOUND - DOCUMENT_ORIGINAL_NOT_AVAILABLE - DOCUMENT_SET_BUSY - DOCUMENT_SET_DISPATCH_STALE - DOCUMENT_SET_INCONSISTENT - DOCUMENT_SET_LOCKED - DOCUMENT_SET_TOO_LARGE - DOCUMENT_SET_VERSION_CONFLICT - DOCUMENT_SIGNED_NOT_AVAILABLE - DOCUMENT_UPLOAD_NOT_FOUND - DUPLICATE_DOCUMENT_ID - FENCE_COLUMN_PROTECTED - INSUFFICIENT_CREDITS - INTERNAL - INTERNAL_ERROR - INVALID_DOCUMENT_ORDER - INVALID_SIGNING_ORDER - MAX_DOCUMENTS_EXCEEDED - MIN_DOCUMENTS_REQUIRED - MULTI_DOCUMENT_READ_ONLY - MULTI_DOCUMENT_REPLACE_UNSUPPORTED - NOT_FOUND - PAGE_COUNT_MISMATCH - PARTICIPANTS_CHANGED - RATE_LIMIT_EXCEEDED - SEAL_MUTATION_NOT_ALLOWED - SEND_EFFECTS_EXIST - SEND_IN_PROGRESS - SIGNED_DATA_IMMUTABLE - SIGNING_ORDER_LOCKED_APPLIED - SIGNING_ORDER_LOCKED_SENDING - SIGNING_ORDER_LOCKED_SENT - VALIDATION_ERROR description: >- Codes d'erreur du contrat multi-documents et des routes qu'il modifie (générés à partir des lignes de la matrice d'erreurs exposées par l'API). Une véritable erreur serveur répond 500 avec INTERNAL_ERROR sur les routes historiques et INTERNAL sur les chemins HttpError partagés (répartition multi-documents, table des statuts RPC, routes de l'ensemble de documents) ; aucun des deux ne contient de détail. 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. SealParticipantApi: type: object description: >- Participant de cachet tel que l'API le renvoie sur une demande de signature ou un modèle. Toutes les clés sont toujours présentes ; les clés nullables valent null lorsqu'elles ne sont pas définies. required: - id - order - seal - status - applied_at - paused_at - pause_reason - swapped_from_seal_id - triggered_by_recipient_id - sender_kind - seal_out_of_scope properties: id: type: string format: uuid order: type: integer minimum: 1 description: >- Position dans l'ordre de signature, partagée avec l'espace d'ordre des destinataires. seal: type: object description: Le cachet d'organisation appliqué par ce participant. required: - id - lineage_id - name - version - display_name properties: id: type: string format: uuid lineage_id: type: string format: uuid description: Partagé entre les versions du même cachet name: type: string version: type: integer display_name: type: string status: type: string enum: - pending - paused - applied description: >- applied lorsque applied_at est défini, sinon paused lorsque paused_at est défini, sinon pending. applied_at: type: string format: date-time nullable: true paused_at: type: string format: date-time nullable: true pause_reason: type: string nullable: true enum: - seal_revoked_stop_pending - seal_integrity_mismatch - null swapped_from_seal_id: type: string format: uuid nullable: true triggered_by_recipient_id: type: string format: uuid nullable: true description: Le destinataire dont l'action a appliqué le cachet. sender_kind: type: string nullable: true enum: - dashboard - api_key - embedded - null seal_out_of_scope: type: boolean description: >- Vrai lorsque le cachet appartient à un espace de travail autre que celui de la demande de signature ou du modèle. 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. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.