Journal des modifications de l'API

​

Résumé des versions

​

v1.30.0

​

Récupérer les marques du signataire comme images

• GET /signing-requests/{id}/signers/{signer_id}/signature — la signature adoptée par le signataire
• GET /signing-requests/{id}/signers/{signer_id}/initials — les initiales adoptées par le signataire
• GET /signing-requests/{id}/signers/{signer_id}/stamps/{field_id} — un tampon pour un champ tampon spécifique
• GET /signing-requests/{id}/signers/{signer_id}/files/{field_id} — un fichier téléversé par le signataire dans un champ fichier

​

Guide de migration

​

v1.29.0

​

Téléversement de document en deux étapes

1. Appeler POST /documents avec les métadonnées du fichier pour recevoir une URL de téléversement pré-signée
2. Effectuer un PUT des octets bruts du fichier directement vers l’URL de téléversement (prend en charge jusqu’à 50 Mo)
3. Transmettre le document_id renvoyé dans votre requête POST /signing-requests ou POST /signing-requests/create-and-send

​

Nouveau champ de requête : document_id

​

Augmentation de la limite de taille de document

​

Guide de migration

​

v1.28.0

​

Exemples de code SDK TypeScript

​

Changements dans la surface de la référence

​

Guide de migration

​

v1.27.0

​

Champs de paramètres désormais documentés dans les réponses

​

Paramètres de la demande de signature

​

Paramètres du modèle

​

Réponses d’annulation et de renvoi

​

Nouveaux schémas

​

Guide de migration

​

v1.26.0

​

Paramètres de l’espace de travail : quatre nouveaux champs

​

Structure de la personnalisation des libellés de bouton

{
  "en": {
    "common.finish": "Confirm",
    "signing.decline.confirm": "I Refuse"
  },
  "de": {
    "common.finish": "Bestätigen"
  }
}

​

v1.25.2

​

Validation plus stricte pour les surcharges de champ de modèle

{
  "error": "The following provided fields do not match any field in the template and cannot be applied: full_name_x. Each provided field must reference an existing template field by 'template_field_id' or 'variable_name'.",
  "code": "VALIDATION_ERROR"
}

​

Types de champ insensibles à la casse

​

v1.25.1

​

Réponses d’erreur précises pour create-and-send

• 400 VALIDATION_ERROR — la validation de la requête ou de l’envoi a échoué (par ex. un signataire auquel il manque des informations requises) ; la réponse inclut validation_errors, field_errors ou details identifiant ce qu’il faut corriger.
• 402 INSUFFICIENT_CREDITS — crédits insuffisants pour envoyer ; current_credits indique le solde.
• 422 RECIPIENT_EMAIL_SUPPRESSED (nouveau) — l’adresse email d’un destinataire est supprimée (précédemment renvoyée en erreur ou marquée comme spam) et l’envoi est impossible.

​

v1.25.0

​

Couleurs de marque de l’éditeur

• color_accent — couleur d’accentuation pour les mises en évidence, les onglets actifs, les interrupteurs et les contrôles principaux dans l’interface de l’éditeur.
• color_accent_fg — couleur de premier plan (texte/icônes) affichée sur les surfaces d’accentuation.
• color_canvas — la couleur d’entourage du canevas du document derrière la page.
• color_muted — couleur de surface atténuée (séparateurs, états de survol, pistes des interrupteurs).
• color_muted_fg — couleur de texte atténuée.

• GET/PUT /company/settings et GET/PUT /workspace/{workspace_id}/settings acceptent et renvoient les cinq nouveaux champs. Chacun est une chaîne hexadécimale #rrggbb pouvant être null ; null signifie hériter (espace de travail → entreprise → valeur par défaut de Firma).
• L’objet color_palette résolu renvoyé dans les charges utiles de l’éditeur intégré contient désormais onze clés (les six existantes plus accent, accent_fg, canvas, muted, muted_fg). Lorsqu’il n’est pas défini, muted prend par défaut la couleur card résolue et muted_fg est dérivé pour garantir la lisibilité, de sorte que la palette est toujours entièrement peuplée.

​

v1.24.0

​

Clés API de test pour l’espace de travail

• POST /workspaces provisionne désormais une paire de clés live + test et renvoie à la fois api_key (live) et le nouveau champ test_api_key.
• GET /workspaces/{id} et GET /workspaces renvoient désormais à la fois api_key et test_api_key.
• POST /workspaces/{id}/api-key/regenerate et /api-key/expire acceptent un key_type optionnel ("live" ou "test", "live" par défaut). La régénération d’un type de clé n’affecte plus l’autre.
• Les espaces de travail existants créés via l’API sont rétroactivement dotés d’une clé de test.

​

v1.23.0

​

Conditions du signataire

• les endpoints GET listent les conditions du signataire pour l’entreprise et l’espace de travail
• les endpoints PUT créent ou mettent à jour les conditions du signataire par langue pour l’entreprise et l’espace de travail
• les endpoints DELETE suppriment les conditions du signataire pour l’entreprise et l’espace de travail

​

Paramètres d’entreprise

​

Changements de schéma

• Schéma des paramètres d’entreprise : ajout de require_terms_acceptance (booléen)
• Schéma des paramètres d’espace de travail : ajout de require_terms_acceptance (booléen, pouvant être null). Utilisez null pour hériter du paramètre de l’entreprise.

​

Guide de migration

​

v1.22.1

​

Suppression de domaine d’email

​

Guide de migration

​

