Passer au contenu principal
Ce document fournit un journal des modifications détaillé de toutes les versions de l’API Firma, documentant les nouvelles fonctionnalités, les changements majeurs et les améliorations entre chaque version.
URL stables pour la référence API. La référence API se trouve désormais à des URL sans version, comme /fr/api-reference/templates/list-templates, et affiche toujours la dernière version. Les cinq versions précédentes restent disponibles dans le menu des versions. Les liens vers des versions plus anciennes redirigent vers la page actuelle, et les spécifications OpenAPI restent téléchargeables depuis les entrées ci-dessous.

Résumé des versions


v1.43.0

Date de sortie : 15 novembre 2026 Type de version : Version mineure Spécification OpenAPI : Télécharger la spécification v1.43.0 Pagination et totaux de la liste, nettoyage du texte du webhook de rebond, noms d’espace de travail dans les webhooks, règles des noms de destinataires et de préparation, et liens réparés de la documentation. Changements de comportement :
  • Dans le webhook de rebond, les valeurs message et sub_type ne contiennent plus de points de code de contrôle, de format, de séparation de ligne ni de substitution. Une valeur vide après ce nettoyage vaut null. message est limité à 500 points de code et sub_type à 64.
  • GET /signing-requests renvoie des pages et des totaux exacts pour toute liste de statuts qui contient exactement un statut parmi in_progress et expired (par exemple status=expired ou status=in_progress,declined), tant que 50 000 demandes de signature au plus doivent être vérifiées. Les totaux et les pages sont exacts pour les lignes lues. Une demande dont la position change parce qu’une autre demande a changé de statut pendant le même appel peut manquer dans cette réponse ; l’appel suivant la renvoie. Un filtre qui exigerait de vérifier plus de 50 000 demandes de signature est refusé avec 400 VALIDATION_ERROR et le texte “More than 50,000 signing requests would have to be checked for this filter. Narrow the request with created_after, created_before, name, signer_name or signer_email.” Sur ces appels de liste, un comptage en échec renvoie désormais 500 au lieu de 200. Sur ces listes, les recipients[] sont dans l’ordre de signature et les fields[] arrivent dans un ordre fixe, identique à chaque appel.
  • Les événements de webhook signing_request.created, signing_request.updated, signing_request.cancelled, signing_request.deleted et template.used portent désormais le vrai workspace.name.
  • Les enregistrements depuis le tableau de bord et depuis les éditeurs intégrés conservent les champs d’identité des destinataires, des CC et des utilisateurs de modèle, ainsi que les noms de document que l’enregistrement n’a pas modifiés.
  • Dans le tableau de bord et les éditeurs intégrés, les noms et fonctions de destinataire saisis conservent les apostrophes typographiques, les caractères U+2010 à U+2015 et le point médian, et les valeurs saisies sont limitées à 125 points de code pour first_name et last_name, 150 pour title et 255 pour company. Un enregistrement depuis un éditeur refuse un destinataire dont le prénom et le nom réunis dépassent 255 caractères.
  • Les réponses de préparation de /users des demandes de signature et des modèles utilisent format_rules.prefilledData et ignorent les préremplissages modifiables. La préparation reste indicative et peut changer pour des demandes existantes dans un sens comme dans l’autre. Par exemple, un libellé Title sans prefilledData n’exige plus title ; un prefilledData: "title" non modifiable l’exige désormais ; un préremplissage de fonction modifiable ne l’exige plus.
  • Un PUT qui ajoute un nouveau signataire ou approbateur exige first_name et une adresse e-mail, comme le fait déjà PATCH. Avec PATCH et PUT, un prénom vide une fois les espaces retirés compte comme absent pour un nouveau destinataire ou CC. Les autres parties de la requête sont tout de même appliquées ; renvoyez uniquement le destinataire corrigé.
  • Les liens internes réparés de la documentation Firma.dev fonctionnent désormais en anglais, en espagnol et en français.

Notes de migration

  • Si GET /signing-requests renvoie 400 VALIDATION_ERROR parce que plus de 50 000 demandes de signature devraient être vérifiées, affinez la requête avec created_after, created_before, name, signer_name ou signer_email.
  • Sur ces appels de liste, un comptage en échec renvoie 500 au lieu de 200.
  • Une demande absente d’une réponse de liste parce que sa position a changé est renvoyée par l’appel suivant.
  • Les réponses de préparation de /users peuvent changer pour des demandes existantes dans un sens comme dans l’autre ; la préparation reste indicative.
  • Un PUT qui ajoute un nouveau signataire ou approbateur nécessite first_name et une adresse e-mail. Un prénom vide une fois les espaces retirés compte comme absent. Les autres parties de la requête sont tout de même appliquées ; renvoyez uniquement le destinataire corrigé.
  • Un enregistrement depuis le tableau de bord ou un éditeur intégré refuse un nom complet de destinataire de plus de 255 caractères.

v1.42.0

Date de sortie : 12 novembre 2026 Type de version : Version mineure Spécification OpenAPI : Cette version n’ajoute aucune version de référence propre. Ses changements de référence sont publiés avec v1.43.0. Refus liés au cycle de vie, filtre de la liste des demandes refusées et corrections des webhooks. Les refus de l’API et le filtre de liste ci-dessous s’appliquent sur le chemin multi-documents, qui dessert toutes les entreprises depuis le 13 octobre 2026 ; les changements apportés aux webhooks s’appliquent à toutes les demandes. Changements de comportement :
  • POST /signing-requests/{id}/cancel sur une demande refusée renvoie 409 DECLINED et n’écrit rien. Traitez cette réponse comme ALREADY_CANCELLED. Une demande refusée puis annulée continue de renvoyer ALREADY_CANCELLED. Une demande expirée peut toujours être annulée. Un 409 CONFLICT signifie que la demande a changé d’état pendant l’annulation : réessayez une fois ; la réponse suivante indique l’état réel.
  • POST /signing-requests/{id}/resend sur une demande refusée renvoie 409 DECLINED ; sur une demande expirée, 409 EXPIRED. Aucun e-mail n’est envoyé lorsque la demande est déjà refusée ou expirée à l’arrivée de l’appel ; si elle est refusée ou expire pendant l’envoi des rappels, les destinataires déjà notifiés conservent leur e-mail et la réponse reste le 409. EXPIRED est définitif : créez une nouvelle demande.
  • Les refus de POST /signing-requests/{id}/send contiennent désormais un code : 400 DECLINED ou 400 ALREADY_CANCELLED. Le statut et le message restent inchangés.
  • GET /signing-requests?status=declined renvoie les demandes refusées (auparavant, la liste non filtrée). Une demande refusée puis annulée est répertoriée comme cancelled. Combiner in_progress ou expired avec un autre statut renvoie désormais tous les statuts demandés (auparavant, seulement les lignes in_progress ou expired).
  • Huit noms d’événements que Firma.dev n’envoie jamais sont retirés : signing_request.field.filled, signing_request.document.updated, signing_request.recipient.added, signing_request.recipient.updated, template.created, template.deleted, template.field.added, workspace.deleted. POST /webhooks et PUT /webhooks/{id} les retirent de la liste soumise et signalent chacun dans un tableau warnings ; une liste vide après ce retrait renvoie 400 VALIDATION_ERROR. Les webhooks enregistrés ne sont pas modifiés ; un PUT sans events les laisse tels quels.
  • signing_request.recipient.signed : all_complete vaut true uniquement lorsque tous les signataires et approbateurs de la demande ont terminé (auparavant true pour chaque événement lorsque l’ordre de signature était activé). Utilisez signing_request.completed pour détecter la fin ; un cachet d’organisation peut encore être en attente.
Ajouts :
  • Nouvel événement auquel vous pouvez vous abonner, signing_request.recipient.email_bounced (enveloppe standard ; charge utile dans le guide des webhooks). Un destinataire peut produire un rebond doux suivi d’un rebond dur, ainsi que d’autres rebonds après un rappel. Chaque webhook est limité à 100 événements par minute, tous types d’événements confondus ; abonnez un webhook dédié à email_bounced lorsque vous effectuez des envois en masse.
  • signing_request.viewed contient l’objet signing_request complet (workspace_id, created_at, sent_at, expires_at, document_page_count, test), les champs first_name, last_name, order et designation du destinataire, ainsi que l’objet workspace.
  • signing_request.completed contient les destinataires (signataires et approbateurs avec signed_at) au lieu d’un tableau vide.
Remarque : si le chemin multi-documents est désactivé, les demandes qui ne sont pas multi-documents retrouvent le comportement précédent pour les refus d’annulation et de renvoi et pour les codes de refus de send ; dans ce cas, le renvoi d’une demande refusée ou expirée renvoie 500, et ?status=declined renvoie alors la liste non filtrée pour toutes les entreprises jusqu’à la réactivation du chemin. Les changements apportés aux webhooks persistent sur tous les chemins : le catalogue de 27 événements, la clé warnings, l’enveloppe email_bounced, la charge utile de viewed, all_complete et completed.recipients.

Notes de migration

  • Si une annulation renvoie 409 CONFLICT, réessayez une fois ; la réponse suivante indiquera l’état réel.
  • EXPIRED est définitif : créez une nouvelle demande.
  • Traitez 409 DECLINED lors d’une annulation comme ALREADY_CANCELLED.
  • POST /webhooks et PUT /webhooks/{id} peuvent renvoyer un tableau warnings qui nomme les événements retirés qu’ils ont supprimés.
  • all_complete vaut true uniquement lorsque tous les signataires et approbateurs ont terminé ; utilisez signing_request.completed pour détecter la fin.

v1.40.4

Date de sortie : 23 octobre 2026 Type de version : Version corrective Spécification OpenAPI : Télécharger la spécification v1.40.4

Corrections de la référence

La spécification OpenAPI décrit désormais ce que l’API fait déjà dans ces cas. L’API elle-même n’a pas changé.
  • Rotation du secret de webhook. POST /webhooks/rotate-secret et POST /workspaces/{id}/webhooks/rotate-secret autorisent une rotation par heure (la spécification indiquait une rotation par minute) ; un deuxième appel dans l’heure renvoie 429 avec le code COOLDOWN_ACTIVE. Un seul secret précédent est conservé : une nouvelle rotation pendant la période de chevauchement de 7 jours le remplace. L’en-tête X-RateLimit-Limit de POST /webhooks/rotate-secret indique désormais 60 requêtes par minute.
  • Envoi d’une demande. POST /signing-requests/{id}/send sur une demande déjà envoyée renvoie 409 avec le code ALREADY_SENT (la spécification indiquait 400), et renvoie 409 avec le code SEND_IN_PROGRESS pendant qu’un autre envoi est en cours. Une demande annulée ou refusée renvoie 400. L’exemple de réussite correspond désormais à la réponse : success, message, sentTo, sentAt. Son en-tête X-RateLimit-Limit indique désormais 120 requêtes par minute.
  • Création et envoi. Lorsque l’étape d’envoi de POST /signing-requests/create-and-send échoue avant que la moindre partie de l’envoi ait commencé, la demande de signature est supprimée et une erreur est renvoyée ; aucun brouillon n’est conservé. Si l’envoi avait déjà commencé, la demande est conservée et la réponse 409 contient son signing_request_id.
  • Liste des demandes de signature. Sur GET /signing-requests, signer_email effectue une correspondance partielle sans distinction entre majuscules et minuscules (la spécification indiquait une correspondance exacte). Les demandes supprimées en douceur sont incluses par défaut avec le statut deleted ; le paramètre exclude_deleted=true, désormais documenté, les exclut.
  • Téléchargements partiels. GET /signing-requests/{id}/download renvoie un instantané de progression partielle pour toute demande envoyée qui n’est pas terminée. Il n’existe aucun paramètre allow_partial_download. Une demande terminée dont le certificat d’achèvement est encore en cours de génération renvoie 409.
  • document_only_hash. La description indique désormais quel fichier est haché : le PDF scellé de chaque document, et non le fichier téléversé ni le PDF final avec le certificat.

Notes de migration

  • Aucun changement des requêtes, des réponses ni des livraisons de webhooks.
  • Si votre logique de nouvelle tentative pour POST /signing-requests/{id}/send attendait un 400 pour une demande déjà envoyée, gérez plutôt 409 ALREADY_SENT.

v1.40.3

Date de sortie : 20 octobre 2026 Type de version : Version corrective

Preuve du code à usage unique dans la piste d’audit

