> ## 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.

# Lister les Demandes de Signature

> Récupérer une liste paginée des demandes de signature



## OpenAPI

````yaml api-reference/v01.30.00/openapi-v01.30.00.fr.json get /signing-requests
openapi: 3.0.3
info:
  title: API Partenaire Firma
  description: >-
    API RESTful pour la signature de documents et la gestion de modèles.


    **Authentification** : Tous les endpoints nécessitent une authentification
    par clé API via l'en-tête `Authorization`. Utilisez votre clé API
    directement sans préfixe (par exemple, `your-api-key`). Le préfixe Bearer
    est optionnel mais pas obligatoire.


    **Fonctionnalités de sécurité** :

    - Validation des entrées avec des schémas Zod incluant des messages d'erreur
    détaillés au niveau des champs

    - Jetons JWT signés RSA-256 pour l'accès aux modèles intégrés


    **Limitation de débit** : Les limites de débit sont hiérarchisées selon le
    type d'opération :

    - Opérations de lecture (GET) : 200 requêtes par minute

    - Opérations d'écriture (POST/PUT/PATCH/DELETE) : 120 requêtes par minute

    - Opérations CRUD sur les webhooks : 60 requêtes par minute

    - Test de webhook : 10 requêtes par minute

    - Régénération/expiration de clé API : 1 requête par minute

    - Rotation du secret de webhook : 1 requête par minute


    Lorsque les limites de débit sont dépassées, l'API renvoie une réponse `429
    Too Many Requests` avec les en-têtes suivants :

    - `X-RateLimit-Limit` : Nombre maximal de requêtes par minute pour cet
    endpoint

    - `X-RateLimit-Remaining` : Requêtes restantes dans la fenêtre actuelle

    - `X-RateLimit-Reset` : Horodatage Unix de la réinitialisation de la limite

    - `Retry-After` : Secondes à attendre avant de pouvoir réessayer


    **Gestion des erreurs** : Toutes les erreurs renvoient des réponses JSON
    structurées avec `error` (message lisible par un humain), `code`
    (identifiant lisible par une machine) et `details` (erreurs de validation au
    niveau des champs, le cas échéant).


    **Intégration de l'Éditeur de Modèles intégré** : L'Éditeur de Modèles Firma
    peut être intégré dans votre application à l'aide d'une bibliothèque
    JavaScript autonome.


    ```html

    <!-- 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>

    ```
  version: 01.30.00
  contact:
    name: API Support
    url: https://firma.com/support
servers:
  - url: https://api.firma.dev/functions/v1/signing-request-api
    description: API de Production - Recommandée (Actuelle)
  - url: https://api.firma.dev/api/v1
    description: API de Production - Prévue
security:
  - ApiKeyAuth: []
tags:
  - name: Company
    description: Informations et paramètres de l'entreprise
  - name: Workspaces
    description: Opérations de gestion des Espaces de Travail
  - name: Templates
    description: Opérations de gestion des Modèles
  - name: Signing Requests
    description: Opérations de Demande de Signature de documents
  - name: Custom Fields
    description: >-
      Gestion des définitions de champs personnalisés pour les espaces de
      travail, modèles et demandes de signature
  - name: Webhooks
    description: Configuration et gestion des webhooks
  - name: JWT Management
    description: Génération et révocation de jetons JWT pour les modèles intégrés
  - name: Workspace Settings
    description: Configuration et paramètres de l'espace de travail
  - name: Email Domains
    description: >-
      Configuration et vérification de domaine e-mail pour l'envoi d'e-mails de
      demande de signature depuis des domaines personnalisés
  - name: Email Templates
    description: >-
      Gestion des modèles d'e-mail pour la personnalisation des notifications de
      demande de signature au niveau de l'espace de travail et de l'entreprise
  - name: Signer Terms
    description: >-
      Conditions d'utilisation / déclarations de consentement personnalisées
      pour le signataire, au niveau de l'entreprise avec des surcharges par
      espace de travail et par langue
paths:
  /signing-requests:
    get:
      tags:
        - Signing Requests
      summary: Lister les Demandes de Signature
      description: Récupérer une liste paginée des demandes de signature
      operationId: listSigningRequests
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            minimum: 1
            default: 1
          description: Numéro de page
        - name: page_size
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 50
          description: Éléments par page
        - name: name
          in: query
          schema:
            type: string
          description: >-
            Filtrer par nom de demande de signature (correspondance partielle,
            insensible à la casse)
        - name: status
          in: query
          schema:
            type: string
            enum:
              - not_sent
              - in_progress
              - finished
              - cancelled
              - declined
              - deleted
              - expired
          description: >-
            Filtrer par statut de demande de signature. Prend en charge
            plusieurs valeurs séparées par des virgules.


            **Statuts disponibles :**

            - `not_sent` : Demande créée mais pas encore envoyée aux signataires

            - `in_progress` : Envoyée aux signataires mais pas terminée,
            annulée, refusée ou expirée

            - `finished` : Tous les signataires ont terminé

            - `cancelled` : La demande a été annulée par l'expéditeur

            - `declined` : Un signataire a refusé de signer (la demande est
            arrêtée)

            - `deleted` : Enregistrements supprimés en douceur (normalement
            masqués)

            - `expired` : Envoyée mais au-delà du délai d'expiration (sent_on +
            expiration_hours < maintenant)


            **Exemple :** `?status=in_progress,expired`


            **Remarque :** Le statut `expired` utilise un post-filtrage qui peut
            avoir des implications sur les performances avec de grands ensembles
            de données.
        - name: created_after
          in: query
          schema:
            type: string
            format: date-time
          description: >-
            Filtrer les demandes de signature créées après cette date (format
            ISO 8601)
        - name: created_before
          in: query
          schema:
            type: string
            format: date-time
          description: >-
            Filtre les demandes de signature créées avant cette date (format ISO
            8601)
        - name: signer_email
          in: query
          schema:
            type: string
          description: Filtre par adresse email du signataire (correspondance exacte)
        - name: signer_name
          in: query
          schema:
            type: string
          description: >-
            Filtre par nom du signataire (correspondance partielle, insensible à
            la casse)
        - name: sort_by
          in: query
          schema:
            type: string
            enum:
              - name
              - created_on
              - expiration_hours
              - sent_on
              - finished_on
            default: created_on
          description: Champ utilisé pour le tri
        - name: sort_order
          in: query
          schema:
            type: string
            enum:
              - asc
              - desc
            default: desc
          description: Ordre de tri
      responses:
        '200':
          description: Demandes de signature récupérées avec succès
          headers:
            X-RateLimit-Limit:
              schema:
                type: integer
              description: 'Limite de débit : 200 requêtes par minute'
            X-RateLimit-Remaining:
              schema:
                type: integer
            X-RateLimit-Reset:
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SigningRequestListResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '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.signingRequests.listSigningRequests();
            console.log(response);
components:
  schemas:
    SigningRequestListResponse:
      type: object
      description: Liste paginée des demandes de signature
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/SigningRequestListItem'
        pagination:
          $ref: '#/components/schemas/Pagination'
      required:
        - results
        - pagination
    SigningRequestListItem:
      type: object
      description: >-
        Demande de signature telle que renvoyée par l'endpoint LIST (GET
        /signing-requests)
      properties:
        id:
          type: string
          format: uuid
          description: Identifiant unique de la demande de signature
        name:
          type: string
          description: Nom de la demande de signature
          maxLength: 255
        description:
          type: string
          nullable: true
          description: Description de la demande de signature
        status:
          type: string
          enum:
            - not_sent
            - in_progress
            - finished
            - cancelled
            - declined
            - deleted
            - expired
          description: Statut actuel de la demande de signature
        document_url:
          type: string
          format: uri
          description: >-
            URL pré-signée vers le document PDF. C'est une URL signée à durée
            limitée pour un accès sécurisé - voir document_url_expires_at pour
            l'heure d'expiration. Les URL initiales sont valides 7 jours ; les
            URL rafraîchies sont valides 1 heure. Demande une nouvelle
            récupération de la demande de signature pour obtenir une URL fraîche
            si elle a expiré.
        document_url_expires_at:
          type: string
          format: date-time
          nullable: true
          description: >-
            Horodatage ISO 8601 de l'expiration de document_url. Après cette
            heure, l'URL renverra une erreur d'accès refusé. Récupère à nouveau
            la demande de signature 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 de la demande de signature (par
            défaut : 168 = 7 jours)
        expires_at:
          type: string
          format: date-time
          nullable: true
          description: >-
            Horodatage ISO 8601 de l'expiration de la demande de signature.
            Calculé à partir de sent_date + expiration_hours. Null si la demande
            de signature n'a pas encore été envoyée ou n'a pas de
            expiration_hours défini.
        credit_cost:
          type: integer
          minimum: 1
          default: 1
          description: >-
            Nombre de crédits consommés lors de l'envoi de cette demande de
            signature. La valeur minimale est 1.
        template_id:
          type: string
          format: uuid
          nullable: true
          description: ID du modèle si créé à partir d'un modèle
        settings:
          $ref: '#/components/schemas/SigningRequestSettings'
        created_date:
          type: string
          format: date-time
          description: Horodatage de création
        updated_date:
          type: string
          format: date-time
          description: Horodatage de dernière mise à jour
        sent_date:
          type: string
          format: date-time
          nullable: true
          description: Date d'envoi de la demande de signature
        finished_date:
          type: string
          format: date-time
          nullable: true
          description: Date à laquelle toutes les signatures ont été complétées
        cancelled_date:
          type: string
          format: date-time
          nullable: true
          description: Date d'annulation de la demande de signature
        declined_date:
          type: string
          format: date-time
          nullable: true
          description: Date de refus de la demande de signature
        recipients:
          type: array
          description: Destinataires de la demande de signature (format simplifié)
          items:
            $ref: '#/components/schemas/SigningRequestListRecipient'
        fields:
          type: array
          description: Champs de la demande de signature avec un objet position imbriqué
          items:
            type: object
            properties:
              id:
                type: string
                format: uuid
              type:
                type: string
                enum:
                  - text
                  - signature
                  - date
                  - checkbox
                  - dropdown
                  - radio_buttons
                  - number
                  - text_area
                  - file
                  - initial
                  - stamp
                  - approval_signature
                  - approval_checkmark
                  - approval_date
              required:
                type: boolean
              recipient_id:
                type: string
                format: uuid
                nullable: true
              variable_name:
                type: string
                nullable: true
              variable_defined_name:
                type: string
                nullable: true
                description: >-
                  Nom de champ lisible provenant de la définition du champ
                  personnalisé (par ex. 'artist_name'). Présent uniquement pour
                  les champs liés à une définition de champ personnalisé, null
                  sinon.
              position:
                type: object
                properties:
                  x:
                    type: number
                  'y':
                    type: number
                  width:
                    type: number
                  height:
                    type: number
              value:
                type: string
                nullable: true
                description: Valeur finale du champ après la signature
              dropdown_options:
                nullable: true
                oneOf:
                  - type: array
                    items:
                      type: string
                  - type: object
              format_rules:
                $ref: '#/components/schemas/DateFormatRules'
                nullable: true
              validation_rules:
                $ref: '#/components/schemas/FieldValidationRules'
      required:
        - id
        - name
        - status
        - created_date
    Pagination:
      type: object
      properties:
        current_page:
          type: integer
        page_size:
          type: integer
        total_count:
          type: integer
        total_pages:
          type: integer
      description: Métadonnées de pagination pour les réponses de type liste
      required:
        - current_page
        - page_size
        - total_count
        - total_pages
    Error:
      type: object
      properties:
        error:
          type: string
          description: Message d'erreur lisible par un humain
        message:
          type: string
          description: Description détaillée de l'erreur
        details:
          type: object
          description: Détails d'erreur supplémentaires
          additionalProperties: true
      required:
        - error
    SigningRequestSettings:
      type: object
      description: >-
        Paramètres renvoyés par les endpoints de liste et de détail des demandes
        de signature. Les modèles utilisent le schéma TemplateSettings (sans
        champs d'identité).
      properties:
        allow_download:
          type: boolean
          description: Indique si les destinataires peuvent télécharger le document
          default: true
        attach_pdf_on_finish:
          type: boolean
          description: Indique s'il faut joindre le PDF une fois la signature terminée
          default: true
        allow_editing_before_sending:
          type: boolean
          description: Indique si la demande de signature peut être modifiée avant l'envoi
          default: false
        use_signing_order:
          type: boolean
          description: >-
            Indique si l'ordre de signature est imposé entre les destinataires.
            Quand c'est vrai, les signataires reçoivent le document dans l'ordre
            défini par leur order. Quand c'est faux, tous les signataires
            reçoivent le document simultanément.
          default: true
        hand_drawn_only:
          type: boolean
          description: >-
            Lorsque cette option est activée, les signataires ne peuvent que
            dessiner leur signature à la main et ne peuvent pas utiliser de
            signatures dactylographiées
          default: false
        send_signing_email:
          type: boolean
          description: >-
            Indique s'il faut envoyer des e-mails de notification de demande de
            signature aux signataires
          default: true
        send_finish_email:
          type: boolean
          description: >-
            Indique s'il faut envoyer un e-mail de fin lorsque tous les
            signataires ont terminé
          default: true
        send_expiration_email:
          type: boolean
          description: >-
            Indique s'il faut envoyer un e-mail de notification d'expiration
            quand la demande expire
          default: true
        send_cancellation_email:
          type: boolean
          description: >-
            Indique s'il faut envoyer un e-mail de notification d'annulation
            quand la demande est annulée
          default: true
        require_otp_verification:
          type: boolean
          nullable: true
          description: >-
            Indique si les signataires doivent vérifier leur e-mail avec un code
            à usage unique avant d'accéder au document. null = hérite du
            paramètre de l'espace de travail/de l'entreprise.
          default: null
        disable_guided_navigation:
          type: boolean
          nullable: true
          description: >-
            Désactive le défilement automatique vers le prochain champ requis
            pendant la signature. Hérite de l'espace de travail ou de
            l'entreprise si non défini.
        allow_presigning_download:
          type: boolean
          nullable: true
          description: >-
            Permet aux signataires de télécharger le document original avant de
            signer. Hérite du paramètre de l'espace de travail ou de
            l'entreprise quand null.
        show_qr_code:
          type: boolean
          nullable: true
          description: >-
            Affiche un QR code sur la page de signature qui permet aux
            signataires de continuer sur leur téléphone. Hérite du paramètre de
            l'espace de travail ou de l'entreprise quand null.
        identity_editable_fields:
          type: array
          nullable: true
          items:
            type: string
          description: >-
            Champs d'identité que les signataires peuvent modifier avant de
            signer (par exemple ["name", "company"]). null = désactivé. Quand
            c'est défini, une boîte de dialogue de confirmation permet aux
            signataires de modifier les champs spécifiés.
        notify_identity_change_email:
          type: boolean
          default: false
          description: >-
            Envoie une notification par e-mail quand un signataire modifie son
            identité.
    SigningRequestListRecipient:
      type: object
      description: >-
        Destinataire tel que renvoyé dans les réponses LIST des demandes de
        signature (format simplifié)
      properties:
        id:
          type: string
          format: uuid
          description: Identifiant unique du destinataire
        name:
          type: string
          description: Nom complet combiné
        email:
          type: string
          format: email
          description: Adresse e-mail du destinataire
        designation:
          type: string
          enum:
            - Signer
            - Approver
            - CC
          description: >-
            Rôle du destinataire. Signer signe le document, Approver approuve
            avec des champs d'approbation, CC reçoit une copie une fois terminé.
        order:
          type: integer
          minimum: 1
          description: Ordre de signature
        finished_date:
          type: string
          format: date-time
          nullable: true
          description: Date à laquelle ce destinataire a terminé de signer
        signature_details:
          type: object
          nullable: true
          description: Détails sur la signature du destinataire
    DateFormatRules:
      type: object
      description: >-
        Règles de formatage pour les champs de date. Spécifie comment les
        valeurs de date doivent être affichées et formatées.
      properties:
        dateFormat:
          type: string
          description: >-
            Modèle de format de date. Utilisez des formats prédéfinis ou des
            modèles personnalisés avec : yyyy (année sur 4 chiffres), MM (mois
            sur 2 chiffres), dd (jour sur 2 chiffres), MMMM (nom complet du
            mois), MMM (nom abrégé du mois), HH (heure sur 24h), mm (minute), ss
            (seconde). Exemples : 'MM/dd/yyyy' s'affiche comme 01/31/2024, 'MMMM
            dd, yyyy' s'affiche comme January 31, 2024.
          enum:
            - MM/dd/yyyy
            - dd/MM/yyyy
            - yyyy-MM-dd
            - MMMM dd, yyyy
            - MMM dd, yyyy
            - dd MMMM yyyy
          default: MM/dd/yyyy
      example:
        dateFormat: MMMM dd, yyyy
    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.

````