v1.22.0

​

Endpoint de suppression de demande de signature

• 200 avec signing_request_id et deleted_on en cas de succès
• 409 ALREADY_SENT si la demande de signature a été envoyée
• 404 si introuvable ou déjà supprimée

​

Nouvel événement webhook

• signing_request.deleted se déclenche lorsqu’une demande de signature est supprimée via l’API

​

Guide de migration

​

v1.21.1

​

Gestion du webhook de l’espace de travail

• webhook_enabled (booléen) - Active ou désactive les webhooks au niveau de l’espace de travail. Lorsqu’il est défini sur true pour la première fois, un secret de webhook est automatiquement généré.
• ignore_company_webhooks (booléen) - Si true, les webhooks au niveau de l’entreprise ne se déclencheront pas pour les événements de cet espace de travail.

​

Changements de schéma

• PATCH /workspaces/ corps de requête : ajout de webhook_enabled (booléen, optionnel) et ignore_company_webhooks (booléen, optionnel)
• PATCH /workspaces/ réponse : inclut désormais webhook_enabled, webhook_secret, webhook_secret_rotated_at, webhook_secret_created_at, et ignore_company_webhooks

​

Guide de migration

​

v1.21.0

​

Nouveaux paramètres

• email_local_part (chaîne, pouvant être null) - Personnalise la partie locale (avant le @) des emails de signature sortants lors de l’utilisation d’un domaine personnalisé vérifié. Disponible à deux niveaux :
  • Paramètres d’entreprise (GET/PATCH /company) - Définit la valeur par défaut pour tous les espaces de travail. Chaîne avec valeur par défaut "support".
  • Paramètres d’espace de travail (GET/PUT /workspace/{id}/settings) - Remplace la valeur par défaut de l’entreprise. Chaîne pouvant être null (null hérite de l’entreprise).

​

Changements de schéma

• Schéma Company : ajout de email_local_part (chaîne, par défaut "support")
• Schéma des paramètres d’espace de travail : ajout de email_local_part (chaîne, pouvant être null)

​

Guide de migration

​

v1.20.0

​

Nouveaux paramètres

• disable_guided_navigation (booléen, pouvant être null) - Désactive le défilement automatique vers le prochain champ obligatoire pendant la signature. Disponible à quatre niveaux :
  • Paramètres d’entreprise (GET/PUT /company/settings) - Définit la valeur par défaut pour tous les espaces de travail. Booléen (non nullable).
  • Paramètres d’espace de travail (GET/PUT /workspace/{id}/settings) - Remplace la valeur par défaut de l’entreprise. Booléen ou null (null hérite de l’entreprise).
  • Modèle (POST/PATCH /templates) - Copié vers les demandes de signature créées à partir de ce modèle. Booléen ou null.
  • Demande de signature (POST/PATCH /signing-requests) - Surcharge de priorité la plus élevée. Booléen ou null (null hérite de l’espace de travail/entreprise).

​

Changements de schéma

• Schéma des paramètres d’entreprise : ajout de disable_guided_navigation (booléen)
• Schéma des paramètres d’espace de travail : ajout de disable_guided_navigation (booléen, pouvant être null)
• Schéma des paramètres de modèle : ajout de disable_guided_navigation (booléen, pouvant être null)
• Schéma des paramètres de demande de signature : ajout de disable_guided_navigation (booléen, pouvant être null)

​

Guide de migration

​

v1.19.0

​

Nouveaux endpoints

• POST /company/logo - Téléverse une image de logo d’entreprise (PNG ou JPEG, 2 Mo maximum). Le logo apparaît sur les certificats et emails de signature.
• DELETE /company/logo - Supprime le logo de l’entreprise. Les certificats reviennent à la valeur par défaut de Firma.
• POST /workspaces/{id}/logo - Téléverse un logo propre à l’espace de travail qui remplace le logo de l’entreprise pour cet espace de travail.
• DELETE /workspaces/{id}/logo - Supprime le logo de l’espace de travail. Revient au logo de l’entreprise.

​

Changements de schéma

• Le schéma Workspace inclut désormais icon_url (chaîne, pouvant être null) - une URL publiquement accessible vers l’image du logo de l’espace de travail
• icon_url de Company est désormais en lecture seule dans les requêtes PATCH/PUT. Utilisez le nouvel endpoint POST /company/logo pour gérer les logos.

​

Guide de migration

• Si vous définissiez icon_url directement via PATCH /company ou PATCH /workspaces/{id}, passez plutôt aux nouveaux endpoints POST .../logo. Le champ icon_url n’est plus accepté dans les corps de requête de mise à jour.
• icon_url dans les réponses GET renvoie désormais une URL publiquement accessible au lieu d’une référence interne.

​

v1.18.0

​

Nouvelles fonctionnalités

​

Champs modifiables par l’identité

• null - utilise la valeur par défaut de la demande
• [] - désactivé pour ce signataire
• ["name", "company"] - champs personnalisés pour ce signataire

{
  "settings": {
    "identity_editable_fields": ["name", "company"]
  },
  "recipients": [
    {
      "name": "John Doe",
      "email": "john@example.com",
      "designation": "signer",
      "order": 1,
      "identity_editable_fields": null
    },
    {
      "name": "Jane Smith",
      "email": "jane@example.com",
      "designation": "signer",
      "order": 2,
      "identity_editable_fields": []
    }
  ]
}

​

Champs de données préremplies modifiables