La piste d’audit enregistre désormais qu’un signataire a saisi le code à usage unique, avec une référence à l’enregistrement du code vérifié, et verify-signing-otp répond plus précisément lorsqu’un code ne peut pas être vérifié.
  • Événements d’audit. GET /signing-requests/{id}/audit renvoie des événements otp_verified avec details.channel = "email" et details.otp_code_id, décrits comme Entered the one-time code sent by email. Les événements document_finished portent details.otp_code_id lorsque la session qui a terminé le document était liée à un code vérifié. Cela s’applique aux demandes de moins de 1 000 lignes de suivi ; les demandes plus volumineuses conservent la troncature actuelle.
  • Réponses de verify-signing-otp.
    • Une erreur de base de données renvoie 500 INTERNAL au lieu de OTP_NOT_FOUND.
    • Un signataire inconnu renvoie 404 SIGNING_USER_NOT_FOUND.
    • Un signataire d’une demande supprimée renvoie 404 SIGNING_REQUEST_NOT_FOUND. Auparavant, un code valide d’une demande supprimée était encore accepté.
    • Un signingUserId mal formé renvoie 400 INVALID_INPUT.
    • Une demande qui ne peut plus être vérifiée (annulée, refusée, expirée, déjà signée, pas encore envoyée, ce n’est pas le tour du signataire ou cachet en pause) renvoie 200 avec code: "SIGNING_STATE_CHANGED" et state.
    • Un code correct avec une erreur transitoire ne consomme plus de tentative.
  • Aucun changement du schéma OpenAPI. event reste du texte libre. Cette version n’ajoute aucune version de référence et ne lie aucun document OpenAPI.
  • Descriptions d’audit administrateur. GET /signing-requests/{id}/audit et la piste d’audit du tableau de bord décrivent une annulation depuis le tableau de bord comme Signing Request Cancellation requested et une suppression depuis le tableau de bord comme Signing Request Deletion requested. Une nouvelle tentative de certificat ajoute Certificate regeneration requested. Firma.dev écrit chaque ligne avant le changement, de sorte que la ligne reste lorsque l’action échoue ensuite ou perd une course ; « requested » ne confirme pas que l’action est terminée. Les lignes écrites avant cette version conservent l’ancienne formulation (Signing Request Cancelled / Signing Request Deleted).

v1.40.2

Date de sortie : 19 octobre 2026 Type de version : Version corrective Spécification OpenAPI : Télécharger la spécification v1.40.2

Liste des événements de webhook

La liste events de POST /webhooks et PUT /webhooks/{id} dans la spécification OpenAPI nomme désormais les 26 événements qu’envoie Firma.dev, les mêmes que décrit le guide des webhooks. Depuis la v1.37.0, la liste nommait des événements que l’API refuse et omettait des événements qu’elle envoie. L’API elle-même n’a pas changé.
  • Ajoutés, déjà envoyés : signing_request.updated, signing_request.certificate.generated, signing_request.reminder.sent, signing_request.recipient.signed, signing_request.recipient.declined et signing_request.recipient.identity_changed.
  • Retirés, jamais acceptés par l’API (une requête qui en nomme un renvoie 400 VALIDATION_ERROR) : signing_request.declined, signing_request.voided, signing_request.field.completed, signing_request.resent et signing_request.credits.purchased. Pour un signataire qui refuse, abonnez-vous à signing_request.recipient.declined ; pour une demande annulée, à signing_request.cancelled.
  • Retirés, acceptés par l’API mais jamais envoyés : template.created, template.deleted, template.field.added et workspace.deleted. Un webhook qui les nomme reste valide, mais aucun événement de ces types n’arrive.

Notes de migration

  • Aucun changement des requêtes, des réponses ni des livraisons de webhooks.
  • Si vous avez généré un client ou une validation à partir de la spécification, régénérez-les : l’ancienne liste refusait des événements auxquels vous pouvez vous abonner et proposait des événements que l’API refuse.

v1.40.1

Date de sortie : 18 octobre 2026 Type de version : Version corrective Spécification OpenAPI : Télécharger la spécification v1.40.1

PDF endommagés

Depuis le 18 octobre 2026, Firma.dev refuse un PDF dont une page n’a aucun contenu valide, par exemple une page dont le contenu pointe vers les données d’une autre page au lieu de ses propres instructions de dessin. Une telle page s’affiche vide, et Firma.dev ne peut pas générer le certificat de finalisation d’une demande qui la contient. La requête renvoie 400 MALFORMED_PDF :
  • malformed_pages liste les numéros (indexés à partir de 1) des pages endommagées. Le message nomme la première.
  • Sur POST /signing-requests, POST /signing-requests/create-and-send et POST /templates, document_position (indexé à partir de 1, dans l’ordre des documents de la requête) désigne le document, et document_id est ajouté lorsque le document provient de document_id ou document_ids.
  • Rien n’est écrit : aucun modèle, aucune demande de signature, aucun débit de crédits, aucun e-mail.
  • Sur POST /signing-requests, POST /signing-requests/create-and-send et POST /templates, un téléversement désigné par document_id ou document_ids est consommé lorsque cette erreur est renvoyée : téléversez à nouveau le fichier réparé avec POST /documents pour obtenir un nouvel identifiant. Sur les routes d’ajout et de remplacement de /documents, le téléversement est conservé.
  • Réexporter le fichier depuis l’application qui l’a créé, ou l’enregistrer à nouveau depuis un éditeur PDF, le répare généralement.
Les routes qui la renvoient sont celles qui acceptent un document : POST /templates, PATCH /templates/{id}, PUT /templates/{id}, POST /templates/{id}/replace-document, POST /templates/{id}/documents, PATCH /templates/{id}/documents/{document_id}, POST /signing-requests, POST /signing-requests/create-and-send, PATCH /signing-requests/{id}, POST /signing-requests/{id}/documents et PATCH /signing-requests/{id}/documents/{document_id}.

PDF illisibles

Depuis le 17 octobre 2026, un document qui ne peut pas être lu comme un PDF, y compris un PDF chiffré, renvoie 400 VALIDATION_ERROR avec le message The uploaded document is not a readable PDF sur les mêmes routes. Auparavant, il renvoyait 500. Les routes d’ajout et de remplacement de /documents répondaient déjà ainsi, et le font désormais aussi pour un fichier qui commence comme un PDF mais dont l’arbre des pages ne peut pas être lu.

Notes de migration

  • Les requêtes avec des PDF valides se comportent comme avant.
  • Là où vous téléversez des documents, gérez 400 MALFORMED_PDF : affichez le message et demandez un fichier réparé. Renvoyer le même fichier renvoie la même erreur.
  • Si vous analysez strictement les réponses d’erreur, acceptez malformed_pages, document_position et document_id.
  • Un PDF illisible renvoie désormais 400, et non 500. Ne le réessayez pas.

v1.40.0

Date de sortie : 17 octobre 2026 Type de version : Version mineure Spécification OpenAPI : Télécharger la spécification v1.40.0

Boutons de la page de signature

Deux nouveaux paramètres contrôlent les boutons que les signataires et les approbateurs voient sur la page de signature, hébergée ou intégrée :
  • allow_decline affiche le bouton Refuser de signer. Lorsque la valeur est false, le bouton est masqué pour chaque signataire et approbateur, et Firma.dev n’accepte plus aucun refus. Personne ne peut refuser la demande de signature dans Firma.dev ; elle ne peut donc être arrêtée qu’en l’annulant.
  • show_save_for_later affiche le bouton Sauvegarder et terminer plus tard. Lorsque la valeur est false, seul le bouton est masqué.
Firma.dev utilise la valeur de la demande de signature. Si elle est null, la valeur de l’espace de travail s’applique, et si celle-ci est aussi null, celle de l’entreprise. La valeur par défaut de l’entreprise est true : les pages de signature restent inchangées tant que vous ne définissez pas de valeur.
  • Une demande de signature créée à partir d’un modèle (template_id sur POST /signing-requests et POST /signing-requests/create-and-send, ou POST /templates/{id}/duplicate) copie les valeurs du modèle lors de sa création. Sur les deux routes de création, une valeur dans les settings de la demande remplace celle du modèle ; null y signifie la valeur de l’espace de travail. POST /templates/{id}/duplicate copie toujours les valeurs du modèle. Modifier le modèle ensuite ne change pas les demandes de signature déjà créées à partir de celui-ci.
  • POST /templates/{id}/copy copie les deux valeurs dans le nouveau modèle.
  • Un changement de la valeur de l’espace de travail ou de l’entreprise s’applique à chaque demande de signature dont la propre valeur est null, y compris les demandes déjà envoyées et celles créées avant cette version.
  • Les réponses renvoient les valeurs sous la forme true, false ou null : dans settings des modèles (GET /templates, GET /templates/{id}, POST /templates, PUT /templates/{id}) et des demandes de signature (GET /signing-requests, GET /signing-requests/{id} et les réponses de création), et au premier niveau de GET /company/settings et GET /workspace/{workspace_id}/settings. Les valeurs de l’entreprise sont toujours true ou false.
  • Toute autre valeur, comme une chaîne ou un nombre, renvoie 400 VALIDATION_ERROR en nommant la clé (par exemple settings.allow_decline must be a boolean or null) et n’écrit rien. PUT /company/settings refuse aussi null.

Limite de taille des requêtes

Depuis le 13 octobre 2026, un corps de requête de plus de 6 291 456 octets (6 Mio) renvoie 413 REQUEST_TOO_LARGE avec le corps d’erreur standard error et code. Auparavant, la passerelle répondait 502. La référence de l’API le documente sur POST /templates, POST /signing-requests, POST /signing-requests/create-and-send et POST /documents. Pour envoyer un document plus volumineux, demandez une URL de téléversement avec POST /documents, téléversez-y le fichier, puis transmettez document_id ou document_ids au lieu du base64 intégré.

Notes de migration

  • Le changement est additif. Les requêtes qui n’envoient jamais allow_decline ni show_save_for_later se comportent comme avant, et les deux boutons restent visibles tant qu’aucune valeur n’est définie.
  • Si vous analysez les réponses de manière stricte, acceptez les deux nouvelles clés dans les réponses des modèles, des demandes de signature, des paramètres de l’espace de travail et des paramètres de l’entreprise.
  • Si vous envoyez des documents volumineux en base64 intégré, gérez 413 REQUEST_TOO_LARGE ou téléversez les fichiers avec POST /documents.

v1.39.1

Date de sortie : 12 octobre 2026 Type de version : Version corrective Spécification OpenAPI : Télécharger la spécification v1.39.1

Mise à jour, 13 octobre 2026

  • Sur POST /signing-requests et POST /signing-requests/create-and-send avec template_id, lorsque le modèle n’a pas de destinataires propres et que seal_participants est absent ou vaut null, les cachets hérités conservent désormais l’ordre du modèle en premier (1..k), suivis par les destinataires de la demande (à partir de k+1). Les tableaux de remplacement explicites, les modèles avec destinataires et les demandes sans cachets conservent leur comportement d’ordre existant.
  • Les remplacements via PATCH /seals/{id} exigent désormais statement avec accepted: true, version: 1, language, text exactement égal au statement_text enregistré de GET /seals/{id} et signatory_name (signatory_title facultatif). Cela s’applique aux changements de image, typed, display_name, signatory_title ou statement. Sans statement, la demande renvoie 400 SEAL_STATEMENT_REQUIRED et n’écrit rien. Le comportement de création de POST /seals reste inchangé.
  • Chaque remplacement enregistre son propre moment d’attestation, l’auteur de l’appel et le signataire fourni. Le texte de la déclaration, le hash, la langue, la version de la déclaration et authority_name restent ceux de la version 1 du cachet. Les demandes déjà envoyées conservent leur version figée ; celles envoyées après le remplacement utilisent la nouvelle version, dont le signataire et la date d’attestation apparaissent sur leurs certificats.
  • Les objets de cachet de POST /seals, GET /seals, GET /seals/{id}, PATCH /seals/{id} et des webhooks organization_seal.created, organization_seal.updated et organization_seal.deleted incluent désormais statement_text et statement_hash. Les identifiants de l’utilisateur et de la clé API de l’attestant, l’adresse IP et le user agent sont exclus de ces objets de cachet.

Cachets d’organisation à partir de modèles

POST /signing-requests et POST /signing-requests/create-and-send avec un template_id copient désormais les participants de cachet du modèle et leurs champs de cachet. La clé seal_participants détermine le comportement :
  • Absente ou null : la demande hérite des cachets du modèle.
  • Un tableau : le tableau remplace les cachets du modèle. Les champs de cachet du modèle ne sont pas copiés.
  • [] : la demande est créée sans cachet.
  • Tout autre type renvoie 400 VALIDATION_ERROR. Cette vérification s’applique à toutes les routes de création, avec ou sans template_id.
Les champs du corps ne font que remplacer ceux du modèle : sur un modèle qui a des champs, les cachets d’un tableau de remplacement ne peuvent donc obtenir aucun champ tampon dans cet appel, et l’envoi renvoie 400 SEAL_NO_IMAGE_FIELD. Pour utiliser vos propres cachets avec leurs champs, créez à partir d’un document (ou, sur POST /signing-requests uniquement, utilisez un modèle sans champs et affectez les champs du corps avec seal_participant_temp_id). Sinon, héritez des cachets du modèle. Un cachet hérité utilise la version actuelle du cachet. Si le cachet n’a pas de version actuelle, ou si cette version est révoquée ou supprimée, la création renvoie 409 SEAL_UNAVAILABLE et rien n’est écrit. Si au moins un cachet hérité est conservé et que les cachets d’organisation ne sont pas activés, la création renvoie 503 SEALS_DISABLED. Un cachet hérité limité à un autre espace de travail que celui de la demande, ou que l’entreprise de la clé API ne peut pas voir, est écarté, avec ses champs. Il figure dans la réponse avec dropped: true, après les autres entrées. Toutes les entrées conservées portent dropped: false.
seal vaut null lorsque l’entreprise de la clé API ne peut pas voir le cachet. Un cachet valable pour toute l’entreprise n’est jamais écarté.

