> ## 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.39.01/openapi-v01.39.01.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 ``` **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/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. Pour les documents de plus de 5 Mo, utilisez POST /documents et transmettez le document_id à la place. example: >- JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PC9UeXBlIC9QYWdlCi9QYXJlbnQgMSAwIFIKL1Jlc291c... template_id: type: string format: uuid description: >- ID du modèle à utiliser (mutuellement exclusif avec document et document_id). **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`. 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. 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. 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 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. 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ésactive la modification. Lorsqu'il est défini, une boîte de dialogue de confirmation permet aux signataires de modifier les champs indiqué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 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 (lorsque template_id est utilisé), puis sur les valeurs par défaut de l'espace de travail et de l'entreprise. example: Thank you for signing 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 (lorsque template_id est utilisé), puis sur les valeurs par défaut de l'espace de travail et de l'entreprise. example: Your signed copy is on its way to your inbox. 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 (lorsque template_id est utilisé), puis sur les valeurs par défaut de l'espace de travail et de l'entreprise. example: https://example.com/thank-you 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 (lorsque template_id est utilisé), puis sur les valeurs par défaut de l'espace de travail et de l'entreprise. example: 5 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 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`. oneOf: - required: - document - required: - template_id - required: - document_ids 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. La réponse peut inclure des avertissements non bloquants liés 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/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 field_type: signature seal_participant_id: null credits_remaining: 99 '400': description: >- Erreur de validation - entrée invalide ou données de signataire obligatoires manquantes. 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`. À l'étape d'envoi, `SEAL_NO_IMAGE_FIELD` lorsqu'un participant de cachet de la demande ne détient aucun champ de type `stamp` (son champ tampon) : la demande n'est pas envoyée et aucune demande de signature n'est conservée. 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 seal-no-image-field: summary: >- Un participant de cachet n'a pas de champ tampon (image du cachet) value: error: >- Each organization seal needs at least one seal image field. code: SEAL_NO_IMAGE_FIELD '401': $ref: '#/components/responses/UnauthorizedError' '402': description: Crédits insuffisants content: application/json: schema: $ref: '#/components/schemas/InsufficientCreditsError' '404': description: >- Le modèle est introuvable ou n'est pas dans l'espace de travail de la clé API. 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`, `SEND_IN_PROGRESS`, `SEND_EFFECTS_EXIST`, `ALREADY_SENT`, `DOCUMENT_SET_BUSY`, `DOCUMENT_SET_INCONSISTENT`, `DOCUMENT_SET_VERSION_CONFLICT`, `DOCUMENT_SET_DISPATCH_STALE`. `SEND_EFFECTS_EXIST` et `ALREADY_SENT` peuvent aussi contenir `signing_request_id` : il est présent lorsque la demande de signature créée par cet appel a été conservée (son annulation a été refusée), vous devez donc récupérer cette demande au lieu de réessayer, car un nouvel essai crée une seconde demande ; sans lui, aucune demande n'a été conservée. content: application/json: schema: anyOf: - $ref: '#/components/schemas/CreateAndSendConflictError' - 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' '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' '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.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. 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 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`. 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`. 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 actifs de la nouvelle demande de signature, y compris les champs détenus par des participants de cachet. Chaque élément est l'enregistrement de champ stocké, et non la forme `Field` utilisée dans les requêtes : par exemple, le type de champ se trouve dans `field_type`, et un champ propre à un cachet n'a pas de destinataire et nomme son participant de cachet dans `seal_participant_id`. items: type: object additionalProperties: true 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' credits_remaining: type: integer description: Crédits restants pour l'entreprise après déduction warnings: type: array items: type: string description: >- Avertissements optionnels non bloquants, incluant des propriétés de balise d'ancrage inconnues pendant la fenêtre de compatibilité et des avertissements de traitement des ancrages. 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 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 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 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 CreateAndSendConflictError: description: >- Un 409 renvoyé par POST /signing-requests/create-and-send : un MultiDocumentError qui indique également la demande de signature créée par cet appel lorsque cette demande a été conservée (son annulation a été refusée avec `SEND_EFFECTS_EXIST` ou `ALREADY_SENT`). allOf: - $ref: '#/components/schemas/MultiDocumentError' - type: object properties: signing_request_id: type: string format: uuid description: >- Présent uniquement sur SEND_EFFECTS_EXIST et ALREADY_SENT lorsque la demande de signature créée par cet appel a été conservée (son annulation a été refusée) : son identifiant, afin que l'appelant puisse la récupérer au lieu de réessayer (une nouvelle tentative crée une deuxième demande). Absent lorsque la demande a été annulée. 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' 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 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é. 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. 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. 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.