• Champs de modèle (PATCH /templates/{id}, PUT /templates/{id})
• Champs de demande de signature (POST /signing-requests, POST /signing-requests/create-and-send)
• Objets de réponse de champ (GET /signing-requests/{id})

{
  "fields": [
    {
      "type": "text",
      "recipient_id": "temp_1",
      "page_number": 1,
      "x": 10,
      "y": 20,
      "width": 30,
      "height": 5,
      "format_rules": {
        "prefilledData": "full_name",
        "prefilledEditable": true
      }
    }
  ]
}

​

Validation de la source de valeur du champ

• POST /signing-requests
• POST /signing-requests/create-and-send
• PATCH /templates/{id} (création et mise à jour de champ)
• PUT /templates/{id} (upsert de champ)

​

Priorité de valeur

​

Guide de migration

• La modification de l’identité est désactivée par défaut (identity_editable_fields: null). Définissez-la sur un tableau de clés de champ pour l’activer.
• Les champs de données préremplies existants restent verrouillés (lecture seule) par défaut. Définissez prefilled_editable: true dans format_rules pour les rendre modifiables.

​

v1.17.0

​

Nouvelles fonctionnalités

​

Personnalisation des couleurs pour l’expérience de signature

​

Schéma ColorPalette

​

Guide de migration

• Les six champs de couleur sont null par défaut, ce qui préserve l’apparence par défaut existante de Firma.
• Pour personnaliser les couleurs, définissez des valeurs hexadécimales sur les paramètres d’entreprise (valeurs par défaut pour toute l’entreprise) ou les paramètres d’espace de travail (surcharges par espace de travail).
• La cascade de couleurs est : valeurs par défaut de Firma -> surcharges d’entreprise -> surcharges d’espace de travail. Chaque niveau ne remplace que les champs explicitement définis (non null).

​

v1.16.0

​

Nouvelles fonctionnalités

​

Téléchargement du document de la demande de signature

​

Paramètre de filigrane de téléchargement partiel

​

Guide de migration

• L’endpoint de téléchargement est purement optionnel. Aucun comportement existant ne change.
• Appelez GET /signing-requests/{id}/download — gérez 503 avec Retry-After jusqu’à ce que le document soit prêt.

​

v1.15.3

​

Alias de champs propres pour GET /signing-requests//fields

​

Guide de migration

// Avant → Après
field.field_type        → field.type
field.x_postion         → field.position.x
field.heigh             → field.position.height
field.final_value       → field.value
field.required === 1    → field.required === true

​

v01.15.02

​

Corrections de bugs

​

Types de champ de create-and-send étendus

• dropdown (avec la propriété dropdown_options)
• radio_buttons
• text_area
• url
• file

• POST /signing-requests/create-and-send — énumération fields[].type

​

v01.15.01

​

Corrections de bugs

​

Énumération des langues mise à jour

• PUT /workspace/{workspace_id}/settings — champ language
• PUT /company et PATCH /company — champ language
• GET /email-templates/defaults — paramètre de requête language

​

v01.15.00

​

Nouvelles fonctionnalités

​

Webhooks propres à l’espace de travail

• Paramètre workspace_id à la création du webhook — Transmettez un workspace_id optionnel lors de la création d’un webhook pour le limiter à un espace de travail spécifique. L’omettre crée un webhook au niveau de l’entreprise (comportement existant).
• Filtre workspace_id sur le listing des webhooks — Filtrez la liste des webhooks par espace de travail. Lorsqu’il est omis, seuls les webhooks au niveau de l’entreprise sont renvoyés.
• Champ d’espace de travail ignore_company_webhooks — Les espaces de travail peuvent choisir de ne pas recevoir les événements webhook au niveau de l’entreprise en définissant cet indicateur sur true.

​

Gestion du secret de webhook d’espace de travail

• POST /workspaces/{id}/webhooks/rotate-secret — Génère un nouveau secret de signature de webhook pour l’espace de travail. L’ancien secret reste valide pendant une période de grâce de 7 jours.
• GET /workspaces/{id}/webhooks/secret-status — Renvoie le statut du secret de webhook de l’espace de travail, y compris la date de création, la date de rotation et les informations de période de grâce.

​

Champs webhook de la réponse d’espace de travail

• webhook_enabled — Si les webhooks au niveau de l’espace de travail sont activés
• webhook_secret — Le secret de signature de webhook actuel
• webhook_secret_created_at — Date de création du secret actuel
• webhook_secret_rotated_at — Date de la dernière rotation du secret
• ignore_company_webhooks — Si l’espace de travail ignore les événements webhook au niveau de l’entreprise

​

Changements

• Ajout du paramètre optionnel workspace_id à POST /webhooks et GET /webhooks
• Ajout de 5 nouveaux champs au schéma Workspace : webhook_enabled, webhook_secret, webhook_secret_created_at, webhook_secret_rotated_at, ignore_company_webhooks
• Ajout de 2 nouveaux endpoints : POST /workspaces/{id}/webhooks/rotate-secret, GET /workspaces/{id}/webhooks/secret-status
• Protection SSRF appliquée à la validation de l’URL de webhook

​

Guide de migration

• Les webhooks au niveau de l’entreprise restent la valeur par défaut. Le paramètre workspace_id est optionnel à la fois pour la création et le listing.
• Les webhooks existants ne sont pas affectés. Les nouveaux champs d’espace de travail sur la réponse d’espace de travail ont pour valeur par défaut webhook_enabled: false et ignore_company_webhooks: false.
• Pour adopter les webhooks d’espace de travail, créez un webhook avec un workspace_id, puis utilisez l’endpoint de rotation de secret d’espace de travail pour générer un secret de signature pour cet espace de travail.