Ordre avec un modèle

Lorsqu’une création avec template_id résout au moins un cachet, les destinataires et les cachets sont renumérotés de 1 à n. Les cachets hérités conservent leur position par rapport aux destinataires du modèle ; les cachets fournis dans un tableau de remplacement sont placés selon leur order. Un cachet passe en premier lorsqu’il est à égalité avec un destinataire. Une telle création renvoie 201 là où elle renvoyait auparavant 400 INVALID_SIGNING_ORDER ou 400 SEAL_ORDER_COLLISION. La réponse indique les ordres renumérotés.
  • Depuis le 13 octobre 2026, si le modèle n’a aucun destinataire et que seal_participants est absent ou vaut null, les cachets hérités conservent l’ordre du modèle en premier (1..k) ; les destinataires de la demande suivent (à partir de k+1).
  • Sur POST /signing-requests, un recipient_id numérique sur un champ continue de compter les destinataires comme s’ils étaient numérotés sans le cachet.
  • Les créations à partir d’un document (document, document_id, document_ids) avec des participants de cachet explicites sont inchangées : les vérifications d’ordre partagé brutes s’appliquent.

Champs tampon et envoi

Un cachet a besoin d’au moins un champ tampon. La création ne le vérifie pas, mais l’envoi d’une demande de signature dont le cachet n’a aucun champ tampon renvoie 400 SEAL_NO_IMAGE_FIELD. Donnez à chaque cachet au moins un champ tampon.

Duplication d’un modèle

Sauf pour les entreprises activées pour les fonctionnalités multi-documents, POST /templates/{id}/duplicate copie les participants de cachet du modèle et leurs champs dans la nouvelle demande de signature, et les renvoie dans seal_participants ([] s’il n’y en a aucun). Chaque cachet conservé utilise la version actuelle de sa lignée. Si la lignée n’a pas de version actuelle, ou si cette version est révoquée ou supprimée, la route renvoie 409 SEAL_UNAVAILABLE. Un cachet limité à un autre espace de travail que l’espace de travail cible, ou que l’entreprise de la clé API ne peut pas voir, est écarté et listé avec dropped: true. Si au moins un cachet est conservé et que les cachets d’organisation ne sont pas activés, la route renvoie 503 SEALS_DISABLED. Ces erreurs sont renvoyées avant toute écriture. Pour les entreprises activées pour les fonctionnalités multi-documents, cette route rattache telle quelle la version de cachet enregistrée dans le modèle. Un cachet qui a été remplacé, révoqué ou supprimé depuis échoue à l’envoi. La réponse ne contient pas la clé seal_participants.

seal_attribute

Un champ de texte appartenant à un cachet accepte seal_attribute : display_name ou signatory_title. Il détermine quelle propriété du cachet le champ imprime. POST /signing-requests et POST /signing-requests/create-and-send l’acceptent, à partir d’un document ou d’un modèle. Toute autre valeur renvoie 400 VALIDATION_ERROR ; null est accepté.
  • POST /signing-requests/create-and-send à partir d’un document conserve désormais seal_attribute. Auparavant, il était ignoré.
  • Un champ de cachet copié depuis un modèle conserve la mise en forme du champ du modèle. seal_attribute sur la demande remplace uniquement la propriété imprimée.

Modèles

  • GET /templates/{id} et PUT /templates/{id} renvoient seal_participants, triés par order, [] lorsque le modèle n’en a aucun. Chaque entrée a la même forme que les participants de cachet ailleurs.
  • POST /templates n’accepte pas seal_participants, recipients ni fields. Il les ignore et renvoie un tableau warnings avec une chaîne par clé présente, par exemple seal_participants is not accepted on POST /templates and was ignored; add it with PATCH or PUT /templates/{id}. Sans ces clés, la réponse est inchangée.

Autres changements

  • Corrigé : seal_participants sur GET /signing-requests/{id}, GET /signing-requests, POST /signing-requests et POST /signing-requests/create-and-send renvoie désormais chaque participant de cachet d’organisation avec son cachet (identifiant, lignée, version, nom et nom d’affichage) pour toutes les entreprises. Auparavant, cette liste était vide, alors que le cachet lui-même était bien enregistré et appliqué sur le document. Cette correction ne modifie que ce que renvoie l’API ; les documents stockés, les signatures et les webhooks ne sont pas modifiés par elle.
  • Les certificats de finalisation dessinent désormais les champs tampon, de date et de texte du cachet appliqué, et listent chaque participant de cachet dans le tableau des signataires, dans l’ordre de signature. Le certificat n’est pas généré tant qu’un cachet est en attente (non appliqué ou en pause). Un cachet appliqué automatiquement à la finalisation, sans destinataire déclencheur, ne bloque plus le certificat ; sa ligne d’audit indique “après que tous les participants précédents ont terminé leur participation” (dans la langue du certificat).

Documentation et référence de l’API

La référence de l’API de cette version documente ce qui suit. Cela décrit des réponses que l’API donnait déjà.
  • Chaque entrée de seal_participants sur POST /signing-requests et POST /signing-requests/create-and-send exige temp_id et order. seal_id est facultatif : sans lui, le cachet par défaut de l’espace de travail est utilisé ou, si l’espace de travail n’en a pas, le cachet par défaut de l’entreprise, et l’appel renvoie 400 SEAL_UNAVAILABLE lorsque ni l’un ni l’autre n’existe. La référence indiquait seal_id comme obligatoire et temp_id comme facultatif.
  • Le corps seal_participant de PATCH /signing-requests/{id} et PATCH /templates/{id} est documenté tel que l’API le lit : id, seal_id, order et, sur les demandes de signature, swap_to_seal_id. La clé participant_id que montraient les références précédentes n’était jamais lue ; utilisez id. Ajouter un participant de cachet répond 201, et le mettre à jour ou le remplacer répond 200, tous deux avec { "seal_participant": ... }. Ces routes renvoient 503 SEALS_DISABLED lorsque les cachets d’organisation ne sont pas activés et qu’un participant de cachet est ajouté ou que son cachet est changé. Sur PATCH /signing-requests/{id}, un champ qui appartient à un participant de cachet n’accepte que des changements de position et de page ; les autres clés, recipient_id comprise, sont ignorées.
  • Un remplacement de cachet sur PATCH /signing-requests/{id} documente ses réponses : 403 PROTECTED_KEY_REQUIRED lorsque la clé API n’est pas celle de l’espace de travail protégé ; 404 NOT_FOUND lorsque le nouveau cachet n’existe pas, appartient à une autre entreprise ou est limité à un autre espace de travail ; 409 SEAL_UNAVAILABLE lorsque le nouveau cachet est révoqué, supprimé ou n’est pas la version actuelle ; 409 SEAL_MUTATION_NOT_ALLOWED lorsque la demande n’a pas été envoyée ou que le participant n’est pas en pause ; 400 SEAL_FIELD_REQUIRED lorsque le participant n’a pas de champ tampon.
  • Le corps 200 de DELETE /signing-requests/{id}/seal-participants/{participant_id} est { "deleted": true }.
  • Le tableau fields de la réponse de POST /signing-requests/create-and-send liste tous les champs actifs, y compris les champs des participants de cachet. Chaque élément est l’enregistrement du champ tel qu’il est stocké, et non la forme Field utilisée dans les requêtes (par exemple, le type se trouve dans field_type).
  • POST /templates/{id}/copy documente ses seal_participants (comportement inchangé).
  • PUT /templates/{id} documente son tableau de requête seal_participants (TemplateSealParticipantInput), qui remplace l’ensemble des cachets du modèle.
  • Le 400 de POST /signing-requests/create-and-send liste SEAL_NO_IMAGE_FIELD (un cachet sans champ tampon est refusé à l’envoi).
  • Les paramètres dont le null a une signification (require_otp_verification, require_terms_acceptance, allow_presigning_download, terms_url, le recipient_id ou assigned_to_user_id d’un champ, identity_editable_fields, et les paramètres d’espace de travail show_signature_frame et show_partial_watermark) indiquent désormais ce que fait null.

Notes de migration

  • Pour les remplacements de cachets à partir du 13 octobre 2026, lisez GET /seals/{id} et envoyez statement sur PATCH /seals/{id} : accepted: true, version: 1, language, le statement_text exact enregistré comme text et signatory_name (signatory_title facultatif). Gérez 400 SEAL_STATEMENT_REQUIRED et acceptez statement_text et statement_hash dans les objets de cachet.
  • Un POST /signing-requests ou POST /signing-requests/create-and-send avec template_id et sans clé seal_participants hérite désormais des cachets du modèle. Envoyez "seal_participants": [] pour créer sans eux. null hérite également (y compris un client qui envoie null pour un champ non défini).
  • Une valeur de seal_participants qui n’est ni un tableau ni null renvoie désormais 400 VALIDATION_ERROR sur POST /signing-requests et POST /signing-requests/create-and-send ; auparavant, elle était ignorée.
  • Si vous analysez les réponses de manière stricte, acceptez les nouvelles clés : dropped dans les réponses de création, warnings sur POST /templates, et seal_participants sur GET /templates/{id}, PUT /templates/{id} et POST /templates/{id}/duplicate.

v1.39.0

Mise à jour, 13 octobre 2026 : Les fonctionnalités multi-documents sont disponibles pour toutes les entreprises. Aucune activation n’est nécessaire. Les restrictions d’activation des notes de version originales ci-dessous décrivent le déploiement initial.
Date de sortie : 12 octobre 2026 Type de version : Version mineure Spécification OpenAPI : Télécharger la spécification v1.39.0

Plusieurs documents par modèle et par demande de signature

Un modèle ou une demande de signature peut désormais contenir jusqu’à 20 documents, avec une limite de 100 Mo par ensemble de documents. Vous pouvez le créer à partir de plusieurs téléversements, puis ajouter, remplacer, renommer, réordonner, supprimer et télécharger ses documents un par un.
Les fonctionnalités multi-documents nécessitent une activation pour l’entreprise de votre espace de travail. Cela concerne les routes /documents, document_ids avec plus d’un identifiant, les balises d’ancrage par document (anchor_tags[].document_index) et les clés de réponse documents, documents_version et documents_layout_version. Si votre entreprise n’est pas activée :
  • Les routes /documents renvoient 404 NOT_FOUND, exactement comme un endpoint inconnu.
  • Les trois clés de réponse sont absentes.
  • document_index sur une balise d’ancrage n’est pas appliqué : une création à un seul document l’accepte avec un avertissement de propriété inconnue et utilise l’unique document.
  • POST /templates, POST /signing-requests et POST /signing-requests/create-and-send avec plus d’une entrée dans document_ids (les identifiants répétés comptent) renvoient 409 MULTI_DOCUMENT_READ_ONLY avant toute création.
Tant que la modification multi-documents est suspendue, les écritures sur un modèle ou une demande de signature multi-documents renvoient 409 MULTI_DOCUMENT_READ_ONLY. Les lectures continuent de fonctionner.

Créer avec plusieurs documents

POST /templates, POST /signing-requests et POST /signing-requests/create-and-send acceptent document_ids. Transmettez de 1 à 20 identifiants de téléversement temporaire de POST /documents, dans l’ordre des documents.
  • Envoyez exactement une source de document : document, document_id ou document_ids (ou template_id sur les routes des demandes de signature). En envoyer plusieurs renvoie 400 CONFLICTING_DOCUMENT_SOURCE.
  • Un identifiant répété renvoie 400 DUPLICATE_DOCUMENT_ID. Plus de 20 identifiants renvoient 400 MAX_DOCUMENTS_EXCEEDED. Un téléversement inconnu ou expiré renvoie 400 DOCUMENT_UPLOAD_NOT_FOUND. Un ensemble de plus de 100 Mo renvoie 413 DOCUMENT_SET_TOO_LARGE.
  • document n’est plus indiqué comme obligatoire sur POST /templates, car document_id ou document_ids peuvent le remplacer.

Balises d’ancrage par document

Pour les entreprises activées, les balises d’ancrage acceptent un nouveau document_index : la position (à partir de 1) dans document_ids du document dans lequel effectuer la recherche. Il n’a de sens que pour les demandes multi-documents.
  • Avec un seul document, document_index est facultatif et vaut 1 par défaut.
  • Avec plusieurs documents, il est obligatoire. Une valeur manquante renvoie 400 ANCHOR_DOCUMENT_REQUIRED ; une valeur hors limites renvoie 400 VALIDATION_ERROR.

Nouveaux endpoints

