> ## 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 un Modèle > Crée un nouveau modèle avec un document PDF encodé en base64. L'API extrait automatiquement le nombre de pages du document. `seal_participants`, `recipients` et `fields` ne sont pas des clés acceptées par cette opération : elles sont ignorées et rien n'est créé à partir d'elles. Lorsque le corps de la requête en contient une (la présence de la clé suffit, quelle que soit sa valeur, y compris `null` ou `[]`), la réponse 201 contient `warnings`, une chaîne par clé ignorée. Ajoutez des participants et des champs avec `PATCH /templates/{id}` ou `PUT /templates/{id}`. ## OpenAPI ````yaml api-reference/v01.39.01/openapi-v01.39.01.fr.json post /templates 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: /templates: post: tags: - Templates summary: Créer un Modèle description: >- Crée un nouveau modèle avec un document PDF encodé en base64. L'API extrait automatiquement le nombre de pages du document. `seal_participants`, `recipients` et `fields` ne sont pas des clés acceptées par cette opération : elles sont ignorées et rien n'est créé à partir d'elles. Lorsque le corps de la requête en contient une (la présence de la clé suffit, quelle que soit sa valeur, y compris `null` ou `[]`), la réponse 201 contient `warnings`, une chaîne par clé ignorée. Ajoutez des participants et des champs avec `PATCH /templates/{id}` ou `PUT /templates/{id}`. operationId: createTemplate requestBody: required: true content: application/json: schema: type: object required: - name properties: name: type: string maxLength: 255 description: Nom du modèle example: Employment Contract Template description: type: string description: Description du modèle example: Standard employment contract for new hires document: type: string format: byte description: >- Document PDF ou DOCX encodé en base64. Les fichiers DOCX sont automatiquement convertis en PDF. L'API extrait automatiquement le nombre de pages du document. Pour les documents de plus de 5 Mo, utilisez POST /documents et transmettez le document_id à la place. (mutuellement exclusif avec document_id et document_ids) example: >- JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PC9UeXBlIC9QYWdlCi9QYXJlbnQgMSAwIFIKL1Jlc291c... expiration_hours: type: integer description: Heures avant l'expiration de la demande de signature default: 168 example: 168 settings: type: object properties: allow_editing_before_sending: type: boolean default: false description: Autoriser la modification des champs avant l'envoi attach_pdf_on_finish: type: boolean default: true description: Joindre le PDF terminé à l'email de finalisation allow_download: type: boolean default: true description: Autoriser les destinataires à télécharger le document hand_drawn_only: type: boolean default: false description: >- Exiger des signataires qu'ils dessinent leur signature à la main plutôt que d'utiliser des signatures saisies require_otp_verification: type: boolean nullable: true default: null description: >- Exige que les signataires vérifient leur e-mail avec un code à usage unique ; `null` hérite du paramètre de l'espace de travail ou de l'entreprise. disable_guided_navigation: type: boolean nullable: true description: >- Désactiver 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 si null. document_id: type: string format: uuid description: >- ID d'un document précédemment téléversé (mutuellement exclusif avec document). À obtenir en appelant d'abord POST /documents. example: 123e4567-e89b-12d3-a456-426614174000 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 un modèle multi-documents (activation requise). Exactement un parmi document, document_id ou document_ids (`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`. responses: '201': description: Modèle créé avec succès headers: X-RateLimit-Limit: schema: type: integer description: 'Limite de taux : 120 requêtes par minute' X-RateLimit-Remaining: schema: type: integer X-RateLimit-Reset: schema: type: integer content: application/json: schema: $ref: '#/components/schemas/TemplateCreateResponse' '400': description: >- Requête Incorrecte - Échec de la validation. Multi-documents : `CONFLICTING_DOCUMENT_SOURCE`, `DUPLICATE_DOCUMENT_ID`, `MAX_DOCUMENTS_EXCEEDED`, `DOCUMENT_UPLOAD_NOT_FOUND` 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' '413': description: DOCUMENT_SET_TOO_LARGE content: application/json: schema: $ref: '#/components/schemas/MultiDocumentError' '429': $ref: '#/components/responses/RateLimitError' security: - ApiKeyAuth: [] x-codeSamples: - lang: TypeScript label: '@firma-dev/sdk' source: |- import { FirmaClient } from "@firma-dev/sdk"; const firma = new FirmaClient({ apiKey: "YOUR_API_KEY" }); const response = await firma.templates.createTemplate({ name: "Employment Contract Template", document: "JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PC9UeXBlIC9QYWdlCi9QYXJlbnQgMSAwIFIKL1Jlc291c..." }); console.log(response); components: schemas: TemplateCreateResponse: description: >- Le modèle créé : toutes les clés de Template, plus `warnings` lorsque le corps de la requête contenait des clés que cette opération ignore. allOf: - $ref: '#/components/schemas/Template' - type: object properties: warnings: type: array description: >- Présent uniquement lorsque le corps de la requête contenait `seal_participants`, `recipients` ou `fields` (la présence de la clé suffit, quelle que soit sa valeur, y compris `null` ou `[]`). Une chaîne par clé de ce type, dans l'ordre seal_participants, recipients, fields. items: type: string example: - >- seal_participants is not accepted on POST /templates and was ignored; add it with PATCH or PUT /templates/{id} 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' Template: type: object properties: id: type: string format: uuid description: Identifiant unique du modèle name: type: string description: Nom du modèle maxLength: 255 description: type: string description: Description du modèle nullable: true document_url: type: string format: uri description: >- URL pré-signée vers le document PDF. Il s'agit d'une URL signée à durée limitée pour un accès sécurisé, voir document_url_expires_at pour la date d'expiration. Les URL initiales sont valables 7 jours ; les URL rafraîchies sont valables 1 heure. Demandez une nouvelle récupération du modèle pour obtenir une URL fraîche si elle a expiré. document_url_expires_at: type: string format: date-time nullable: true description: >- Timestamp ISO 8601 auquel document_url expirera. Après cette heure, l'URL retournera une erreur d'accès refusé. Récupérez à nouveau le modèle pour recevoir une nouvelle URL signée. 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 des demandes de signature créées à partir de ce modèle credit_cost: type: integer minimum: 1 default: 1 description: >- Nombre de crédits consommés lorsqu'une demande de signature est envoyée à partir de ce modèle. La valeur minimale est 1. settings: $ref: '#/components/schemas/SigningRequestSettings' recipients: type: array items: $ref: '#/components/schemas/TemplateUser' description: >- Destinataires du modèle (inclus dans la récupération d'un seul modèle) fields: type: array items: $ref: '#/components/schemas/TemplateField' description: Champs du modèle (inclus dans la récupération d'un seul modèle) created_date: type: string format: date-time description: Timestamp de création du modèle updated_date: type: string format: date-time description: Timestamp de dernière mise à jour du modèle documents: type: array items: $ref: '#/components/schemas/DocumentSummary' description: >- Les documents du modèle dans l'ordre des positions (multi-documents ; présent uniquement pour les entreprises activées). Sur GET /templates (la liste) : une entrée de liste ne contient pas de `document_url`. Un élément dont l'ensemble de documents n'a jamais été modifié apparaît ici avec `documents: []`, tandis que son GET individuel renvoie son unique document (avec `document_id` null). Sur GET /templates/{id}, PUT /templates/{id} et POST /templates : un élément dont l'ensemble de documents n'a jamais été modifié renvoie son unique document, avec `document_id` null. documents_version: type: integer description: >- Version de l'ensemble de documents, incrémentée à chaque modification de document (multi-documents ; entreprises activées uniquement). documents_layout_version: type: integer description: >- Version de la mise en page des documents, incrémentée lorsque des documents sont ajoutés, supprimés ou réordonnés (multi-documents ; entreprises activées uniquement). Les écritures de champs sur une demande de signature comportant plus d'un document la renvoient sous la forme `documents_layout_version`. required: - id - name - created_date 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. 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é. TemplateUser: type: object properties: id: type: string format: uuid description: Identifiant unique de l'utilisateur du modèle name: type: string description: Nom du destinataire (prénom et nom combinés) email: type: string format: email description: Adresse e-mail 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 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 dans lequel le destinataire doit signer phone_number: type: string nullable: true description: Numéro de téléphone du destinataire street_address: type: string nullable: true description: Adresse postale du destinataire city: type: string nullable: true description: Ville du destinataire state_province: type: string nullable: true description: État ou province du destinataire postal_code: type: string nullable: true description: Code postal du destinataire country: type: string nullable: true description: Pays du destinataire title: type: string nullable: true description: Intitulé de poste du destinataire company: type: string nullable: true description: Nom de l'entreprise du destinataire required_fields: type: array items: type: string description: >- Liste des champs de données du destinataire requis pour l'envoi (basée sur les champs du modèle avec des correspondances variable_name). Inclut toujours 'email' et 'first_name'. missing_fields: type: array items: type: string description: Liste des champs requis actuellement vides pour ce destinataire required_read_only_fields: type: array items: type: object properties: variable_name: type: string nullable: true description: Nom de variable du champ en lecture seule variable_defined_name: type: string nullable: true description: >- Nom de champ lisible par un humain provenant de la définition du champ personnalisé (par exemple 'artist_name'). Présent uniquement pour les champs liés à une définition de champ personnalisé, sinon null. field_type: type: string description: Type du champ (text, date, etc.) description: >- Liste des champs en lecture seule obligatoires qui nécessitent des valeurs préremplies avant l'envoi ready_to_send: type: boolean description: >- Indique si ce destinataire a toutes les données obligatoires renseignées pour l'envoi required: - id - first_name - email - designation - order TemplateField: type: object description: Un champ placé sur un document modèle 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 required: type: boolean description: Indique si le champ est obligatoire recipient_id: type: string format: uuid nullable: true description: ID du destinataire assigné variable_name: type: string nullable: true description: Nom de variable pour le champ (utilisé dans les modèles) variable_defined_name: type: string nullable: true description: >- Nom de champ lisible par un humain provenant de la définition du champ personnalisé (par exemple 'artist_name'). Présent uniquement pour les champs liés à une définition de champ personnalisé, sinon null. position: type: object description: >- Position et dimensions du champ sur le document. Toutes les valeurs sont des pourcentages (0-100). Le champ doit tenir dans la page : x + width <= 100 et y + height <= 100. properties: x: type: number minimum: 0 maximum: 100 description: Coordonnée X de la position du champ (pourcentage, 0-100) 'y': type: number minimum: 0 maximum: 100 description: Coordonnée Y de la position du champ (pourcentage, 0-100) width: type: number minimum: 0 maximum: 100 description: >- Largeur du champ (pourcentage, 0-100). Remarque : x + width doit être <= 100 height: type: number minimum: 0 maximum: 100 description: >- Hauteur du champ (pourcentage, 0-100). Remarque : y + height doit être <= 100 page_number: type: integer minimum: 1 nullable: true 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. dropdown_options: nullable: true description: Options pour les champs de type menu déroulant oneOf: - type: array items: type: string - type: object 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. date_default: type: string format: date nullable: true description: >- Valeur de date par défaut pour les champs de date (format ISO 8601, par exemple '2024-01-15') date_signing_default: type: boolean description: >- Utiliser la date de signature comme valeur par défaut pour les champs de date format_rules: $ref: '#/components/schemas/DateFormatRules' nullable: true description: >- Règles de formatage, actuellement utilisées pour les champs de date afin de spécifier le format d'affichage 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) read_only_value: type: string nullable: true description: Valeur statique pour les champs en lecture seule required: - id - type - page_number DocumentSummary: type: object description: Un document d'un modèle ou d'une demande de signature. required: - document_id - position - label - original_filename - page_count - document_url_kind properties: document_id: type: string format: uuid nullable: true description: >- Identifiant du document. null uniquement pour le seul document d'une demande de signature ou d'un modèle dont l'ensemble de documents n'a jamais été modifié (voir l'exemple). position: type: integer minimum: 1 description: Position dans l'ensemble, à partir de 1. label: type: string nullable: true maxLength: 200 description: Nom d'affichage, ou null. original_filename: type: string nullable: true maxLength: 255 description: Nom de fichier enregistré au téléversement, ou null. page_count: type: integer nullable: true description: Nombre de pages de ce document. document_url: type: string nullable: true description: >- URL signée (1 heure) du fichier désigné par `document_url_kind`. Absente des réponses de liste. document_url_kind: type: string nullable: true enum: - stored - signed - null description: >- `stored` : le document tel qu'enregistré ; `signed` : le document scellé individuellement. Toujours `stored` sur les modèles ; null dans les entrées de liste des demandes de signature. document_only_hash: type: string nullable: true description: >- SHA-256 (hex) du document scellé individuellement, null avant que le certificat soit lié. Demandes de signature uniquement. example: document_id: null position: 1 label: null original_filename: null page_count: 3 document_url: >- https://api.firma.dev/storage/v1/object/sign/signing-request-documents/example.pdf?token=example document_url_kind: stored document_only_hash: null 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 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 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.