​

v01.14.00

​

Nouvelles fonctionnalités

​

Désignations des destinataires

• Signer — Signe le document (comportement existant, reste la valeur par défaut)
• Approver — Approuve le document en utilisant des champs spécifiques à l’approbation. Les approbateurs ne signent pas mais doivent compléter tous les champs d’approbation qui leur sont assignés avant que la demande puisse se terminer.
• CC — Reçoit une copie terminée du document signé. Les destinataires en CC ne peuvent ni signer, ni se voir assigner de champs.

​

Types de champ d’approbation

• approval_signature — Un tampon d’approbation placé par l’approbateur
• approval_checkmark — Une case à cocher d’approbation
• approval_date — Date auto-remplie lorsque l’approbateur approuve

​

Destinataires CC

​

Changements

• Extension de l’énumération designation de ["Signer"] à ["Signer", "Approver", "CC"] sur 7 schémas
• Ajout de approval_signature, approval_checkmark, et approval_date aux énumérations de type de champ sur 10 schémas

​

Guide de migration

• Les nouvelles valeurs de designation sont optionnelles. Omettre le champ designation utilise par défaut "Signer", préservant le comportement existant.
• Les nouveaux types de champ sont additifs. Toutes les valeurs de type de champ existantes restent valides et inchangées.
• Si vous intégrez des flux d’approbation, assignez la désignation "Approver" aux destinataires concernés et utilisez les types de champ approval_* pour leurs champs.

​

v01.13.00

​

Nouvelles fonctionnalités

​

Type de champ Tampon

​

Changements

• Ajout de stamp aux énumérations de type de champ sur tous les schémas liés aux champs (modèles, demandes de signature, create-and-send)
• Mise à jour des descriptions de type de champ pour documenter le comportement des tampons

​

Guide de migration

• Si vous créez des champs via l’API, vous pouvez désormais utiliser "stamp" comme type de champ. Les champs tampon doivent être définis avec read_only: true, l’image du tampon étant fournie en tant qu’URL de données PNG dans read_only_value.
• Les champs tampon sont également pris en charge dans les balises d’ancrage. Lors de l’utilisation de balises d’ancrage, l’image du tampon doit être fournie via read_only_value en tant qu’URL de données PNG.

​

v01.12.01

​

Nouvelles fonctionnalités

​

variable_defined_name sur les réponses de champ

• GET /templates (liste et unitaire)
• GET /templates/{id}/fields
• POST /templates/{id}/replace-document
• GET /signing-requests (liste)
• GET /signing-requests/{id}/fields
• GET /documents (legacy)

{
  "variable_name": "custom_template_a1b2c3d4-...",
  "variable_defined_name": "artist_name"
}

​

variable_defined_name comme entrée pour la correspondance de champ

{
  "fields": [
    { "variable_defined_name": "artist_name", "read_only_value": "John Smith" }
  ]
}

​

Aucun changement majeur

​

v01.12.00

​

Nouvelles fonctionnalités

​

Intégration du serveur MCP

• Authentification par clé API via l’en-tête Authorization
• OAuth 2.1 avec PKCE pour les clients basés sur navigateur (Claude.ai, Claude Desktop)

• Espaces de travail — lister, créer, obtenir, mettre à jour
• Modèles — CRUD complet, duplication, consultation des champs/utilisateurs/rappels
• Demandes de signature — CRUD complet, envoi, annulation, renvoi, pistes d’audit
• Webhooks — CRUD complet, test de livraison
• Entreprise — consultation et mise à jour des informations d’entreprise

​

Aucun changement majeur

​

v01.11.00

​

Nouvelles fonctionnalités

​

Type de champ Téléversement de fichier

• Les signataires peuvent téléverser des images (JPG, PNG) et/ou des fichiers PDF selon la configuration
• Les fichiers sont validés par leurs octets magiques, pas seulement par l’extension du fichier
• Taille de fichier maximale : 10 Mo

{
  "type": "file",
  "format_rules": {
    "acceptedFileTypes": "image_and_pdf"
  }
}

​

Balises d’ancrage pour le placement automatique de champ

• Jusqu’à 100 balises d’ancrage par demande
• Disponible uniquement pour la création basée sur document (pas basée sur modèle)
• Les champs créés à partir des balises d’ancrage sont ajoutés en plus de tout champ spécifié manuellement

{
  "anchor_tags": [
    {
      "anchor_string": "{{SIGN_HERE}}",
      "type": "signature",
      "recipient_id": "temp_1",
      "width": 25,
      "height": 5
    }
  ]
}

​

Couleur de fond de champ

​

Changements de schéma

​

Nouveaux schémas

​

Field / TemplateField / SigningRequestField

​

Énumération du type de champ

• Ajout de file à la liste des types de champ acceptés

​

format_rules

• Accepte désormais FileFormatRules (avec acceptedFileTypes) en plus de DateFormatRules et du texte d’affichage de l’URL

​

Création de demande de signature

​

Changements majeurs

​

Changement de la valeur par défaut de use_signing_order

​

Guide de migration

​

v01.10.00

​

Nouvelles fonctionnalités

​

Logique de champ conditionnel