Chaque ajout, remplacement, renommage, réordonnancement et suppression renvoie l’ensemble complet des documents après le changement, avec documents, documents_version et documents_layout_version.
  • Un document de remplacement doit avoir le même nombre de pages, et chaque page doit avoir la même taille à 1 pt près. Sinon, la requête renvoie 400 PAGE_COUNT_MISMATCH ou 400 DIMENSION_MISMATCH. Sur une demande de signature, un document placé avec des balises d’ancrage n’est remplacé que si les balises d’ancrage du document de remplacement se résolvent exactement comme enregistré. Sinon, la requête renvoie 400 ANCHOR_MISMATCH.
  • Une demande de signature envoyée, terminée, annulée ou refusée renvoie 409 DOCUMENT_SET_LOCKED à toute écriture de documents.
  • Un identifiant de document qui n’appartient pas au modèle ou à la demande de signature renvoie 404 DOCUMENT_NOT_FOUND. Un identifiant manquant ou répété lors d’un réordonnancement renvoie 400 INVALID_DOCUMENT_ORDER. Supprimer le dernier document renvoie 400 MIN_DOCUMENTS_REQUIRED.
  • Le téléchargement renvoie 404 DOCUMENT_ORIGINAL_NOT_AVAILABLE lorsque le fichier téléversé n’est plus conservé, et 404 DOCUMENT_SIGNED_NOT_AVAILABLE avant que le certificat soit lié.

Documents dans les réponses

Pour les entreprises activées, ces réponses contiennent documents, documents_version et documents_layout_version : GET /templates, GET /templates/{id}, POST /templates, PUT /templates/{id}, GET /signing-requests et GET /signing-requests/{id}.
  • Chaque entrée de documents comporte document_id, position, label, original_filename, page_count et document_url_kind. En dehors des réponses de liste, chaque entrée inclut aussi un document_url signé, valable 1 heure. Les demandes de signature incluent également document_only_hash, le SHA-256 du document scellé individuellement une fois le certificat lié.
  • Un modèle ou une demande de signature dont l’ensemble de documents n’a jamais été modifié renvoie son unique document avec document_id: null. Dans les réponses de liste, il apparaît avec documents: [].
  • documents_version augmente à chaque modification de document. documents_layout_version augmente lorsque des documents sont ajoutés, supprimés ou réordonnés.

Écritures de champs sur les modèles et demandes de signature multi-documents

PUT et PATCH sur /templates/{id} et /signing-requests/{id} acceptent documents_layout_version avec les écritures de champs. Envoyez la valeur de votre dernière lecture.
  • Il est obligatoire pour écrire un champ lorsqu’il y a plus d’un document ou que la version de mise en page est supérieure à 1. Une valeur manquante renvoie 409 DOCUMENTS_LAYOUT_VERSION_REQUIRED.
  • Une valeur obsolète renvoie 409 DOCUMENT_SET_VERSION_CONFLICT. Rechargez et réessayez.
  • Une valeur qui n’est pas un entier positif ou nul renvoie 400 VALIDATION_ERROR avec la clé documents_layout_version. Un champ placé sur une page au-delà du nombre de pages de son document renvoie 400 VALIDATION_ERROR avec la clé page.
  • Un document en ligne sur PATCH /signing-requests/{id} pour une demande comportant plus d’un document renvoie 409 MULTI_DOCUMENT_REPLACE_UNSUPPORTED. Utilisez plutôt les routes /documents.

Modèles comportant plusieurs documents

  • POST /templates/{id}/copy copie un modèle comportant plus d’un document sous la forme d’un modèle à un seul document fusionné. Le contenu et les numéros de page absolus de ses champs sont conservés. Les libellés et les positions propres à chaque document ne sont pas repris.

Conflits de create-and-send

POST /signing-requests/create-and-send peut renvoyer 409 avec MULTI_DOCUMENT_READ_ONLY, SEND_IN_PROGRESS, SEND_EFFECTS_EXIST, ALREADY_SENT, DOCUMENT_SET_BUSY, DOCUMENT_SET_INCONSISTENT, DOCUMENT_SET_VERSION_CONFLICT ou DOCUMENT_SET_DISPATCH_STALE. SEND_EFFECTS_EXIST et ALREADY_SENT peuvent aussi contenir signing_request_id. Il est présent lorsque la demande de signature créée par cet appel a été conservée. Récupérez cette demande au lieu de réessayer, car une nouvelle tentative crée une deuxième demande. Sans signing_request_id, aucune demande n’a été conservée.

Codes d’erreur

Nouveaux codes, tous renvoyés sous la forme { error, code } : Le schéma MultiDocumentErrorCode de la référence API liste les 42 codes que peuvent renvoyer les routes multi-documents et les routes qu’elles modifient. Une erreur serveur renvoie 500 avec INTERNAL_ERROR ou INTERNAL selon la route (les routes /documents utilisent INTERNAL) ; aucun des deux ne contient de détail.

Ordre des participants

Les signataires, les approbateurs et les participants de cachet d’organisation partagent un seul espace d’ordre. Les destinataires CC sont enregistrés séparément et n’y occupent jamais de position.
  • PATCH /templates/{id} et PATCH /signing-requests/{id} déplacent un destinataire ou un participant de cachet par insertion avec décalage : tous les participants situés entre l’ancienne et la nouvelle position sont renumérotés. Une position cible supérieure à n renvoie 400 INVALID_SIGNING_ORDER. Un order inférieur à 1 renvoie 400 INVALID_SIGNING_ORDER pour un destinataire et 400 VALIDATION_ERROR pour un participant de cachet.
  • Un nouveau signataire ou approbateur sur ces routes est inséré à order dans [1..n+1], ou ajouté en dernier lorsque order est omis. order: 0 ou une position hors de cet intervalle renvoie 400 INVALID_SIGNING_ORDER.
  • Un nouveau participant de cachet exige order sous la forme d’un entier positif. Un order manquant ou nul renvoie 400 VALIDATION_ERROR ; une position hors de [1..n+1] renvoie 400 INVALID_SIGNING_ORDER.
  • Sur PATCH /templates/{id} et PATCH /signing-requests/{id}, le cachet doit appartenir à votre entreprise : le cachet d’une autre entreprise renvoie 404 NOT_FOUND. Un cachet révoqué, supprimé ou remplacé par une version plus récente renvoie 400 SEAL_UNAVAILABLE. Un cachet limité à un autre espace de travail renvoie 400 SEAL_UNAVAILABLE sur PATCH /signing-requests/{id}. Sur PATCH /templates/{id}, il renvoie 404 NOT_FOUND lorsque vous ajoutez un participant de cachet ou en déplacez un (order défini) ; si vous modifiez uniquement le cachet d’un participant existant (id et seal_id, sans order), l’espace de travail du cachet n’est pas vérifié.
  • Sur une demande de signature envoyée, PATCH /signing-requests/{id} renvoie 409 ALREADY_SENT, sauf l’échange d’un participant de cachet en pause par un appelant protégé. Le retrait d’un participant de cachet avec DELETE /signing-requests/{id}/seal-participants/{participant_id} renvoie 409 SEAL_MUTATION_NOT_ALLOWED.
  • Un changement d’ordre en conflit avec un participant de cachet déjà appliqué renvoie 409 SIGNING_ORDER_LOCKED_APPLIED.
  • POST /signing-requests et POST /signing-requests/create-and-send sans cachet numérotent les destinataires dans l’ordre du tableau lorsque use_signing_order vaut false ou qu’un destinataire omet order. Avec des cachets, chaque destinataire doit avoir un order, et destinataires et cachets doivent former ensemble 1..n : un ordre manquant ou un trou renvoie 400 INVALID_SIGNING_ORDER, et deux participants (destinataires ou cachets) sur le même ordre renvoient 400 SEAL_ORDER_COLLISION.
  • PUT /templates/{id} applique chaque entrée de users et de deleted_users comme une écriture de participant distincte. Si une entrée échoue, les entrées appliquées avant elle sont conservées.
  • POST /templates/{id}/copy conserve l’ordre du modèle source, retire les participants de cachet dont le cachet n’est pas dans la portée de l’espace de travail cible (ainsi que leurs champs) et compacte les participants restants en [1..n].

Nom d’autorité du cachet d’organisation

Les cachets renvoyés par POST /seals, GET /seals, GET /seals/{id} et PATCH /seals/{id} incluent authority_name, 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. Il vaut null pour les cachets dont la lignée a été créée avant la fixation du nom ; ces cachets certifient au nom actuel de l’entreprise.

Autres changements

  • POST /signing-requests/{id}/resend renvoie 409 SEND_IN_PROGRESS pendant qu’un envoi de cette demande de signature est en cours.
  • Corrigé : pour les entreprises activées pour la signature multi-documents, la création d’une demande de signature (POST /signing-requests) et sa création avec envoi (POST /signing-requests/create-and-send) renvoient désormais chaque participant de cachet d’organisation avec son cachet (identifiant, lignée, version, nom et nom d’affichage) dans seal_participants. Auparavant, cette liste était vide, alors que le cachet lui-même était bien enregistré et appliqué sur le document. Les documents signés, les certificats et les webhooks ne sont pas concernés.
  • Documentation uniquement : la réponse de POST /signing-requests/create-and-send documente désormais seal_participants, qu’elle renvoyait déjà. La réponse de renvoi documente désormais recipients_suppressed, le nombre de destinataires non relancés parce que leur adresse est supprimée.

Inchangé

  • PUT /signing-requests/{id} avec un identifiant de champ qui n’appartient pas à la demande de signature renvoie toujours 400, y compris sur les demandes multi-documents.
  • reminders sur POST /signing-requests/create-and-send fonctionne comme avant, y compris pour les demandes créées avec document_ids.

Notes de migration

  • La modification est additive. Les requêtes qui n’utilisent jamais document_ids, document_index ni les routes /documents se comportent comme avant, et les entreprises non activées ne voient aucune nouvelle clé de réponse.
  • Si vous générez un client à partir de la spécification OpenAPI : document est facultatif sur POST /templates, et le schéma du participant de cachet dans les réponses des demandes de signature s’appelle désormais SealParticipantApi (auparavant SealParticipant).
  • Si vous analysez strictement les codes d’erreur, acceptez les nouveaux codes ci-dessus.
  • Pour une entreprise activée, envoyez documents_layout_version avec les écritures de champs sur les modèles et demandes de signature comportant plus d’un document.

v1.38.0

Date de sortie : 17 septembre 2026 Type de version : Version mineure Spécification OpenAPI : Télécharger la spécification v1.38.0

Prise en charge du catalan

L’ensemble des langues prises en charge passe de 14 à 15 avec l’ajout du catalan (ca), qui rejoint en, es, it, pt, fr, de, el, ru, pl, cs, sv, nl, ro et nb. Le nouveau code est accepté sur toutes les surfaces de l’API porteuses de langue :
  • Paramètres de l’espace de travail : language sur PUT /workspace/{workspace_id}/settings (et renvoyé par le GET correspondant)
  • Paramètres de l’entreprise : language sur les endpoints de paramètres d’entreprise
  • Langue d’e-mail par demande de signature : le champ language sur POST /signing-requests, POST /signing-requests/create-and-send et PATCH / PUT /signing-requests/{id}
  • Conditions du signataire : le paramètre de chemin {language} sur les endpoints de conditions du signataire d’entreprise et d’espace de travail (PUT / DELETE)
  • Modèles d’e-mail par défaut : GET /email-templates/defaults/{language}
  • Déclaration du cachet d’organisation : statement.language lors de la création et de la mise à jour du cachet, renvoyé comme statement_language sur le cachet
Définir le catalan localise l’expérience complète du signataire : les e-mails destinés au signataire, l’interface de la cérémonie de signature, la déclaration de consentement enregistrée lors de l’acceptation des conditions et le format des dates. Le certificat de finalisation suit la langue de l’espace de travail : définissez le catalan sur l’espace de travail pour obtenir un certificat en catalan. Les erreurs de validation pour les codes non pris en charge listent désormais les 15 langues.

Notes de migration

  • La modification de l’API est additive. Les 14 codes de langue existants sont acceptés et renvoyés exactement comme avant, et les requêtes qui n’envoient jamais ca sont validées comme avant.
  • Sauf si l’URL de signature comporte un code lang pris en charge, la page de signature sélectionne la première langue de la liste de préférences du navigateur du signataire prise en charge par Firma.dev. Un signataire dont le navigateur place ca ou une variante régionale ca- avant toute autre langue prise en charge voit désormais la page de signature en catalan. Avant la v1.38.0, le signataire voyait la langue suivante prise en charge dans la liste ou l’anglais. Les liens de signature envoyés par e-mail ne contiennent pas de paramètre lang, ce comportement s’applique donc aussi aux signataires existants. Un code lang pris en charge que vous ajoutez à une URL de signature intégrée définit toujours la langue ; toute autre valeur est ignorée.
  • La déclaration de consentement est résolue dans cet ordre : les conditions de l’espace de travail dans la langue du signataire, les conditions de l’entreprise dans la langue du signataire, les conditions de l’espace de travail dans la langue configurée de l’espace de travail, les conditions de l’entreprise dans la langue configurée de l’entreprise, puis les conditions par défaut de Firma.dev dans la langue du signataire. S’il n’existe aucune condition en catalan ni dans la langue configurée applicable, un signataire qui donne la priorité au catalan accepte désormais la déclaration par défaut en catalan de Firma.dev au lieu de conditions personnalisées dans une autre langue du navigateur, par exemple l’espagnol. Les conditions dans la langue configurée de l’espace de travail ou de l’entreprise continuent de s’appliquer lorsqu’elles sont disponibles.
  • Ajoutez des conditions du signataire en catalan au niveau de l’entreprise ou de l’espace de travail afin de conserver des conditions personnalisées pour ces signataires. Utilisez PUT /company/signer-terms/ca, PUT /workspace/{workspace_id}/signer-terms/ca ou les paramètres des conditions dans le tableau de bord.

