> ## 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 cachet d'organisation

> Crée un nouveau cachet d'organisation avec une image téléchargée, saisie ou dessinée. Les cachets de portée entreprise requièrent une clé API protégée.



## OpenAPI

````yaml api-reference/v01.39.01/openapi-v01.39.01.fr.json post /seals
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

    <!-- Charger la bibliothèque de l'Éditeur de Modèles Firma -->

    <script
    src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>


    <script>

    // Générer d'abord un jeton JWT via l'API

    fetch('https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
    {
      method: 'POST',
      headers: {
        'Authorization': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        companies_workspaces_templates_id: 'template-id'
      })
    })

    .then(res => res.json())

    .then(data => {
      // Initialiser l'éditeur avec le jeton JWT
      window.FirmaTemplateEditor.init({
        container: '#firma-editor-container',
        jwt: data.token,
        templateId: 'template-id',
        theme: 'dark',
        readOnly: false,
        onSave: (savedData) => {
          console.log('Template saved:', savedData);
        },
        onError: (error) => {
          console.error('Editor error:', error);
        },
        onLoad: (template) => {
          console.log('Template loaded:', template);
        }
      });
    });

    </script>

    ```


    **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:
  /seals:
    post:
      tags:
        - Organization Seals
      summary: Créer un cachet d'organisation
      description: >-
        Crée un nouveau cachet d'organisation avec une image téléchargée, saisie
        ou dessinée. Les cachets de portée entreprise requièrent une clé API
        protégée.
      operationId: createOrganizationSeal
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrganizationSealCreate'
      responses:
        '201':
          description: Cachet créé avec succès
          headers:
            X-Firma-Deprecation:
              schema:
                type: string
              description: >-
                Présent lorsque l'opération est disponible mais sera déplacée
                vers l'hôte principal de l'API dans une version future. La
                valeur décrit le calendrier.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationSeal'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '409':
          description: >-
            Conflit. Codes possibles : SEAL_ALREADY_REVOKED,
            SEAL_ORDER_COLLISION, SEAL_ERASE_NOT_ELIGIBLE
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  code:
                    $ref: '#/components/schemas/SealErrorCode'
        '429':
          $ref: '#/components/responses/RateLimitError'
        '503':
          description: >-
            Le traitement des images de cachet est indisponible sur cet hôte
            (SEAL_CREATION_DISABLED_EDGE). Réessayez sur l'hôte principal de
            l'API.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    OrganizationSealCreate:
      type: object
      required:
        - name
        - display_name
        - kind
        - scope
        - statement
      description: Corps de requête pour créer un cachet d'organisation.
      properties:
        name:
          type: string
          maxLength: 120
          description: Nom interne du cachet
        display_name:
          type: string
          maxLength: 200
          description: Nom d'affichage rendu sur l'image du cachet
        signatory_title:
          type: string
          maxLength: 200
          nullable: true
          description: Titre du signataire rendu sur l'image du cachet
        kind:
          type: string
          enum:
            - uploaded
            - typed
            - drawn
          description: Comment l'image du cachet a été créée
        scope:
          type: string
          enum:
            - company
            - workspace
          description: >-
            Portée du cachet. La portée entreprise requiert une clé API
            protégée.
        workspace_id:
          type: string
          format: uuid
          description: Requis lorsque scope vaut 'workspace'
        image:
          type: string
          description: >-
            URI de données PNG encodée en base64 (data:image/png;base64,...).
            Requise pour les types 'uploaded' et 'drawn'.
        typed:
          type: object
          description: Paramètres du cachet saisi. Requis pour le type 'typed'.
          properties:
            text:
              type: string
              description: Texte à rendre sur le cachet
            style:
              type: string
              description: Variante de style du cachet saisi
        statement:
          $ref: '#/components/schemas/SealStatement'
        is_default:
          type: boolean
          default: false
          description: Définir comme cachet par défaut de cette portée
    OrganizationSeal:
      type: object
      description: >-
        Métadonnées du cachet d'organisation (les données internes de l'image et
        de la déclaration sont retirées des réponses de liste et de
        consultation).
      properties:
        id:
          type: string
          format: uuid
        lineage_id:
          type: string
          format: uuid
          description: Partagé entre les versions du même cachet
        version:
          type: integer
          minimum: 1
        companies_id:
          type: string
          format: uuid
        companies_workspaces_id:
          type: string
          format: uuid
          nullable: true
          description: Null pour les cachets de portée entreprise
        authority_name:
          type: string
          nullable: true
          description: >-
            Le nom au titre duquel le cachet a été attesté : l'entreprise pour
            la portée entreprise ou l'espace de travail protégé, sinon l'espace
            de travail. Null pour les cachets dont la lignée a été créée avant
            la fixation du nom ; ils certifient au nom actuel de l'entreprise.
        name:
          type: string
          maxLength: 120
        display_name:
          type: string
          maxLength: 200
        signatory_title:
          type: string
          maxLength: 200
          nullable: true
        kind:
          type: string
          enum:
            - uploaded
            - typed
            - drawn
        is_default:
          type: integer
          enum:
            - 0
            - 1
          description: 1 s'il s'agit du cachet par défaut de sa portée
        statement_language:
          type: string
        statement_version:
          type: integer
          minimum: 1
        signatory_name:
          type: string
          maxLength: 200
        signatory_title_attested:
          type: string
          maxLength: 200
          nullable: true
        attested_at:
          type: string
          format: date-time
        revoked_on:
          type: string
          format: date-time
          nullable: true
        created_at:
          type: string
          format: date-time
        deleted:
          type: integer
          enum:
            - 0
            - 1
    SealErrorCode:
      type: string
      enum:
        - 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
      description: >-
        Codes d'erreur spécifiques aux opérations sur les cachets
        d'organisation.
    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
    SealStatement:
      type: object
      required:
        - language
        - signatory_name
        - text
        - accepted
      description: Déclaration d'attestation affirmant l'autorité d'appliquer le cachet.
      properties:
        language:
          type: string
          description: Code de langue de la déclaration
        signatory_name:
          type: string
          maxLength: 200
          description: Nom de la personne qui atteste
        signatory_title:
          type: string
          maxLength: 200
          nullable: true
          description: Titre de la personne qui atteste
        text:
          type: string
          description: >-
            À la création, la déclaration rendue avec le nom de l'autorité (le
            nom enregistré de l'espace de travail ou de l'entreprise exactement
            tel que renvoyé par l'API, échappement HTML compris). Au
            remplacement, il doit être identique au texte de déclaration
            enregistré du cachet.
        accepted:
          type: boolean
          description: Doit valoir true pour confirmer l'acceptation
        version:
          type: integer
          minimum: 1
          description: Numéro de version de la déclaration
  responses:
    ValidationError:
      description: Requête Incorrecte - Échec de la validation
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Validation Error
            message: Invalid input data
            details:
              name: Name is required
              email: Invalid email format
    UnauthorizedError:
      description: Non Autorisé - Clé API invalide ou manquante
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Unauthorized
            message: Invalid API key
    ForbiddenError:
      description: Interdit - Permissions insuffisantes
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Forbidden
            message: You do not have permission to access this resource
    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.