• required_conditions — Lorsqu’il est défini, remplace l’indicateur statique required. Le champ est obligatoire uniquement lorsque les conditions s’évaluent à vrai en fonction d’autres valeurs de champ.
• visibility_conditions — Lorsqu’il est défini, le champ est masqué sauf si les conditions s’évaluent à vrai. Les champs masqués ne sont pas validés lors de la soumission.

{
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          {
            "field_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "operator": "is_filled"
          }
        ]
      }
    ]
  }
}

​

Prise en charge des documents DOCX

• Création de modèle (POST /templates)
• Remplacement de document de modèle (POST /templates/{id}/replace-document)
• Création de demande de signature (POST /signing-requests)
• Mises à jour de modèle/demande de signature (PUT et PATCH)

​

Endpoint de piste d’audit

​

Contrôle du cadre de signature

• true — Afficher le cadre de signature avec l’ID de signature
• false — Masquer le cadre de signature
• null — Hériter du niveau parent

​

Forcer la suppression des conditions lors de la suppression d’un utilisateur

• false (par défaut) — La requête est rejetée avec une erreur listant les champs dépendants
• true — Supprime automatiquement les références de condition et poursuit la suppression

​

Changements de schéma

​

Field

​

Nouveaux schémas

​

SigningRequestSettings / WorkspaceSettings / Company

​

Suppression d’utilisateur de modèle et demande de signature

​

Nouveaux endpoints

​

Guide de migration

• Les propriétés de champ conditionnel ont pour valeur par défaut null (aucune condition)
• show_signature_frame a pour valeur par défaut null (hériter, ce qui est activé par défaut)
• force_remove_conditions a pour valeur par défaut false (préservant le comportement de rejet existant)
• La prise en charge DOCX est transparente — les téléversements PDF existants continuent de fonctionner sans changement
• L’endpoint de piste d’audit est purement additif

​

v01.09.00

​

Nouvelles fonctionnalités

​

Vérification par email OTP

• true — Exiger la vérification OTP avant l’accès au document
• false — Ne pas exiger la vérification OTP
• null — Hériter du niveau parent (espace de travail → entreprise, demande de signature → espace de travail)

PATCH /workspace-settings/{workspace_id}
{
  "settings": {
    "require_otp_verification": true
  }
}

PATCH /signing-requests/{id}
{
  "settings": {
    "require_otp_verification": false
  }
}

​

Remplacement du document de modèle

• Le document de remplacement doit avoir le même nombre de pages que l’original
• Les dimensions de page doivent correspondre avec une tolérance de 1pt
• Le document doit être fourni sous forme de PDF encodé en base64

POST /templates/{template_id}/replace-document
{
  "document": "JVBERi0xLjQKJeLjz9..."
}

​

Changements de schéma

​

SigningRequestSettings

​

WorkspaceSettings

​

Nouveaux endpoints

​

Guide de migration

​

v01.08.00

​

Nouvelles fonctionnalités

​

API des modèles d’email

PUT /workspace/{workspace_id}/email-templates/signing_request
{
  "subject": "Please sign: {{document_name}}",
  "body": "<p>Hi {{signer_name}},</p><p>Please sign using this link: {{signing_link}}</p>"
}

​

Prise en charge linguistique

​

Changements de schéma

​

Corrections d’horodatage

​

Schéma Company

​

Schéma Template (étendu)

​

Formes de réponse de demande de signature

​

SigningRequestSettings

​

Schéma Reminder

​

Schéma Webhook

​

SendSigningRequestResponse (corrigé)

​

WorkspaceSettings

​

v01.07.00

​

Nouvelles fonctionnalités

​

Signatures manuscrites uniquement

• Création de demandes de signature (POST /signing-requests)
• Création et envoi de demandes de signature (POST /signing-requests/create-and-send)
• Mises à jour complètes (PUT /signing-requests/{id})
• Mises à jour partielles (PATCH /signing-requests/{id})
• Création et mise à jour de modèle

{
  "settings": {
    "hand_drawn_only": true,
    "use_signing_order": false,
    "allow_download": true
  }
}

​

Changements de schéma

​

Champs de paramètres legacy dépréciés

​

Guide de migration

​

v01.06.00

​

Nouvelles fonctionnalités

​

Téléchargements PDF scindés

• Disponible uniquement lorsque la fonctionnalité de PDF scindé a été appliquée à la demande de signature
• Les URL expirent après 1 heure — récupérez à nouveau la demande de signature pour obtenir une URL fraîche
• Les champs d’erreur renvoient "file_not_accessible" si le chemin du fichier existe mais que le fichier est manquant

{
  "id": "sr-uuid",
  "status": "finished",
  "final_document_download_url": "https://storage.example.com/combined.pdf",
  "document_only_download_url": "https://storage.example.com/document.pdf",
  "document_only_download_error": null,
  "certificate_only_download_url": "https://storage.example.com/certificate.pdf",
  "certificate_only_download_error": null
}

​

Changements de schéma

​

Normalisation du type de champ

​

Guide de migration

​

v01.05.00

​

Nouvelles fonctionnalités

​

Avertissements de validation d’email

{
  "signing_request": { ... },
  "warnings": [
    "Recipient email 'user@compny' may have an invalid format"
  ]
}

• Les avertissements sont non bloquants — la requête aboutit tout de même
• Utile pour signaler des fautes de frappe potentielles ou des domaines email invalides
• Vérifiez le champ warnings ou warning dans la réponse pour les afficher aux utilisateurs

​

Guide de migration

​

v01.04.00

​

Nouvelles fonctionnalités

​