v1.37.1

Date de sortie : 15 septembre 2026 Type de version : Version corrective Spécification OpenAPI : Télécharger la spécification v1.37.0 (inchangée dans cette version)

Destinataires CC

Les endpoints de mise à jour enregistrent désormais les destinataires avec "designation": "CC", et les endpoints de lecture les renvoient. Avant cette version, ils ne faisaient ni l’un ni l’autre.

Ajouter et mettre à jour des destinataires CC

  • PUT /templates/{id} (users[]) et PATCH /templates/{id} (user) enregistrent les destinataires CC. Auparavant, ils renvoyaient 400 et 500.
  • PUT /signing-requests/{id} (recipients[]) et PATCH /signing-requests/{id} (recipient) enregistrent les destinataires CC. Auparavant, PUT renvoyait 200 et comptait le CC dans summary.recipients_created sans l’enregistrer, et PATCH renvoyait 500.
  • Sur PUT /signing-requests/{id}, un destinataire qui ne peut pas être enregistré apparaît désormais dans details.recipients de la réponse 400 au lieu d’être compté dans summary.recipients_created.
  • Les destinataires CC existants peuvent être mis à jour par id et supprimés via deleted_users / deleted_recipients, comme les signataires et les approbateurs.
  • first_name et email sont obligatoires pour un nouveau destinataire CC.
  • designation est comparé sans tenir compte de la casse ("CC", "cc").

Destinataires CC dans les réponses

Les destinataires CC sont renvoyés avec "designation": "CC", après les signataires et les approbateurs, par :
  • GET /signing-requests/{id}/users
  • GET /templates/{id}/users
  • GET /templates/{id} et GET /templates (recipients)
  • le tableau recipients des réponses de POST /signing-requests, POST /signing-requests/create-and-send et PUT /signing-requests/{id}
Les entrées CC ont les mêmes clés que les autres entrées de cet endpoint. Elles ne reçoivent jamais de lien de signature, et les clés qui ne concernent que la signature ont des valeurs neutres (par exemple required_fields: [] et ready_to_send: true).

Création à partir d’un modèle

  • POST /signing-requests et POST /signing-requests/create-and-send avec template_id copient désormais les destinataires CC du modèle vers la nouvelle demande de signature. Un CC du modèle est ignoré lorsque la demande a déjà un CC avec la même adresse e-mail (sans tenir compte de la casse).
  • Un destinataire du corps de la requête avec "designation": "CC" est toujours ajouté comme destinataire CC. Il n’est jamais associé à un utilisateur du modèle par template_user_id ou order.

Validation

  • Faire passer un destinataire existant de CC à Signer ou Approver, ou l’inverse, renvoie 400. PATCH /templates/{id} et PATCH /signing-requests/{id} renvoient le message Cannot change designation between CC and Signer/Approver; delete the recipient and create it again, PUT /signing-requests/{id} l’indique dans details.recipients et PUT /templates/{id} renvoie le message générique Validation errors occurred. Supprimez le destinataire et recréez-le avec la nouvelle désignation.
  • Un champ ne peut pas être attribué à un destinataire CC. Sur PUT /signing-requests/{id}, y compris pour un CC créé dans la même requête via _temp_id, l’erreur du champ indique Cannot assign fields to CC recipient. ; les autres chemins de champs rejettent l’id d’un CC comme destinataire invalide.
  • La mise à jour ou la suppression d’un destinataire par id ne trouve désormais que les destinataires non supprimés. Un destinataire déjà supprimé est traité comme introuvable au lieu d’être modifié.

Notes de migration

  • Aucun nouvel endpoint, champ ou valeur d’enum : la spécification v1.37.0 reste valable.
  • Les listes de destinataires peuvent désormais contenir des entrées CC. Si votre code traite chaque entrée comme un signataire, vérifiez designation.
  • Les demandes de signature créées à partir d’un modèle qui a des destinataires CC incluent désormais ces destinataires CC, qui reçoivent le document finalisé. Retirez les destinataires CC du modèle si vous ne souhaitez pas ce comportement.
  • Si vous comptiez sur une réponse 200 de PUT /signing-requests/{id} lorsqu’un destinataire n’était pas enregistré, gérez la réponse 400.

v1.37.0

Date de sortie : 14 septembre 2026 Type de version : Version mineure Spécification OpenAPI : Télécharger la spécification v1.37.0

Cachets d’organisation

Cachets électroniques appliqués automatiquement au nom d’une entreprise, en tant que participants dans l’ordre de signature. La configuration, les règles de portée et le rendu sur le certificat sont décrits dans le guide des Cachets d’Organisation.

Nouveaux endpoints

Participants de cachet

Les demandes de signature et les modèles acceptent un tableau seal_participants[] aux côtés de recipients[] / users[] sur POST /signing-requests, POST /signing-requests/create-and-send, PATCH /signing-requests/{id}, POST /templates et PATCH /templates/{id}. Chaque entrée comprend temp_id (identifiant client servant à affecter les champs), seal_id et order. Destinataires et cachets partagent un espace d’ordre contigu unique ; l’ordre 1 s’applique à l’envoi. Les champs appartenant à un cachet portent seal_participant_temp_id au lieu d’un destinataire. Les champs de cachet sont générés par le serveur (read_only: 1, sans destinataire) et les valeurs fournies par le client sur ces champs sont ignorées. Les réponses des demandes de signature incluent désormais seal_participants[].

Échange de cachet

PATCH /signing-requests/{id} accepte seal_participant: { "id": "<participant-id>", "swap_to_seal_id": "<seal-uuid>" } pour déplacer un participant en pause d’une demande envoyée vers un autre cachet de la portée. Clé API protégée requise.

Événements webhook

Codes d’erreur

SEALS_DISABLED, SEAL_NOT_FOUND, SEAL_SCOPE_FORBIDDEN, SEAL_IMAGE_INVALID, SEAL_ALREADY_REVOKED, SEAL_ERASE_NOT_ELIGIBLE, SEAL_MUTATION_NOT_ALLOWED, SEAL_ORDER_COLLISION, SEAL_PAUSED, SEAL_UNAVAILABLE et SEAL_CREATION_DISABLED_EDGE (réservé à l’hôte edge de repli ; l’hôte principal de l’API effectue la création des cachets).

Notes de migration

  • Purement additif. recipients[], users[] et tous les endpoints existants sont inchangés.
  • Aucun changement incompatible.

v1.36.0

Date de sortie : 2026-08-31 Type de version : Version mineure Spécification OpenAPI : Télécharger la spécification v1.36.0

Anchor tags

  • add_white_background dans les définitions d’anchor tags : peint un fond blanc derrière le champ ancré.

Réponses d’erreur

  • Les objets d’erreur portent un code lisible par machine.
  • Les échecs de validation renvoient aussi errors[] avec les erreurs par champ.

Create and send

  • Les réponses de POST /signing-requests/create-and-send incluent warnings[] avec des avertissements non bloquants.

Notes de migration

  • Purement additif. Aucun changement incompatible.

v1.35.0

Date de publication : 13 aout 2026 Type de version : Version Mineure Specification OpenAPI : Telecharger la spec v1.35.0

Copie de modele entre espaces de travail

Nouveau endpoint POST /templates/{id}/copy qui copie un modele vers un autre espace de travail au sein de la meme entreprise. Toutes les donnees associees sont copiees avec un remappage correct des IDs :
  • Parametres du modele (expiration, ordre de signature, e-mails, etc.)
  • Destinataires (signataires, approbateurs) avec designations preservees
  • Champs avec references required_conditions et visibility_conditions remappees
  • Destinataires en copie (CC)
  • Definitions de champs personnalises
  • Rappels avec references aux destinataires remappees
  • Document PDF (copie independante)
Corps de la requete :
  • workspace_id (requis, uuid) - espace de travail cible
  • name (optionnel, string, max 255) - nom de la copie (par defaut, nom original avec suffixe ” (copy)”)
Autorisation : necessite une cle API de niveau entreprise (protegee). Les cles d’espace de travail recoivent 403 PROTECTED_KEY_REQUIRED.

v1.33.0

Type de version : Version Mineure Publié le : 2026-08-03 Télécharger la spécification OpenAPI

Cinq nouvelles langues

L’ensemble des langues prises en charge passe de 9 à 14 : le tchèque (cs), le suédois (sv), le néerlandais (nl), le roumain (ro) et le norvégien bokmål (nb) rejoignent en, es, it, pt, fr, de, el, ru, pl. Les nouveaux codes sont acceptés sur toutes les surfaces de l’API porteuses de langue :
  • Paramètres de l’espace de travail — language sur PUT /workspace/{workspace_id}/settings (et renvoyé par le GET correspondant)
  • Paramètres de l’entreprise — language sur les endpoints de paramètres d’entreprise
  • Langue d’e-mail par demande de signature — le champ language sur POST /signing-requests, POST /signing-requests/create-and-send et PATCH / PUT /signing-requests/{id}
  • Conditions du signataire — le paramètre de chemin {language} sur les endpoints de conditions du signataire d’entreprise et d’espace de travail (GET / PUT / DELETE)
  • Modèles d’e-mail par défaut — GET /email-templates/defaults/{language}
Définir l’une des nouvelles langues localise l’expérience complète du signataire : les e-mails destinés au signataire, l’interface de la cérémonie de signature, la déclaration de consentement enregistrée lors de l’acceptation des conditions, le format des dates et le certificat de finalisation (y compris le rendu correct des diacritiques tchèques et roumains). Les erreurs de validation pour les codes non pris en charge listent désormais les 14 langues.

Guide de migration

Aucune action requise. Le changement est purement additif : les 9 codes de langue existants se comportent exactement comme avant, et les espaces de travail ou demandes de signature qui n’ont jamais défini de langue ne sont pas affectés.

v1.32.0

Type de version : Version Mineure Publié le : 2026-07-22 Télécharger la spécification OpenAPI

Taille de police explicite par champ

Les champs textuels (text, textarea, email, name, phone, company, title, number, date, signing_date, approval_date, dropdown, url) acceptent désormais un fontSize optionnel dans format_rules — un entier entre 8 et 48, en pixels. Voir le nouveau schéma TextFormatRules ; DateFormatRules reçoit la même propriété optionnelle, un champ de date peut donc porter à la fois dateFormat et fontSize. La valeur est une taille initiale/maximale, pas une garantie : la vue de signature et le PDF scellé commencent à afficher la valeur du champ à la taille explicite, puis la réduisent automatiquement pour tenir dans le cadre du champ si le contenu déborde. Omettez la propriété pour un dimensionnement automatique (le comportement précédent, inchangé). Les valeurs hors plage sont ramenées à 8-48 ; les valeurs non numériques sont ignorées. Les champs signature, initials, checkbox, radio, file et stamp n’acceptent pas de taille de police. Définissez-la partout où format_rules est accepté — création/mise à jour des champs de modèle et payloads de champs des demandes de signature — par exemple :

Anchor tags : font_size

Les anchor tags reçoivent une propriété optionnelle font_size (entier, 8-48). Lorsqu’un anchor est résolu en champ, la valeur est enregistrée sur le champ créé sous format_rules.fontSize et se comporte exactement comme décrit ci-dessus.

Guide de migration

Aucune action requise. Les propriétés sont optionnelles et additives — les champs sans fontSize s’affichent exactement comme avant, et les modèles et demandes de signature existants ne sont pas affectés.

v1.31.0

Type de version : Version Mineure Publié le : 2026-07-14 Télécharger la spécification OpenAPI

Langue des e-mails optionnelle par demande de signature

Nouveau champ optionnel language sur les endpoints de création et de mise à jour de demandes de signature : POST /signing-requests, POST /signing-requests/create-and-send et PATCH / PUT /signing-requests/{id}. Définissez-le sur l’une des valeurs en, es, it, pt, fr, de, el, ru, pl et tous les e-mails destinés au signataire de cette demande de signature — invitation, rappels, vérification OTP, finalisation et CC, expiration, annulation et refus — ainsi que leur format de date, utilisent cette langue. Le champ accepte null et est additif : language contrôle les e-mails destinés au signataire pour l’ensemble de la demande.

Guide de migration

Aucune action requise. Le champ est optionnel : omettez-le ou envoyez null et le comportement reste inchangé ; les e-mails reviennent à la langue de l’espace de travail, puis de l’entreprise, puis à en. Les demandes de signature existantes ne sont pas affectées.

v1.30.0

Type de version : Version Mineure Publié le : 2026-07-08 Télécharger la spécification OpenAPI

Récupérer les marques du signataire comme images