Nouveaux types de champ

• Automatiquement défini sur read_only: true
• Utilisez read_only_value pour définir l’URL cible
• Utilisez format_rules.urlDisplayText pour personnaliser le texte d’affichage

{
  "field": {
    "type": "url",
    "position": { "x": 100, "y": 200, "width": 150, "height": 30 },
    "page_number": 1,
    "read_only_value": "https://example.com/terms",
    "format_rules": { "urlDisplayText": "View Terms & Conditions" }
  }
}

​

Opérations PATCH sur les champs

• Peut désormais mettre à jour les propriétés, un seul utilisateur, OU un seul champ
• Inclure l’objet field dans le corps de la requête
• Inclure field.id pour mettre à jour un champ existant, l’omettre pour en créer un nouveau

• Peut désormais mettre à jour les propriétés, un seul destinataire, OU un seul champ
• Même structure d’objet field que pour les modèles

{
  "field": {
    "type": "text",
    "x": 100,
    "y": 200,
    "width": 200,
    "height": 30,
    "page": 1,
    "required": true,
    "assigned_to_user_id": "user-uuid"
  }
}

{
  "field": {
    "id": "field-uuid",
    "x": 120,
    "y": 220
  }
}

​

Correspondance d’utilisateur de modèle pour les destinataires

{
  "template_id": "template-uuid",
  "recipients": [
    {
      "template_user_id": "template-user-uuid",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com"
    }
  ]
}

• template_user_id est la méthode privilégiée pour la correspondance
• order reste disponible comme solution de repli

​

Changements de schéma

​

Énumération du type de champ

["text", "signature", "date", "checkbox", "initials", "dropdown", "radio"]

["text", "signature", "date", "checkbox", "initials", "dropdown", "radio_buttons", "textarea", "url"]

​

Schéma Recipient

• La création de demande de signature utilise désormais une référence au schéma Recipient partagé
• Ajout de la propriété template_user_id pour la correspondance explicite d’utilisateur de modèle

​

v01.03.00

​

Nouvelles fonctionnalités

​

API des domaines d’email

• GET /company/domains - Lister tous les domaines d’email de l’entreprise
• POST /company/domains - Ajouter un nouveau domaine d’email
• GET /company/domains/{id} - Obtenir les détails d’un domaine
• DELETE /company/domains/{id} - Supprimer un domaine
• POST /company/domains/{id}/verify-ownership - Vérifier la propriété du domaine via un enregistrement TXT
• POST /company/domains/{id}/finalize - Finaliser la configuration du domaine avec le fournisseur d’email
• POST /company/domains/{id}/verify-dns - Vérifier les enregistrements SPF, DKIM, DMARC
• POST /company/domains/{id}/set-primary - Définir le domaine d’envoi principal

• Domain - Configuration de domaine d’email avec statut de vérification
• DomainDnsRecord - Détails d’enregistrement DNS pour la vérification de domaine

​

Suivi du coût en crédits

• Ajout du champ credit_cost au schéma Template - Nombre de crédits consommés lors de l’envoi
• Ajout du champ credit_cost au schéma SigningRequest - Crédits consommés lors de l’envoi

​

Statut refusé de la demande de signature

• Ajout de declined aux valeurs d’énumération SigningRequest.status
• Ajout du champ date_declined au schéma SigningRequest

​

Améliorations de schéma

​

Champs de modèle

• Ajout du champ date_default pour définir des valeurs de date par défaut (format ISO 8601)
• Description enrichie de multi_group_id : explique le regroupement de champs mutuellement exclusifs pour les cases à cocher/boutons radio
• Ajout d’une clarification indiquant que page_number est indexé à partir de 1 et ne doit pas dépasser le nombre de pages du document

​

Champs de demande de signature

• Description de multi_group_id enrichie avec les mêmes améliorations que les champs de modèle

​

v01.02.00

​

Informations utilisateur enrichies

​

Améliorations du schéma TemplateUser

• first_name - Prénom du destinataire
• last_name - Nom du destinataire
• phone_number - Numéro de téléphone de contact
• street_address - Adresse postale
• city - Ville
• state_province - État ou province
• postal_code - Code postal
• country - Pays
• title - Titre du poste
• company - Nom de l’entreprise

​

Indicateurs de disponibilité pour l’envoi

• required_fields - Liste des champs de données destinataire requis selon la configuration du modèle
• missing_fields - Liste des champs requis actuellement vides
• required_read_only_fields - Champs en lecture seule nécessitant des valeurs préremplies
• ready_to_send - Booléen indiquant si le destinataire dispose de toutes les données requises

​

Améliorations du schéma SigningRequestUser

• declined_on - Horodatage indiquant quand le destinataire a refusé de signer
• decline_reason - Raison fournie par le destinataire pour le refus
• custom_fields - Valeurs de champ personnalisé pour le destinataire
• propriété has_value dans required_read_only_fields - Indique si le champ en lecture seule a une valeur

​

Changements de format de réponse

{
  "results": [
    {
      "id": "uuid",
      "name": "John Doe",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john@example.com",
      "designation": "Signer",
      "order": 1,
      "required_fields": ["email", "first_name"],
      "missing_fields": [],
      "ready_to_send": true
    }
  ]
}

​

v01.01.00

​

Nouveaux endpoints

​

Gestion des modèles