Quatre nouveaux endpoints en lecture seule renvoient individuellement les marques capturées d’un signataire, séparément du PDF signé :
  • 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
Les endpoints signature, initiales et tampon renvoient la marque sous forme d’URI de données PNG en base64 (data:image/png;base64,...), utilisable directement dans un <img src>. L’endpoint fichier renvoie une URL de téléchargement pré-signée de courte durée (300 secondes). Un signataire adopte une seule signature et une seule série d’initiales, appliquées à tous ses champs de ce type ; ces endpoints ne prennent donc pas de field_id. Les tampons et fichiers sont propres à chaque champ et nécessitent un field_id (obtenez les ID de champ via GET /signing-requests/{id}/fields). Par défaut, un cadre d’ID signataire est superposé aux images renvoyées ; passez include_frame=false pour obtenir la marque brute. Ces endpoints sont limités à 60 requêtes par minute. La validité juridique d’une signature repose sur le PDF scellé et son certificat d’achèvement, pas sur une image récupérée.

Guide de migration

Aucun changement majeur. Ce sont de nouveaux endpoints additifs ; les intégrations existantes ne nécessitent aucune modification.

v1.29.0

Type de version : Version Mineure Publié le : 2026-07-06 Télécharger la spécification OpenAPI

Téléversement de document en deux étapes

Un nouvel endpoint POST /documents permet de téléverser des documents dépassant la limite de taille des requêtes en ligne. Au lieu d’envoyer un document encodé en base64 dans le corps de la requête, vous pouvez désormais :
  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
Ceci est requis pour les documents de plus d’environ 5 Mo. Les documents plus petits peuvent continuer à utiliser le champ document en ligne.

Nouveau champ de requête : document_id

L’endpoint POST /signing-requests/create-and-send accepte désormais document_id comme alternative à document et template_id. Les trois champs s’excluent mutuellement : fournissez-en exactement un.

Augmentation de la limite de taille de document

La taille maximale de document est passée de 20 Mo à 50 Mo lors de l’utilisation du flux de téléversement en deux étapes.

Guide de migration

Aucun changement majeur. Les intégrations existantes utilisant document en ligne ou template_id continuent de fonctionner sans changement. Pour téléverser des documents plus volumineux, adoptez le flux en deux étapes via POST /documents.

v1.28.0

Type de version : Version Mineure Publié le : 2026-07-05 Télécharger la spécification OpenAPI

Exemples de code SDK TypeScript

Chaque endpoint de la référence de l’API inclut désormais un exemple de code prêt à copier-coller pour le client TypeScript officiel @firma-dev/sdk, montrant l’appel typé exact pour cette opération. Consultez le nouveau guide du SDK TypeScript pour installer le client et démarrer.

Changements dans la surface de la référence

Les endpoints suivants ont été retirés de la référence de l’API car ils ne font pas partie de la surface d’API partenaire documentée :

Guide de migration

Aucun changement n’est requis pour les intégrations utilisant les endpoints d’API partenaire documentés ici. Si vous référenciez les endpoints de demande de signature intégrée, utilisez plutôt les guides Intégrables ; l’éditeur intégré continue de s’appuyer sur ces endpoints. Si vous utilisiez les endpoints legacy /documents, migrez vers les endpoints de modèle (POST /templates) et de demande de signature (POST /signing-requests).

v1.27.0

Type de version : Version Corrective Publié le : 2026-06-29 Télécharger la spécification OpenAPI

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

Cette version documente des champs de paramètres que l’API renvoie déjà. Tous les changements sont additifs et rétrocompatibles — aucun comportement de l’API n’a changé, seule la spécification OpenAPI a été mise à jour pour correspondre à ce que les endpoints envoient déjà.

Paramètres de la demande de signature

L’objet settings renvoyé par les endpoints de demande de signature (POST /signing-requests, POST /signing-requests/create-and-send, GET /signing-requests, GET /signing-requests/{id}, PUT /signing-requests/{id}, PATCH /signing-requests/{id}) documente désormais quatre champs supplémentaires :

Paramètres du modèle

L’objet settings renvoyé par les endpoints de modèle (POST /templates, PUT /templates/{id}, PATCH /templates/{id}, GET /templates, GET /templates/{id}, POST /templates/{id}/replace-document) documente désormais le champ show_qr_code. Les paramètres de modèle couvrent les mêmes options que les paramètres de demande de signature, à l’exception des champs d’identité du signataire (identity_editable_fields, notify_identity_change_email), qui s’appliquent uniquement aux demandes de signature.

Réponses d’annulation et de renvoi

Nouveaux schémas

Deux nouveaux schémas séparent les formes de paramètres qui diffèrent selon les endpoints, afin que chaque réponse documente exactement les champs qu’elle renvoie :

Guide de migration

Aucun changement majeur. Ce sont des ajouts documentaires uniquement, décrivant des champs que l’API renvoie déjà. Les intégrations existantes ne sont pas affectées. Si vous analysez des objets settings, vous pouvez désormais vous appuyer sur les champs documentés show_qr_code, allow_presigning_download, identity_editable_fields et notify_identity_change_email, ainsi que sur emails_sent / recipients_failed dans les réponses d’annulation et de renvoi.

v1.26.0

Type de version : Version Mineure Publié le : 2026-06-23 Télécharger la spécification OpenAPI

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

Quatre champs sont désormais disponibles sur GET /workspace/{workspace_id}/settings et PUT /workspace/{workspace_id}/settings :

Structure de la personnalisation des libellés de bouton

Clés de bouton personnalisables : common.finish, signing.approveAndFinish, signing.nextRequiredField, signing.saveAndFinishLater, signing.decline.confirm, signing.decline.title, signing.decline.cancel, signing.finishAnyway, signing.goBack. Les valeurs sont assainies côté serveur (HTML supprimé, 200 caractères maximum). Les valeurs vides ou composées uniquement d’espaces sont ignorées.

v1.25.2

Type de version : Version Corrective Publié le : 2026-06-18 Télécharger la spécification OpenAPI

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

Lors de la création d’une demande de signature à partir d’un modèle, tout champ fourni qui ne correspond à aucun champ de ce modèle est désormais rejeté avec 400 VALIDATION_ERROR au lieu d’être ignoré silencieusement. Auparavant, un tel champ était abandonné et la requête aboutissait tout de même, si bien qu’un identifiant mal orthographié signifiait que le champ n’apparaissait tout simplement jamais sur le document, sans aucune erreur. Un champ fourni correspond à un champ de modèle par template_field_id, variable_name ou variable_defined_name. L’erreur nomme le ou les champs en cause :
S’applique à POST /signing-requests et POST /signing-requests/create-and-send. Migration : assurez-vous que chaque champ que vous envoyez lors d’une création basée sur un modèle référence un champ de modèle existant. Si vous comptiez sur le fait que les champs supplémentaires/non correspondants étaient ignorés, supprimez-les.

Types de champ insensibles à la casse

Les valeurs de type de champ sont désormais normalisées sans distinction de casse. "Initials", "Signature", "TextArea", etc. sont résolus vers leur type canonique (initial, signature, text_area) au lieu d’être rejetés comme invalides. Les valeurs en minuscules restent inchangées.

v1.25.1

Type de version : Version Corrective Publié le : 2026-06-14 Télécharger la spécification OpenAPI

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

POST /signing-requests/create-and-send renvoyait auparavant un 500 générique chaque fois que l’étape d’envoi rejetait une requête, masquant ainsi la raison réelle. Il renvoie désormais le statut exploitable par le client (400, 402 ou 422) avec un code exploitable par machine et le détail pertinent :
  • 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.
Les échecs réels côté serveur renvoient toujours 500. Lorsque l’étape d’envoi échoue, la demande de signature partiellement créée est annulée (rollback), de sorte qu’aucun brouillon orphelin n’est laissé. Guide de migration : aucune action requise pour les clients qui traitent déjà toute réponse non-2xx comme un échec. Si vous traitiez auparavant de façon spécifique le 500 opaque de cet endpoint, basculez vers une logique basée sur le statut HTTP / code : 400 et 422 signifient « corrigez la requête, puis réessayez », 402 signifie « ajoutez des crédits ».

v1.25.0

Type de version : Version Mineure Publié le : 2026-06-14 Télécharger la spécification OpenAPI

Couleurs de marque de l’éditeur

Les paramètres d’apparence incluent désormais cinq couleurs de marque supplémentaires qui thématisent les éditeurs intégrés (les éditeurs de modèle et de demande de signature que vous intégrez sur vos propres pages) :
  • 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.
Elles rejoignent les six champs de couleur existants ; les endpoints de paramètres comportent désormais onze champs color_* :
  • 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.
Les valeurs de l’espace de travail remplacent celles de l’entreprise ; les valeurs non définies reviennent aux valeurs par défaut de Firma, de sorte que les intégrations existantes s’affichent sans changement. Guide de migration : aucune action requise. Les cinq champs sont additifs et peuvent être null. Pour personnaliser les éditeurs intégrés, envoyez l’un des nouveaux champs color_* (hexadécimal #rrggbb valide, ou null pour effacer) à l’endpoint des paramètres d’entreprise ou d’espace de travail.

v1.24.0

Type de version : Version Mineure Publié le : 2026-06-09 Télécharger la spécification OpenAPI

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

Les espaces de travail exposent désormais une clé API en mode test en plus de la clé live existante. Les requêtes authentifiées avec une clé de test ne consomment pas de crédits et produisent des demandes de signature marquées comme test et filigranées.
  • 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.
Tous les changements sont additifs et rétrocompatibles : les consommateurs qui lisent api_key continuent de fonctionner sans changement. Guide de migration : aucune action requise. Pour utiliser le mode test, lisez test_api_key depuis n’importe quelle réponse de création/lecture d’espace de travail et envoyez-la comme clé Authorization pour les requêtes que vous souhaitez exécuter en mode test.

v1.23.0

Type de version : Version Mineure Publié le : 2026-06-04 Télécharger la spécification OpenAPI

Conditions du signataire

De nouveaux endpoints de conditions du signataire vous permettent de gérer des déclarations de consentement personnalisées du signataire aux niveaux entreprise et espace de travail :
  • 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

Les nouveaux endpoints GET /company/settings et PUT /company/settings exposent les paramètres d’entreprise, y compris le contrôle d’acceptation des conditions.

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

Aucun changement majeur. Cette version est additive, et aucune action n’est requise pour les intégrations existantes.

v1.22.1

Type de version : Version Corrective Publié le : 2026-06-02 Télécharger la spécification OpenAPI

Suppression de domaine d’email

DELETE /company/domains/{id} et DELETE /workspace/{workspace_id}/domains/{id} réussissent désormais lorsque la cible est le domaine principal de l’espace de travail ou son seul domaine. Auparavant, ceux-ci renvoyaient 400 "Cannot delete primary domain". Après la suppression, l’email sortant revient à l’expéditeur par défaut de l’entreprise, ou à la valeur par défaut de la plateforme si aucun n’est défini. Pour utiliser à nouveau un domaine d’envoi personnalisé, ajoutez et vérifiez un nouveau domaine, puis définissez-le comme principal.

Guide de migration

Aucun changement majeur. Les réponses 400 "Cannot delete primary domain" et « cannot delete the only domain » sont supprimées des deux endpoints DELETE de domaine ; ils renvoient désormais 200 dans ces cas. Les intégrations qui traitaient spécifiquement ce 400 peuvent supprimer cette gestion.

v1.22.0

Type de version : Version Mineure Publié le : 2026-05-30 Télécharger la spécification OpenAPI

Endpoint de suppression de demande de signature

Nouvel endpoint DELETE /signing-requests/{id} pour supprimer les demandes de signature non envoyées (brouillons). Cet endpoint ne fonctionne que sur les demandes de signature qui n’ont pas encore été envoyées. Pour les demandes de signature envoyées, utilisez plutôt l’endpoint d’annulation existant. Réponse :
  • 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

Aucun changement majeur. La nouvelle méthode DELETE sur /signing-requests/{id} est purement additive. Les intégrations existantes ne sont pas affectées.

v1.21.1

Type de version : Version Corrective Publié le : 2026-05-19 Télécharger la spécification OpenAPI

Gestion du webhook de l’espace de travail

L’endpoint PATCH /workspaces/{id} prend désormais en charge deux nouveaux champs pour gérer les webhooks au niveau de l’espace de travail via l’API :
  • 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.
Auparavant, ces paramètres ne pouvaient être configurés que via l’interface du tableau de bord.

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

Aucun changement majeur. Les configurations de webhook d’espace de travail existantes ne sont pas affectées. Utilisez PATCH /workspaces/{id} avec webhook_enabled: true pour activer les webhooks d’espace de travail via l’API au lieu du tableau de bord.

v1.21.0

Type de version : Version Mineure Publié le : 2026-05-14 Télécharger la spécification OpenAPI

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).
Les emails sont envoyés depuis {email_local_part}@{votre-domaine-personnalisé}. Par exemple, définir email_local_part sur "noreply" envoie les emails depuis noreply@yourdomain.com au lieu de support@yourdomain.com. Validation : alphanumérique en minuscules, points, tirets et underscores. Doit commencer et se terminer par un caractère alphanumérique. 1 à 64 caractères. Motif : ^[a-z0-9]([a-z0-9._-]*[a-z0-9])?$

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