• POST /templates - Créer un nouveau modèle avec un PDF encodé en base64
• PATCH /templates/{id} - Mise à jour partielle (propriétés OU un seul utilisateur)
• PUT /templates/{id} - Mise à jour complète (propriétés, utilisateurs, champs, rappels)
• DELETE /templates/{id} - Suppression douce d’un modèle

​

Sous-ressources de modèle

• GET /templates/{id}/users - Obtenir tous les destinataires du modèle
• GET /templates/{id}/fields - Obtenir tous les champs du modèle
• GET /templates/{id}/reminders - Obtenir tous les rappels du modèle

​

Gestion des clés API

• POST /workspaces/{id}/api-key/regenerate - Générer une nouvelle clé API avec une période de grâce de 24 heures
• POST /workspaces/{id}/api-key/expire - Faire expirer immédiatement les clés en attente

​

Opérations enrichies

​

Mises à jour complètes

• template_properties - Mettre à jour les métadonnées et paramètres
• users - Upsert des utilisateurs (inclure l’id pour mettre à jour, l’omettre pour créer)
• deleted_users - Supprimer des utilisateurs avec une stratégie de gestion des champs (delete ou reassign)
• fields - Upsert des champs
• reminders - Upsert des rappels

{
  "template_properties": {
    "name": "Updated Template",
    "settings": {
      "allow_editing_before_sending": true
    }
  },
  "users": [
    {
      "id": "existing-uuid",
      "email": "updated@example.com"
    },
    {
      "first_name": "New",
      "last_name": "Signer",
      "email": "new@example.com",
      "designation": "Signer",
      "order": 2
    }
  ],
  "deleted_users": [
    {
      "user_id": "user-to-delete",
      "field_action": "reassign",
      "reassign_to_user_id": "existing-uuid"
    }
  ]
}

​

v01.00.02

​

Nouvelles fonctionnalités

​

API des champs personnalisés

• Custom Fields - Gestion des définitions de champ personnalisé

WorkspaceCustomField

{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "is_preset": true,
  "preset_value": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}

TemplateCustomField

{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "created_at": "datetime",
  "updated_at": "datetime"
}

SigningRequestCustomField

{
  "id": "uuid",
  "field_name": "string",
  "field_label": "string",
  "copied_from_template": true,
  "created_at": "datetime",
  "updated_at": "datetime"
}

​

Améliorations de schéma

​

Schéma TemplateField

• Propriété type explicite avec valeurs d’énumération
• Objet position avec x, y, width, height
• read_only et read_only_value pour les champs préremplis

​

v01.00.01

​

Version initiale

​

Tags / catégories de l’API

• Company - Informations et paramètres de l’entreprise
• Workspaces - Opérations de gestion de l’espace de travail
• Templates - Opérations de gestion de modèle
• Signing Requests - Opérations de demande de signature de document
• Webhooks - Configuration et gestion des webhooks
• JWT Management - Génération et révocation de jetons JWT
• Legacy - Endpoints dépréciés pour la rétrocompatibilité

​

Authentification

• Authentification par clé API via l’en-tête Authorization
• Support optionnel du préfixe Bearer

​

Limitation de débit

• Opérations de lecture (GET) : 200 requêtes/minute
• Opérations d’écriture (POST/PUT/PATCH/DELETE) : 120 requêtes/minute
• CRUD Webhook : 60 requêtes/minute
• Test de webhook : 10 requêtes/minute
• Opérations de clé API : 1 requête/minute
• Rotation de secret : 1 requête/minute

​

Schémas principaux

Company

• id, company_name, account_owner, account_owner_email
• website, icon_url, credits (lecture seule)
• date_created, date_changed

Workspace

• id, name, protected, api_key
• date_created, date_changed

Template

• id, name, description
• document_url (pré-signée, expire)
• document_url_expires_at
• date_created, date_changed

SigningRequest

• id, name, description
• document_url, document_url_expires_at
• document_page_count, status, expiration_hours
• settings, template_id
• Champs de date : date_created, date_sent, date_finished, date_cancelled, expires_at
• objet certificate avec statut de génération
• final_document_download_url, final_document_download_error

Recipient

• Base : id, first_name, last_name, email, designation, order
• Adresse : street_address, city, state_province, postal_code, country
• Professionnel : phone_number, title, company
• custom_fields pour des données supplémentaires
• Support d’ID temporaire pour la création basée sur document

Field

• id, type, position, page_number, required
• recipient_id, variable_name
• Spécifique au type : dropdown_options, date_default, date_signing_default
• Lecture seule : read_only, read_only_value, prefilled_data
• Formatage : format_rules, validation_rules

Webhook

• id, url, events, enabled
• date_created, date_changed

​

Gestion JWT

• Générer un JWT pour l’intégration de modèle
• Générer un JWT pour l’intégration de demande de signature
• Révoquer des jetons JWT

​

Guide de migration

​

Migration de v01.00.01 vers v01.00.02

• Aucun changement majeur
• API des champs personnalisés disponible à l’utilisation

​

Migration de v01.00.02 vers v01.01.00

• Aucun changement majeur
• Nouveaux endpoints de gestion de modèle disponibles
• Endpoints de régénération de clé API disponibles

​

Migration de v01.01.00 vers v01.02.00

• Aucun changement majeur
• Les utilisateurs de modèle et de demande de signature incluent désormais des champs supplémentaires
• Booléen ready_to_send disponible pour vérifier la disponibilité du destinataire

​

Migration de v01.02.00 vers v01.03.00