Aucun changement majeur. Les configurations existantes continuent d’envoyer les emails depuis support@{domaine} par défaut. Définissez email_local_part au niveau de l’entreprise ou de l’espace de travail pour personnaliser l’adresse d’expéditeur.

v1.20.0

Type de version : Version Mineure Publié le : 2026-05-12

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).
Le paramètre suit le même modèle de cascade que require_otp_verification : le niveau demande de signature est prioritaire, puis l’espace de travail, puis les paramètres de l’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

Aucun changement majeur. Les demandes de signature et modèles existants continuent de fonctionner comme avant (défilement automatique activé par défaut). Pour désactiver le défilement automatique, définissez disable_guided_navigation: true au niveau souhaité. Télécharger la spécification OpenAPI

v1.19.0

Type de version : Version Mineure Publié le : 2026-05-12

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.
Télécharger la spécification OpenAPI

v1.18.0

Date de sortie : 5 mai 2026

Nouvelles fonctionnalités

Champs modifiables par l’identité

Les demandes de signature prennent désormais en charge la modification de l’identité par champ et par signataire. Une fois configurés, les signataires voient une boîte de dialogue de confirmation avant de signer où ils peuvent examiner et modifier des champs d’identité spécifiés (nom, entreprise, titre, téléphone, adresse). Nouvelle propriété de paramètre : Clés de champ valides : name, company, title, phone, address Surcharge par destinataire via identity_editable_fields sur l’objet destinataire :
  • null - utilise la valeur par défaut de la demande
  • [] - désactivé pour ce signataire
  • ["name", "company"] - champs personnalisés pour ce signataire
Exemple :
Dans cet exemple, John hérite de la valeur par défaut de la demande (nom + entreprise modifiables), tandis que Jane a la modification de l’identité explicitement désactivée. Nouvel événement webhook : signing_request.recipient.identity_changed est désormais disponible comme événement webhook standard. Abonnez-vous-y dans votre configuration de webhook pour recevoir des notifications lorsqu’un signataire modifie son identité pendant la signature.

Champs de données préremplies modifiables

Les champs de données préremplies peuvent désormais être optionnellement modifiables par les signataires. Auparavant, tous les champs avec prefilled_data défini étaient automatiquement verrouillés en lecture seule. Une nouvelle propriété prefilled_editable permet de contrôler ce comportement. Lorsque prefilled_editable est true, la valeur du champ est toujours auto-remplie à partir des données du destinataire, mais le signataire peut la modifier pendant le processus de signature. Disponible sur :
  • 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})
Exemple - créer une demande de signature avec un champ prérempli modifiable :

Validation de la source de valeur du champ

L’API valide désormais que les champs utilisent une seule source de valeur à la fois. Les requêtes combinant read_only_value, prefilled_data et une value explicite sur le même champ renverront désormais une erreur 400 VALIDATION_ERROR. Cette validation s’applique à :
  • 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

Lorsque prefilled_editable est true et qu’une value explicite et prefilled_data sont toutes deux définies sur un champ, la valeur explicite est prioritaire sur les données du destinataire auto-remplies.

Guide de migration

Aucun changement majeur. Les nouvelles fonctionnalités sont optionnelles :
  • 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

Date de sortie : 30 avril 2026 Télécharger la spécification OpenAPI

Nouvelles fonctionnalités

Personnalisation des couleurs pour l’expérience de signature

Six nouveaux champs de couleur pouvant être null vous permettent de personnaliser l’apparence de l’expérience de signature aux niveaux entreprise et espace de travail. Les couleurs suivent une cascade à 3 niveaux : les valeurs par défaut de Firma sont utilisées sauf surcharge au niveau de l’entreprise, et les couleurs de l’entreprise sont utilisées sauf surcharge au niveau de l’espace de travail. Nouveaux champs sur Company (GET /company, PUT /company, PATCH /company) : Nouveaux champs sur Workspace Settings (GET /workspace/{workspace_id}/settings, PUT /workspace/{workspace_id}/settings) : Les six mêmes champs sont disponibles sur les paramètres d’espace de travail. Définissez une valeur pour remplacer celle de l’entreprise par défaut, ou définissez null pour hériter de l’entreprise.

Schéma ColorPalette

Un nouveau schéma ColorPalette représente la palette de couleurs résolue appliquée à l’expérience de signature. Toutes les valeurs sont des chaînes de couleur hexadécimales (#rrggbb).

Guide de migration

De v1.16.0 à v1.17.0 : Il s’agit d’un changement additif non majeur. Les intégrations existantes continuent de fonctionner sans modification.
  • 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

Date de sortie : 27 avril 2026 Télécharger la spécification OpenAPI

Nouvelles fonctionnalités

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

Un nouvel endpoint récupère une URL de téléchargement pour le document d’une demande de signature. Pour les demandes de signature terminées, l’URL pointe vers le PDF final signé. Pour les demandes en cours, annulées, refusées ou expirées, l’URL pointe vers un instantané PDF partiel capturant l’état du document au moment de la dernière action du signataire. Endpoint : GET /signing-requests/{id}/download Champs de réponse : Comportement par statut : Les instantanés partiels sont générés à la demande et mis en cache. La première requête peut renvoyer 503 avec un en-tête Retry-After pendant que le PDF est en cours de génération — réessayez après l’intervalle indiqué. Expiration de l’URL : download_url est une URL pré-signée. Appelez à nouveau l’endpoint après expires_at pour obtenir une URL fraîche.

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

Un nouveau paramètre d’espace de travail show_partial_watermark contrôle si les téléchargements PDF partiels incluent un filigrane diagonal « EN COURS — NON ENCORE EXÉCUTÉ ». Désactivé par défaut. Peut être défini au niveau de l’entreprise (valeur par défaut pour tous les espaces de travail) ou surchargé par espace de travail. Endpoint : PUT /workspace/{workspace_id}/settings

Guide de migration

De v1.15.3 à v1.16.0 : Il s’agit d’un changement additif non majeur. Les intégrations existantes continuent de fonctionner sans modification.
  • 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

Date de sortie : 27 avril 2026 Télécharger la spécification OpenAPI

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

L’endpoint des champs renvoie désormais des champs propres et nommés de façon cohérente, en plus des noms de colonnes de base de données existants : De plus, required, read_only, et date_signing_default renvoient désormais des booléens (true/false) au lieu d’entiers (0/1). Tous les champs dépréciés restent présents dans la réponse pour la rétrocompatibilité et seront supprimés dans une future version majeure.

Guide de migration

Mettez à jour votre analyse de champs pour utiliser les nouveaux noms. Les anciens noms fonctionnent toujours :

v01.15.02

Date de sortie : 23 avril 2026
Télécharger la spécification OpenAPI

Corrections de bugs

Types de champ de create-and-send étendus

Le schéma fields de l’endpoint create-and-send ne comportait pas plusieurs types de champ déjà pris en charge par le backend et disponibles via anchor_tags. Les types suivants ont été ajoutés à l’énumération fields.type :
  • dropdown (avec la propriété dropdown_options)
  • radio_buttons
  • text_area
  • url
  • file
Ces types étaient déjà acceptés par l’API et pleinement fonctionnels. Cette mise à jour aligne la spécification OpenAPI sur le comportement réel du backend. Endpoint concerné :
  • POST /signing-requests/create-and-send — énumération fields[].type

v01.15.01

Date de sortie : 17 avril 2026
Télécharger la spécification OpenAPI

Corrections de bugs

Énumération des langues mise à jour

Ajout des codes de langue manquants ru (russe) et pl (polonais) à tous les champs d’énumération de langue de l’API. Ces langues étaient déjà prises en charge par la plateforme mais absentes de la spécification OpenAPI, empêchant les utilisateurs de l’API de les définir via les endpoints documentés. Endpoints concernés :
  • 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

Date de sortie : 16 avril 2026
Télécharger la spécification OpenAPI

Nouvelles fonctionnalités

Webhooks propres à l’espace de travail

Les webhooks peuvent désormais être limités à des espaces de travail individuels au lieu de s’appliquer à toute l’entreprise. Cela permet à différents espaces de travail d’avoir des configurations et secrets de signature de webhook indépendants.
  • 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

Deux nouveaux endpoints pour gérer les secrets de signature de webhook au niveau de l’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

La réponse GET de l’espace de travail inclut désormais des champs liés aux webhooks :
  • 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

De v01.14.00 à v01.15.00 : Il s’agit d’un changement additif non majeur. Les intégrations existantes continuent de fonctionner sans modification.
  • 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

Date de sortie : 12 avril 2026
Télécharger la spécification OpenAPI

Nouvelles fonctionnalités

Désignations des destinataires

Le champ designation sur les destinataires de demande de signature et de modèle accepte désormais trois valeurs : "Signer", "Approver", et "CC".
  • 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.
Au moins un Signer reste requis par demande de signature.

Types de champ d’approbation

Trois nouveaux types de champ pour les destinataires Approbateur :
  • 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
Ces types de champ ne peuvent être assignés qu’à des destinataires ayant la désignation "Approver".

Destinataires CC

Les destinataires CC sont désormais pris en charge dans tous les endpoints de création et de mise à jour, tant pour les modèles que pour les demandes de signature. Les destinataires CC apparaissent dans la liste des destinataires mais n’ont aucun champ et ne participent pas au flux de signature ou d’approbation.

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

De v01.13.00 à v01.14.00 : Il s’agit d’un changement additif non majeur. Les intégrations existantes continuent de fonctionner sans modification.
  • 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

Date de sortie : 12 avril 2026
Télécharger la spécification OpenAPI

Nouvelles fonctionnalités

Type de champ Tampon

Nouveau type de champ stamp pour placer des tampons image préconfigurés ou des sceaux d’entreprise sur des documents. Les tampons sont des images PNG en lecture seule définies par le créateur du modèle ou de la demande de signature, rendues au moment de la signature sans interaction du signataire, et intégrées dans le PDF final.

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

De v01.12.01 à v01.13.00 : Il s’agit d’un changement additif non majeur. Les intégrations existantes ne sont pas affectées.
  • 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

Date de sortie : 2 avril 2026
Télécharger la spécification OpenAPI

Nouvelles fonctionnalités

variable_defined_name sur les réponses de champ

Tous les endpoints de l’API qui renvoient des champs de modèle ou de demande de signature incluent désormais une propriété variable_defined_name. Il s’agit du field_name lisible par un humain, provenant de la définition de champ personnalisé auquel le champ est lié. Auparavant, les champs liés à des définitions de champ personnalisé exposaient uniquement variable_name, qui contient l’identifiant interne (par ex. custom_template_a1b2c3d4-...). Le nouveau variable_defined_name renvoie le nom que vous avez initialement défini (par ex. artist_name), facilitant le mappage des champs dans votre intégration sans avoir à consulter l’endpoint des champs personnalisés. Endpoints concernés :
  • 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)
Exemple de réponse :
Pour les champs non liés à une définition de champ personnalisé, variable_defined_name vaut null.

variable_defined_name comme entrée pour la correspondance de champ

Lors de la création d’une demande de signature à partir d’un modèle via POST /signing-requests/create-and-send, vous pouvez désormais utiliser variable_defined_name pour cibler des champs à surcharger au lieu du variable_name interne :
variable_name et variable_defined_name sont tous deux acceptés. variable_name est prioritaire lorsque les deux sont fournis.

Aucun changement majeur

Il s’agit d’une version corrective non majeure. Tout le comportement de l’API existant est inchangé.

v01.12.00

Date de sortie : 26 mars 2026
Télécharger la spécification OpenAPI

Nouvelles fonctionnalités

Intégration du serveur MCP

Firma prend désormais en charge le Model Context Protocol (MCP), permettant aux assistants IA comme Claude d’interagir avec l’API Firma en langage naturel. Le serveur MCP expose les opérations principales de l’API Firma sous forme d’outils que les assistants IA peuvent découvrir et appeler directement. URL du serveur : https://mcp.firma.dev/mcp Authentification :
  • 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)
Catégories d’outils disponibles :
  • 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
Transport : Streamable HTTP — compatible avec Claude Code, Claude Desktop, Claude.ai, et tout client MCP prenant en charge le standard. Consultez le guide d’intégration MCP pour les instructions d’installation et exemples d’utilisation.

Aucun changement majeur

Cette version n’ajoute aucun nouvel endpoint API ni changement de schéma. La spécification OpenAPI est inchangée par rapport à la v1.11.0.

v01.11.00

Date de sortie : 19 mars 2026
Télécharger la spécification OpenAPI

Nouvelles fonctionnalités

Type de champ Téléversement de fichier

Un nouveau type de champ file permet aux signataires de téléverser des pièces jointes. Pris en charge sur les demandes de signature et les modèles.
  • 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
Configuration via format_rules :

Balises d’ancrage pour le placement automatique de champ

Un nouveau tableau anchor_tags sur la création de demande de signature permet le placement automatique de champs à l’aide de marqueurs de texte intégrés dans les documents PDF (par ex. {{SIGN_HERE}}). Le texte d’ancrage est retiré du PDF après traitement par défaut.
  • 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
Propriétés clés : Exemple :

Couleur de fond de champ

Tous les types de champ prennent désormais en charge une propriété background_color — une chaîne de couleur hexadécimale (par ex. #FFFDE7, #fff) utile pour mettre en évidence les champs nécessitant une attention particulière. Disponible à la fois sur les champs standard et les définitions de balise d’ancrage.

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

La valeur par défaut du paramètre use_signing_order est passée de false à true. Cela signifie que les nouvelles demandes de signature imposeront par défaut l’ordre de signature. Lorsque true, les signataires reçoivent le document en séquence selon leur champ order. Définissez explicitement use_signing_order: false pour préserver le comportement précédent où tous les signataires reçoivent le document simultanément.

Guide de migration

Si vous vous appuyez sur le comportement précédent où tous les signataires reçoivent les documents simultanément, définissez explicitement use_signing_order: false lors de la création des demandes de signature. Vérifiez tout code d’intégration qui crée des demandes de signature sans spécifier ce champ.

v01.10.00

Date de sortie : 10 mars 2026
Télécharger la spécification OpenAPI

Nouvelles fonctionnalités

Logique de champ conditionnel

Les champs prennent désormais en charge des règles conditionnelles à la fois pour le statut obligatoire et la visibilité. Deux nouvelles propriétés pouvant être null sont disponibles sur les objets de champ :
  • 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.
Les conditions utilisent une structure de groupe imbriquée avec des opérateurs logiques : Opérateurs pris en charge : is_filled, is_empty, equals, not_equals, contains, not_contains, greater_than, less_than, greater_than_or_equal, less_than_or_equal Exemple — Rendre un champ obligatoire uniquement lorsqu’un autre champ est rempli :

Prise en charge des documents DOCX

Tous les endpoints de téléversement de document acceptent désormais les fichiers DOCX en plus du PDF. Les fichiers DOCX sont automatiquement convertis en PDF lors du téléversement. Cela s’applique à :
  • 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

Un nouvel endpoint récupère la piste d’audit complète d’une demande de signature, combinant les actions administrateur (créée, modifiée, envoyée, annulée) et les actions du signataire (consultée, signée, refusée, téléchargée). Les événements sont triés chronologiquement. Endpoint : GET /signing-requests/{id}/audit Champs de réponse :

Contrôle du cadre de signature

Un nouveau paramètre show_signature_frame contrôle si un cadre visuel avec l’ID de signature est rendu autour des signatures dans les PDF terminés. Disponible aux niveaux entreprise, espace de travail et demande de signature. Valeurs :
  • 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

Lors de la suppression de destinataires dont les champs sont référencés par des conditions dans d’autres champs, un nouveau paramètre booléen force_remove_conditions contrôle le comportement :
  • 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
Ceci s’applique aux opérations de suppression d’utilisateur, tant pour les modèles que pour les demandes de signature.

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

Aucun changement majeur. Toutes les nouvelles fonctionnalités sont additives :
  • 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

Date de sortie : 5 mars 2026
Télécharger la spécification OpenAPI

Nouvelles fonctionnalités

Vérification par email OTP

Un nouveau paramètre require_otp_verification vous permet d’exiger que les signataires vérifient leur adresse email avec un code à usage unique avant d’accéder aux documents de signature. Cela ajoute une couche supplémentaire de vérification d’identité. Où c’est disponible : Valeurs :
  • 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)
Exemple — Activer l’OTP au niveau de l’espace de travail :
Exemple — Remplacer pour une demande de signature spécifique :

Remplacement du document de modèle

Un nouvel endpoint permet de remplacer le document PDF d’un modèle tout en préservant tous les placements de champ. Ceci est utile lorsque vous devez mettre à jour un document (par ex. corriger une faute de frappe) sans recréer toutes les configurations de champ. Endpoint : POST /templates/{id}/replace-document Exigences :
  • 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
Exemple :
Cas d’erreur :

Changements de schéma

SigningRequestSettings

WorkspaceSettings

Nouveaux endpoints

Guide de migration

Aucun changement majeur. Le champ require_otp_verification a pour valeur par défaut null (hériter), le comportement existant est donc inchangé. L’endpoint de remplacement de document est purement additif.

v01.08.00

Date de sortie : 3 mars 2026
Télécharger la spécification OpenAPI

Nouvelles fonctionnalités

API des modèles d’email

Un nouveau groupe d’endpoints Modèles d’email vous permet de personnaliser les emails de notification envoyés pendant le processus de signature. Les modèles peuvent être configurés à la fois aux niveaux entreprise et espace de travail, les modèles au niveau de l’espace de travail remplaçant les valeurs par défaut au niveau de l’entreprise. Types d’email pris en charge : Nouveaux endpoints : Hiérarchie des modèles : Modèles d’espace de travail → Modèles d’entreprise → Valeurs par défaut intégrées. Les modèles prennent en charge des corps HTML avec des variables comme {{signing_link}}, {{signer_name}}, etc. Un avertissement est renvoyé si le corps ne contient pas {{signing_link}}. Exemple :

Prise en charge linguistique

Nouveau champ language ajouté aux schémas Company et WorkspaceSettings pour prendre en charge les modèles d’email multilingues.

Changements de schéma

Corrections d’horodatage

Les noms de champ d’horodatage ont été corrigés dans la spécification pour correspondre aux réponses réelles de l’API :
Ce sont des corrections de spécification uniquement — les réponses de l’API n’ont pas changé. Si votre intégration gère déjà les champs de réponse réels de l’API, aucun changement de code n’est nécessaire.

Schéma Company

Schéma Template (étendu)

Le schéma Template inclut désormais les destinataires et champs en ligne lors de la récupération d’un modèle unique (GET /templates/{id}), réduisant le besoin d’appels API séparés.

Formes de réponse de demande de signature

Le schéma monolithique SigningRequest a été divisé en formes de réponse spécifiques à chaque endpoint : Les réponses de liste et de création incluent désormais des tableaux recipients et fields en ligne, et utilisent des champs d’horodatage standardisés (created_date, sent_date, finished_date, etc.).

SigningRequestSettings

use_signing_order (booléen, par défaut false) est désormais inclus dans l’objet settings. Auparavant, ceci n’était disponible que comme champ entier déprécié au niveau supérieur.

Schéma Reminder

Schéma Webhook

SendSigningRequestResponse (corrigé)

La spécification reflète désormais fidèlement la forme de réponse réelle :

WorkspaceSettings


v01.07.00

Date de sortie : 25 février 2026
Télécharger la spécification OpenAPI

Nouvelles fonctionnalités

Signatures manuscrites uniquement

Un nouveau paramètre hand_drawn_only vous permet d’exiger que les signataires dessinent leur signature à la main plutôt que d’utiliser des options saisies ou basées sur une police. Ajouté au schéma SigningRequestSettings : Ce paramètre est disponible partout où les paramètres de demande de signature sont configurés :
  • 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
Exemple :

Changements de schéma

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

Le schéma SigningRequest inclut désormais des champs entiers dépréciés au niveau supérieur, qui reflètent l’objet settings booléen. Ils existent pour la rétrocompatibilité et ne doivent pas être utilisés dans les nouvelles intégrations :
Ces champs dépréciés utilisent des entiers 0/1 au lieu de booléens. Utilisez toujours l’objet settings pour les nouvelles intégrations.

Guide de migration

Aucun changement majeur. Le paramètre hand_drawn_only a pour valeur par défaut false, préservant le comportement existant. Les champs entiers dépréciés au niveau supérieur sont purement additifs.

v01.06.00

Date de sortie : 12 février 2026
Télécharger la spécification OpenAPI

Nouvelles fonctionnalités

Téléchargements PDF scindés

Les demandes de signature terminées prennent désormais en charge le téléchargement du document signé et du certificat de piste d’audit sous forme de fichiers séparés, en plus du téléchargement combiné existant. Nouveaux champs sur le schéma SigningRequest : Notes :
  • 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
Exemple de réponse (partiel) :

Changements de schéma

Normalisation du type de champ

Les énumérations de type de champ acceptent désormais les formes originales et normalisées sur tous les schémas. L’API normalise automatiquement les entrées : Schémas concernés :

Guide de migration

Aucun changement majeur. Les anciens et nouveaux noms de type de champ sont acceptés. Les champs de téléchargement PDF scindé sont purement additifs.

v01.05.00

Date de sortie : 5 février 2026
Télécharger la spécification OpenAPI

Nouvelles fonctionnalités

Avertissements de validation d’email

Les endpoints de demande de signature renvoient désormais des avertissements non bloquants lorsque les adresses email des destinataires ont des formats potentiellement invalides (par ex. TLD inhabituels, points manquants). Ces avertissements aident à identifier des problèmes de livraison potentiels sans faire échouer la requête. Endpoints concernés : Exemple de réponse :
Notes :
  • 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

Aucun changement majeur. Les avertissements de validation d’email sont purement additifs et n’affectent pas les intégrations existantes.

v01.04.00

Date de sortie : 31 janvier 2026
Télécharger la spécification OpenAPI

Nouvelles fonctionnalités

Nouveaux types de champ

Trois nouveaux types de champ ont été ajoutés : Détails du champ URL :
  • 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
Exemple :

Opérations PATCH sur les champs

Les endpoints PATCH de Modèle et de Demande de signature prennent désormais en charge les opérations sur un seul champ : PATCH de modèle (PATCH /templates/{id}) :
  • 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
PATCH de demande de signature (PATCH /signing-requests/{id}) :
  • 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
Exemple - Créer un nouveau champ :
Exemple - Mettre à jour un champ existant :

Correspondance d’utilisateur de modèle pour les destinataires

Lors de la création de demandes de signature à partir de modèles, vous pouvez désormais utiliser template_user_id pour faire correspondre explicitement les destinataires aux utilisateurs de modèle :
  • 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

Mise à jour de :
Vers :

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

Télécharger la spécification OpenAPI

Nouvelles fonctionnalités

API des domaines d’email

Une nouvelle catégorie d’API complète pour configurer des domaines d’email personnalisés pour l’envoi d’emails de demande de signature : Nouveaux endpoints :
  • 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
Nouveaux schémas :
  • 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

Télécharger la spécification OpenAPI

Informations utilisateur enrichies

Améliorations du schéma TemplateUser

Ajout de champs d’informations complètes sur le destinataire :
  • 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

Nouveaux champs pour aider à déterminer la disponibilité du destinataire :
  • 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

Mêmes améliorations que TemplateUser, plus :
  • 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

L’endpoint des utilisateurs de modèle (GET /templates/{id}/users) renvoie désormais :

v01.01.00

Télécharger la spécification OpenAPI

Nouveaux endpoints

Gestion des modèles

Support CRUD complet pour les 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

Nouveaux endpoints pour le cycle de vie des clés API d’espace de travail :
  • 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

L’endpoint PUT pour les modèles prend en charge :
  • 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
Exemple de requête :

v01.00.02

Télécharger la spécification OpenAPI

Nouvelles fonctionnalités

API des champs personnalisés

Ajout de la gestion des définitions de champ personnalisé pour les espaces de travail, modèles et demandes de signature. Nouveau tag :
  • Custom Fields - Gestion des définitions de champ personnalisé
Nouveaux schémas :
WorkspaceCustomField
TemplateCustomField
SigningRequestCustomField

Améliorations de schéma

Schéma TemplateField

Enrichi avec des descriptions plus claires et des propriétés supplémentaires :
  • 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

Télécharger la spécification OpenAPI

Version initiale

La version initiale de l’API Partenaire Firma avec les fonctionnalités principales suivantes :

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

Limites de débit échelonnées selon le type d’opération :
  • 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é

Migration de v1.38.0 vers v1.39.0

  • Aucun changement majeur
  • Les fonctionnalités multi-documents nécessitent une activation pour votre entreprise ; les entreprises non activées ne voient aucun changement
  • Nouveau document_ids sur POST /templates, POST /signing-requests et POST /signing-requests/create-and-send, et nouvelles routes /documents sur les modèles et les demandes de signature
  • Pour les entreprises activées, anchor_tags[].document_index sélectionne le document dans lequel une balise d’ancrage est recherchée sur les demandes multi-documents
  • Envoyez documents_layout_version avec les écritures de champs sur les modèles et demandes de signature comportant plus d’un document

Migration de v1.40.0 vers v1.40.1

  • Aucun changement pour les PDF valides
  • Un PDF dont une page n’a aucun contenu valide renvoie 400 MALFORMED_PDF avec malformed_pages ; rien n’est écrit
  • Un PDF illisible, y compris un PDF chiffré, renvoie 400 VALIDATION_ERROR au lieu de 500

Migration de v1.40.1 vers v1.40.2

  • Aucun changement de l’API
  • La liste events de POST /webhooks et PUT /webhooks/{id} nomme désormais les 26 événements qu’envoie Firma.dev ; régénérez les clients créés à partir de la spécification