• Aucun changement majeur
• Configuration de domaine d’email disponible pour les domaines d’envoi personnalisés
• Statut declined ajouté à l’énumération de statut de demande de signature
• Suivi du coût en crédits disponible sur les modèles et demandes de signature

​

Migration de v01.03.00 vers v01.04.00

• Aucun changement majeur
• Le type de champ radio renommé en radio_buttons (les deux toujours acceptés)
• Nouveaux types de champ disponibles : textarea, url
• Les endpoints PATCH prennent désormais en charge les opérations sur un seul champ
• Utilisez template_user_id pour la correspondance explicite d’utilisateur de modèle dans les demandes de signature

​

Migration de v01.04.00 vers v01.05.00

• Aucun changement majeur
• Les avertissements de validation d’email sont purement additifs

​

Migration de v01.05.00 vers v01.06.00

• Aucun changement majeur
• URL de téléchargement PDF scindé disponibles sur les demandes de signature terminées
• Les entrées de type de champ initials/initial et textarea/text_area sont toutes deux acceptées avec normalisation automatique

​

Migration de v01.06.00 vers v01.07.00

• Aucun changement majeur
• Nouveau paramètre hand_drawn_only disponible dans les paramètres de demande de signature (par défaut false)
• Les champs de paramètres entiers dépréciés au niveau supérieur sont désormais visibles dans le schéma SigningRequest — utilisez plutôt l’objet settings

​

Migration de v01.07.00 vers v01.08.00

• Aucun changement majeur — les corrections de nom de champ de schéma reflètent les réponses réelles de l’API
• Nouvelle API des modèles d’email pour personnaliser les emails de notification de signature
• Champ language ajouté à Company et WorkspaceSettings
• Schéma de modèle étendu avec recipients, fields, settings, page_count, expiration_hours en ligne
• use_signing_order ajouté à SigningRequestSettings
• Le schéma Webhook inclut description, consecutive_failures, auto_disabled_at
• Les réponses de demande de signature sont divisées en formes spécifiques à chaque endpoint avec données en ligne

​

Migration de v01.08.00 vers v01.09.00

• Aucun changement majeur
• Nouveau paramètre require_otp_verification disponible aux niveaux entreprise, espace de travail et demande de signature
• Nouvel endpoint POST /templates/{id}/replace-document pour remplacer les PDF de modèle tout en préservant les champs

​

Migration de v01.09.00 vers v01.10.00

• Aucun changement majeur
• Logique de champ conditionnel disponible via required_conditions et visibility_conditions sur les champs
• Les fichiers DOCX sont désormais acceptés en plus du PDF dans tous les endpoints de téléversement de document
• Nouvel endpoint GET /signing-requests/{id}/audit pour récupérer les pistes d’audit
• Nouveau paramètre show_signature_frame aux niveaux entreprise, espace de travail et demande de signature
• Nouveau paramètre force_remove_conditions sur les opérations de suppression d’utilisateur

​

Migration de v01.10.00 vers v01.11.00

• Changement majeur : la valeur par défaut de use_signing_order est passée de false à true — définissez explicitement use_signing_order: false si vous comptez sur la livraison simultanée
• Nouveau type de champ file pour les téléversements de fichier du signataire
• Balises d’ancrage pour le placement automatique de champ à partir de marqueurs de texte dans les PDF
• Propriété background_color disponible sur tous les types de champ

​

Migration de v01.11.00 vers v01.12.00

• Aucun changement majeur
• Intégration du serveur MCP pour l’accès des assistants IA à l’API Firma
• Aucun nouvel endpoint API ni changement de schéma — spécification OpenAPI inchangée depuis v1.11.0

​

Migration de v01.12.00 vers v01.12.01

• Aucun changement majeur
• Nouveau champ variable_defined_name sur toutes les réponses de champ — renvoie le nom lisible par un humain de la définition de champ personnalisé, en plus du variable_name interne
• variable_defined_name accepté comme entrée pour la correspondance de champ sur POST /signing-requests/create-and-send

​

Migration de v01.15.03 vers v01.16.00

• Aucun changement majeur
• Nouvel endpoint GET /signing-requests/{id}/download pour récupérer une URL de téléchargement du document signé
• Téléchargements partiels disponibles lorsque allow_partial_download est activé dans les paramètres de demande de signature

​

Migration de v01.16.00 vers v01.17.00

• Aucun changement majeur
• Six nouveaux champs de couleur pouvant être null (color_primary, color_primary_fg, color_background, color_foreground, color_card, color_border) sur les paramètres Company et Workspace
• Nouveau schéma ColorPalette pour les couleurs d’expérience de signature résolues
• Les couleurs suivent une cascade à 3 niveaux : valeurs par défaut de Firma -> entreprise -> espace de travail

​

Migration de v1.19.0 vers v1.20.0

• Aucun changement majeur
• Nouveau paramètre disable_guided_navigation disponible aux niveaux entreprise, espace de travail, modèle et demande de signature
• Suit le même modèle de cascade que require_otp_verification : demande de signature -> espace de travail -> entreprise (la première valeur non null l’emporte)
• Par défaut false (défilement automatique activé), préservant le comportement existant

​

Migration de v1.20.0 vers v1.21.0

• Aucun changement majeur
• Nouveau paramètre email_local_part sur Company (GET/PATCH /company) et Workspace Settings (GET/PUT /workspace/{id}/settings)
• La valeur de l’espace de travail est prioritaire sur celle de l’entreprise ; la valeur par défaut est "support"
• S’applique uniquement lorsqu’un domaine personnalisé vérifié est configuré