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
messageetsub_typene 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 vautnull.messageest limité à 500 points de code etsub_typeà 64. GET /signing-requestsrenvoie des pages et des totaux exacts pour toute liste de statuts qui contient exactement un statut parmiin_progressetexpired(par exemplestatus=expiredoustatus=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é avec400 VALIDATION_ERRORet 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ésormais500au lieu de200. Sur ces listes, lesrecipients[]sont dans l’ordre de signature et lesfields[]arrivent dans un ordre fixe, identique à chaque appel.- Les événements de webhook
signing_request.created,signing_request.updated,signing_request.cancelled,signing_request.deletedettemplate.usedportent désormais le vraiworkspace.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_nameetlast_name, 150 pourtitleet 255 pourcompany. 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
/usersdes demandes de signature et des modèles utilisentformat_rules.prefilledDataet 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éTitlesansprefilledDatan’exige plustitle; unprefilledData: "title"non modifiable l’exige désormais ; un préremplissage de fonction modifiable ne l’exige plus. - Un
PUTqui ajoute un nouveau signataire ou approbateur exigefirst_nameet une adresse e-mail, comme le fait déjàPATCH. AvecPATCHetPUT, 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-requestsrenvoie400 VALIDATION_ERRORparce que plus de 50 000 demandes de signature devraient être vérifiées, affinez la requête aveccreated_after,created_before,name,signer_nameousigner_email. - Sur ces appels de liste, un comptage en échec renvoie
500au lieu de200. - 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
/userspeuvent changer pour des demandes existantes dans un sens comme dans l’autre ; la préparation reste indicative. - Un
PUTqui ajoute un nouveau signataire ou approbateur nécessitefirst_nameet 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}/cancelsur une demande refusée renvoie409 DECLINEDet n’écrit rien. Traitez cette réponse commeALREADY_CANCELLED. Une demande refusée puis annulée continue de renvoyerALREADY_CANCELLED. Une demande expirée peut toujours être annulée. Un409 CONFLICTsignifie 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}/resendsur une demande refusée renvoie409 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.EXPIREDest définitif : créez une nouvelle demande.- Les refus de
POST /signing-requests/{id}/sendcontiennent désormais uncode:400 DECLINEDou400 ALREADY_CANCELLED. Le statut et le message restent inchangés. GET /signing-requests?status=declinedrenvoie les demandes refusées (auparavant, la liste non filtrée). Une demande refusée puis annulée est répertoriée commecancelled. Combinerin_progressouexpiredavec un autre statut renvoie désormais tous les statuts demandés (auparavant, seulement les lignesin_progressouexpired).- 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 /webhooksetPUT /webhooks/{id}les retirent de la liste soumise et signalent chacun dans un tableauwarnings; une liste vide après ce retrait renvoie400 VALIDATION_ERROR. Les webhooks enregistrés ne sont pas modifiés ; unPUTsanseventsles laisse tels quels. signing_request.recipient.signed:all_completevauttrueuniquement lorsque tous les signataires et approbateurs de la demande ont terminé (auparavanttruepour chaque événement lorsque l’ordre de signature était activé). Utilisezsigning_request.completedpour détecter la fin ; un cachet d’organisation peut encore être en attente.
- 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_bouncedlorsque vous effectuez des envois en masse. signing_request.viewedcontient l’objetsigning_requestcomplet (workspace_id,created_at,sent_at,expires_at,document_page_count,test), les champsfirst_name,last_name,orderetdesignationdu destinataire, ainsi que l’objetworkspace.signing_request.completedcontient les destinataires (signataires et approbateurs avecsigned_at) au lieu d’un tableau vide.
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. EXPIREDest définitif : créez une nouvelle demande.- Traitez
409 DECLINEDlors d’une annulation commeALREADY_CANCELLED. POST /webhooksetPUT /webhooks/{id}peuvent renvoyer un tableauwarningsqui nomme les événements retirés qu’ils ont supprimés.all_completevauttrueuniquement lorsque tous les signataires et approbateurs ont terminé ; utilisezsigning_request.completedpour 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.4Corrections 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-secretetPOST /workspaces/{id}/webhooks/rotate-secretautorisent une rotation par heure (la spécification indiquait une rotation par minute) ; un deuxième appel dans l’heure renvoie429avec le codeCOOLDOWN_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êteX-RateLimit-LimitdePOST /webhooks/rotate-secretindique désormais 60 requêtes par minute. - Envoi d’une demande.
POST /signing-requests/{id}/sendsur une demande déjà envoyée renvoie409avec le codeALREADY_SENT(la spécification indiquait400), et renvoie409avec le codeSEND_IN_PROGRESSpendant qu’un autre envoi est en cours. Une demande annulée ou refusée renvoie400. L’exemple de réussite correspond désormais à la réponse :success,message,sentTo,sentAt. Son en-têteX-RateLimit-Limitindique 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éponse409contient sonsigning_request_id. - Liste des demandes de signature. Sur
GET /signing-requests,signer_emaileffectue 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 statutdeleted; le paramètreexclude_deleted=true, désormais documenté, les exclut. - Téléchargements partiels.
GET /signing-requests/{id}/downloadrenvoie un instantané de progression partielle pour toute demande envoyée qui n’est pas terminée. Il n’existe aucun paramètreallow_partial_download. Une demande terminée dont le certificat d’achèvement est encore en cours de génération renvoie409. 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}/sendattendait un400pour une demande déjà envoyée, gérez plutôt409 ALREADY_SENT.
v1.40.3
Date de sortie : 20 octobre 2026 Type de version : Version correctivePreuve 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é, etverify-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}/auditrenvoie des événementsotp_verifiedavecdetails.channel = "email"etdetails.otp_code_id, décrits commeEntered the one-time code sent by email. Les événementsdocument_finishedportentdetails.otp_code_idlorsque 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 INTERNALau lieu deOTP_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
signingUserIdmal formé renvoie400 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
200aveccode: "SIGNING_STATE_CHANGED"etstate. - Un code correct avec une erreur transitoire ne consomme plus de tentative.
- Une erreur de base de données renvoie
- Aucun changement du schéma OpenAPI.
eventreste 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}/auditet la piste d’audit du tableau de bord décrivent une annulation depuis le tableau de bord commeSigning Request Cancellation requestedet une suppression depuis le tableau de bord commeSigning Request Deletion requested. Une nouvelle tentative de certificat ajouteCertificate 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.2Liste des événements de webhook
La listeevents 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.declinedetsigning_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.resentetsigning_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.addedetworkspace.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.1PDF 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 renvoie400 MALFORMED_PDF :
malformed_pagesliste 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-sendetPOST /templates,document_position(indexé à partir de 1, dans l’ordre des documents de la requête) désigne le document, etdocument_idest ajouté lorsque le document provient dedocument_idoudocument_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-sendetPOST /templates, un téléversement désigné pardocument_idoudocument_idsest consommé lorsque cette erreur est renvoyée : téléversez à nouveau le fichier réparé avecPOST /documentspour 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.
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é, renvoie400 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_positionetdocument_id. - Un PDF illisible renvoie désormais
400, et non500. 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.0Boutons 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_declineaffiche le bouton Refuser de signer. Lorsque la valeur estfalse, 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_lateraffiche le bouton Sauvegarder et terminer plus tard. Lorsque la valeur estfalse, seul le bouton est masqué.
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_idsurPOST /signing-requestsetPOST /signing-requests/create-and-send, ouPOST /templates/{id}/duplicate) copie les valeurs du modèle lors de sa création. Sur les deux routes de création, une valeur dans lessettingsde la demande remplace celle du modèle ;nully signifie la valeur de l’espace de travail.POST /templates/{id}/duplicatecopie 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}/copycopie 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,falseounull: danssettingsdes 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 deGET /company/settingsetGET /workspace/{workspace_id}/settings. Les valeurs de l’entreprise sont toujourstrueoufalse. - Toute autre valeur, comme une chaîne ou un nombre, renvoie
400 VALIDATION_ERRORen nommant la clé (par exemplesettings.allow_decline must be a boolean or null) et n’écrit rien.PUT /company/settingsrefuse aussinull.
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) renvoie413 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_declinenishow_save_for_laterse 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_LARGEou téléversez les fichiers avecPOST /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.1Mise à jour, 13 octobre 2026
- Sur
POST /signing-requestsetPOST /signing-requests/create-and-sendavectemplate_id, lorsque le modèle n’a pas de destinataires propres et queseal_participantsest absent ou vautnull, 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 dek+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ésormaisstatementavecaccepted: true,version: 1,language,textexactement égal austatement_textenregistré deGET /seals/{id}etsignatory_name(signatory_titlefacultatif). Cela s’applique aux changements deimage,typed,display_name,signatory_titleoustatement. Sansstatement, la demande renvoie400 SEAL_STATEMENT_REQUIREDet n’écrit rien. Le comportement de création dePOST /sealsreste 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_namerestent 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 webhooksorganization_seal.created,organization_seal.updatedetorganization_seal.deletedincluent désormaisstatement_textetstatement_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 sanstemplate_id.
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 avectemplate_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_participantsest absent ou vautnull, les cachets hérités conservent l’ordre du modèle en premier (1..k) ; les destinataires de la demande suivent (à partir dek+1). - Sur
POST /signing-requests, unrecipient_idnumé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 renvoie400 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 accepteseal_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ésormaisseal_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_attributesur la demande remplace uniquement la propriété imprimée.
Modèles
GET /templates/{id}etPUT /templates/{id}renvoientseal_participants, triés parorder,[]lorsque le modèle n’en a aucun. Chaque entrée a la même forme que les participants de cachet ailleurs.POST /templatesn’accepte passeal_participants,recipientsnifields. Il les ignore et renvoie un tableauwarningsavec une chaîne par clé présente, par exempleseal_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_participantssurGET /signing-requests/{id},GET /signing-requests,POST /signing-requestsetPOST /signing-requests/create-and-sendrenvoie 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_participantssurPOST /signing-requestsetPOST /signing-requests/create-and-sendexigetemp_idetorder.seal_idest 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 renvoie400 SEAL_UNAVAILABLElorsque ni l’un ni l’autre n’existe. La référence indiquaitseal_idcomme obligatoire ettemp_idcomme facultatif. - Le corps
seal_participantdePATCH /signing-requests/{id}etPATCH /templates/{id}est documenté tel que l’API le lit :id,seal_id,orderet, sur les demandes de signature,swap_to_seal_id. La cléparticipant_idque montraient les références précédentes n’était jamais lue ; utilisezid. Ajouter un participant de cachet répond201, et le mettre à jour ou le remplacer répond200, tous deux avec{ "seal_participant": ... }. Ces routes renvoient503 SEALS_DISABLEDlorsque les cachets d’organisation ne sont pas activés et qu’un participant de cachet est ajouté ou que son cachet est changé. SurPATCH /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_idcomprise, sont ignorées. - Un remplacement de cachet sur
PATCH /signing-requests/{id}documente ses réponses :403 PROTECTED_KEY_REQUIREDlorsque la clé API n’est pas celle de l’espace de travail protégé ;404 NOT_FOUNDlorsque le nouveau cachet n’existe pas, appartient à une autre entreprise ou est limité à un autre espace de travail ;409 SEAL_UNAVAILABLElorsque le nouveau cachet est révoqué, supprimé ou n’est pas la version actuelle ;409 SEAL_MUTATION_NOT_ALLOWEDlorsque la demande n’a pas été envoyée ou que le participant n’est pas en pause ;400 SEAL_FIELD_REQUIREDlorsque le participant n’a pas de champ tampon. - Le corps
200deDELETE /signing-requests/{id}/seal-participants/{participant_id}est{ "deleted": true }. - Le tableau
fieldsde la réponse dePOST /signing-requests/create-and-sendliste 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 formeFieldutilisée dans les requêtes (par exemple, le type se trouve dansfield_type). POST /templates/{id}/copydocumente sesseal_participants(comportement inchangé).PUT /templates/{id}documente son tableau de requêteseal_participants(TemplateSealParticipantInput), qui remplace l’ensemble des cachets du modèle.- Le
400dePOST /signing-requests/create-and-sendlisteSEAL_NO_IMAGE_FIELD(un cachet sans champ tampon est refusé à l’envoi). - Les paramètres dont le
nulla une signification (require_otp_verification,require_terms_acceptance,allow_presigning_download,terms_url, lerecipient_idouassigned_to_user_idd’un champ,identity_editable_fields, et les paramètres d’espace de travailshow_signature_frameetshow_partial_watermark) indiquent désormais ce que faitnull.
Notes de migration
- Pour les remplacements de cachets à partir du 13 octobre 2026, lisez
GET /seals/{id}et envoyezstatementsurPATCH /seals/{id}:accepted: true,version: 1,language, lestatement_textexact enregistré commetextetsignatory_name(signatory_titlefacultatif). Gérez400 SEAL_STATEMENT_REQUIREDet acceptezstatement_textetstatement_hashdans les objets de cachet. - Un
POST /signing-requestsouPOST /signing-requests/create-and-sendavectemplate_idet sans cléseal_participantshérite désormais des cachets du modèle. Envoyez"seal_participants": []pour créer sans eux.nullhérite également (y compris un client qui envoienullpour un champ non défini). - Une valeur de
seal_participantsqui n’est ni un tableau ninullrenvoie désormais400 VALIDATION_ERRORsurPOST /signing-requestsetPOST /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 :
droppeddans les réponses de création,warningssurPOST /templates, etseal_participantssurGET /templates/{id},PUT /templates/{id}etPOST /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.
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
/documentsrenvoient404 NOT_FOUND, exactement comme un endpoint inconnu. - Les trois clés de réponse sont absentes.
document_indexsur 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-requestsetPOST /signing-requests/create-and-sendavec plus d’une entrée dansdocument_ids(les identifiants répétés comptent) renvoient409 MULTI_DOCUMENT_READ_ONLYavant toute création.
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_idoudocument_ids(outemplate_idsur les routes des demandes de signature). En envoyer plusieurs renvoie400 CONFLICTING_DOCUMENT_SOURCE. - Un identifiant répété renvoie
400 DUPLICATE_DOCUMENT_ID. Plus de 20 identifiants renvoient400 MAX_DOCUMENTS_EXCEEDED. Un téléversement inconnu ou expiré renvoie400 DOCUMENT_UPLOAD_NOT_FOUND. Un ensemble de plus de 100 Mo renvoie413 DOCUMENT_SET_TOO_LARGE. documentn’est plus indiqué comme obligatoire surPOST /templates, cardocument_idoudocument_idspeuvent le remplacer.
Balises d’ancrage par document
Pour les entreprises activées, les balises d’ancrage acceptent un nouveaudocument_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_indexest facultatif et vaut1par défaut. - Avec plusieurs documents, il est obligatoire. Une valeur manquante renvoie
400 ANCHOR_DOCUMENT_REQUIRED; une valeur hors limites renvoie400 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_MISMATCHou400 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 renvoie400 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 renvoie400 INVALID_DOCUMENT_ORDER. Supprimer le dernier document renvoie400 MIN_DOCUMENTS_REQUIRED. - Le téléchargement renvoie
404 DOCUMENT_ORIGINAL_NOT_AVAILABLElorsque le fichier téléversé n’est plus conservé, et404 DOCUMENT_SIGNED_NOT_AVAILABLEavant que le certificat soit lié.
Documents dans les réponses
Pour les entreprises activées, ces réponses contiennentdocuments, 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
documentscomportedocument_id,position,label,original_filename,page_countetdocument_url_kind. En dehors des réponses de liste, chaque entrée inclut aussi undocument_urlsigné, valable 1 heure. Les demandes de signature incluent égalementdocument_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 avecdocuments: []. documents_versionaugmente à chaque modification de document.documents_layout_versionaugmente 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_ERRORavec la clédocuments_layout_version. Un champ placé sur une page au-delà du nombre de pages de son document renvoie400 VALIDATION_ERRORavec la clépage. - Un
documenten ligne surPATCH /signing-requests/{id}pour une demande comportant plus d’un document renvoie409 MULTI_DOCUMENT_REPLACE_UNSUPPORTED. Utilisez plutôt les routes/documents.
Modèles comportant plusieurs documents
POST /templates/{id}/copycopie 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}etPATCH /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 ànrenvoie400 INVALID_SIGNING_ORDER. Unorderinférieur à 1 renvoie400 INVALID_SIGNING_ORDERpour un destinataire et400 VALIDATION_ERRORpour un participant de cachet.- Un nouveau signataire ou approbateur sur ces routes est inséré à
orderdans[1..n+1], ou ajouté en dernier lorsqueorderest omis.order: 0ou une position hors de cet intervalle renvoie400 INVALID_SIGNING_ORDER. - Un nouveau participant de cachet exige
ordersous la forme d’un entier positif. Unordermanquant ou nul renvoie400 VALIDATION_ERROR; une position hors de[1..n+1]renvoie400 INVALID_SIGNING_ORDER. - Sur
PATCH /templates/{id}etPATCH /signing-requests/{id}, le cachet doit appartenir à votre entreprise : le cachet d’une autre entreprise renvoie404 NOT_FOUND. Un cachet révoqué, supprimé ou remplacé par une version plus récente renvoie400 SEAL_UNAVAILABLE. Un cachet limité à un autre espace de travail renvoie400 SEAL_UNAVAILABLEsurPATCH /signing-requests/{id}. SurPATCH /templates/{id}, il renvoie404 NOT_FOUNDlorsque vous ajoutez un participant de cachet ou en déplacez un (orderdéfini) ; si vous modifiez uniquement le cachet d’un participant existant (idetseal_id, sansorder), l’espace de travail du cachet n’est pas vérifié. - Sur une demande de signature envoyée,
PATCH /signing-requests/{id}renvoie409 ALREADY_SENT, sauf l’échange d’un participant de cachet en pause par un appelant protégé. Le retrait d’un participant de cachet avecDELETE /signing-requests/{id}/seal-participants/{participant_id}renvoie409 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-requestsetPOST /signing-requests/create-and-sendsans cachet numérotent les destinataires dans l’ordre du tableau lorsqueuse_signing_ordervaut false ou qu’un destinataire ometorder. Avec des cachets, chaque destinataire doit avoir unorder, et destinataires et cachets doivent former ensemble1..n: un ordre manquant ou un trou renvoie400 INVALID_SIGNING_ORDER, et deux participants (destinataires ou cachets) sur le même ordre renvoient400 SEAL_ORDER_COLLISION.PUT /templates/{id}applique chaque entrée deuserset dedeleted_userscomme une écriture de participant distincte. Si une entrée échoue, les entrées appliquées avant elle sont conservées.POST /templates/{id}/copyconserve 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 parPOST /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}/resendrenvoie409 SEND_IN_PROGRESSpendant 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) dansseal_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-senddocumente désormaisseal_participants, qu’elle renvoyait déjà. La réponse de renvoi documente désormaisrecipients_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 toujours400, y compris sur les demandes multi-documents.reminderssurPOST /signing-requests/create-and-sendfonctionne comme avant, y compris pour les demandes créées avecdocument_ids.
Notes de migration
- La modification est additive. Les requêtes qui n’utilisent jamais
document_ids,document_indexni les routes/documentsse 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 :
documentest facultatif surPOST /templates, et le schéma du participant de cachet dans les réponses des demandes de signature s’appelle désormaisSealParticipantApi(auparavantSealParticipant). - Si vous analysez strictement les codes d’erreur, acceptez les nouveaux codes ci-dessus.
- Pour une entreprise activée, envoyez
documents_layout_versionavec 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.0Prise 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 :
languagesurPUT /workspace/{workspace_id}/settings(et renvoyé par le GET correspondant) - Paramètres de l’entreprise :
languagesur les endpoints de paramètres d’entreprise - Langue d’e-mail par demande de signature : le champ
languagesurPOST /signing-requests,POST /signing-requests/create-and-sendetPATCH/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.languagelors de la création et de la mise à jour du cachet, renvoyé commestatement_languagesur le cachet
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
casont validées comme avant. - Sauf si l’URL de signature comporte un code
langpris 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 placecaou une variante régionaleca-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ètrelang, ce comportement s’applique donc aussi aux signataires existants. Un codelangpris 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/caou 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[]) etPATCH /templates/{id}(user) enregistrent les destinataires CC. Auparavant, ils renvoyaient400et500.PUT /signing-requests/{id}(recipients[]) etPATCH /signing-requests/{id}(recipient) enregistrent les destinataires CC. Auparavant,PUTrenvoyait200et comptait le CC danssummary.recipients_createdsans l’enregistrer, etPATCHrenvoyait500.- Sur
PUT /signing-requests/{id}, un destinataire qui ne peut pas être enregistré apparaît désormais dansdetails.recipientsde la réponse400au lieu d’être compté danssummary.recipients_created. - Les destinataires CC existants peuvent être mis à jour par
idet supprimés viadeleted_users/deleted_recipients, comme les signataires et les approbateurs. first_nameetemailsont obligatoires pour un nouveau destinataire CC.designationest 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}/usersGET /templates/{id}/usersGET /templates/{id}etGET /templates(recipients)- le tableau
recipientsdes réponses dePOST /signing-requests,POST /signing-requests/create-and-sendetPUT /signing-requests/{id}
required_fields: [] et ready_to_send: true).
Création à partir d’un modèle
POST /signing-requestsetPOST /signing-requests/create-and-sendavectemplate_idcopient 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 partemplate_user_idouorder.
Validation
- Faire passer un destinataire existant de CC à Signer ou Approver, ou l’inverse, renvoie
400.PATCH /templates/{id}etPATCH /signing-requests/{id}renvoient le messageCannot change designation between CC and Signer/Approver; delete the recipient and create it again,PUT /signing-requests/{id}l’indique dansdetails.recipientsetPUT /templates/{id}renvoie le message génériqueValidation 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 indiqueCannot 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
idne 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
200dePUT /signing-requests/{id}lorsqu’un destinataire n’était pas enregistré, gérez la réponse400.
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.0Cachets 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 tableauseal_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.0Anchor tags
add_white_backgrounddans 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
codelisible 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-sendincluentwarnings[]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.0Copie de modele entre espaces de travail
Nouveau endpointPOST /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_conditionsetvisibility_conditionsremappees - Destinataires en copie (CC)
- Definitions de champs personnalises
- Rappels avec references aux destinataires remappees
- Document PDF (copie independante)
workspace_id(requis, uuid) - espace de travail ciblename(optionnel, string, max 255) - nom de la copie (par defaut, nom original avec suffixe ” (copy)”)
403 PROTECTED_KEY_REQUIRED.
v1.33.0
Type de version : Version Mineure Publié le : 2026-08-03 Télécharger la spécification OpenAPICinq 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 —
languagesurPUT /workspace/{workspace_id}/settings(et renvoyé par le GET correspondant) - Paramètres de l’entreprise —
languagesur les endpoints de paramètres d’entreprise - Langue d’e-mail par demande de signature — le champ
languagesurPOST /signing-requests,POST /signing-requests/create-and-sendetPATCH/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}
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 OpenAPITaille 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 sansfontSize 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 OpenAPILangue des e-mails optionnelle par demande de signature
Nouveau champ optionnellanguage 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 envoyeznull 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 OpenAPIRé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 signataireGET /signing-requests/{id}/signers/{signer_id}/initials— les initiales adoptées par le signataireGET /signing-requests/{id}/signers/{signer_id}/stamps/{field_id}— un tampon pour un champ tampon spécifiqueGET /signing-requests/{id}/signers/{signer_id}/files/{field_id}— un fichier téléversé par le signataire dans un champ fichier
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 OpenAPITéléversement de document en deux étapes
Un nouvel endpointPOST /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 :
- Appeler
POST /documentsavec les métadonnées du fichier pour recevoir une URL de téléversement pré-signée - Effectuer un
PUTdes octets bruts du fichier directement vers l’URL de téléversement (prend en charge jusqu’à 50 Mo) - Transmettre le
document_idrenvoyé dans votre requêtePOST /signing-requestsouPOST /signing-requests/create-and-send
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 utilisantdocument 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 OpenAPIExemples 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 OpenAPIChamps 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ésshow_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 OpenAPIParamètres de l’espace de travail : quatre nouveaux champs
Quatre champs sont désormais disponibles surGET /workspace/{workspace_id}/settings et PUT /workspace/{workspace_id}/settings :
Structure de la personnalisation des libellés de bouton
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 OpenAPIValidation 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é avec400 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 :
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 detype 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 OpenAPIRé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 :
400VALIDATION_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 inclutvalidation_errors,field_errorsoudetailsidentifiant ce qu’il faut corriger.402INSUFFICIENT_CREDITS— crédits insuffisants pour envoyer ;current_creditsindique le solde.422RECIPIENT_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.
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 OpenAPICouleurs 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.
color_* :
GET/PUT /company/settingsetGET/PUT /workspace/{workspace_id}/settingsacceptent et renvoient les cinq nouveaux champs. Chacun est une chaîne hexadécimale#rrggbbpouvant être null ;nullsignifie hériter (espace de travail → entreprise → valeur par défaut de Firma).- L’objet
color_paletterésolu renvoyé dans les charges utiles de l’éditeur intégré contient désormais onze clés (les six existantes plusaccent,accent_fg,canvas,muted,muted_fg). Lorsqu’il n’est pas défini,mutedprend par défaut la couleurcardrésolue etmuted_fgest dérivé pour garantir la lisibilité, de sorte que la palette est toujours entièrement peuplée.
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 OpenAPIClé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 /workspacesprovisionne désormais une paire de clés live + test et renvoie à la foisapi_key(live) et le nouveau champtest_api_key.GET /workspaces/{id}etGET /workspacesrenvoient désormais à la foisapi_keyettest_api_key.POST /workspaces/{id}/api-key/regenerateet/api-key/expireacceptent unkey_typeoptionnel ("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.
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 OpenAPIConditions 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
GETlistent les conditions du signataire pour l’entreprise et l’espace de travail - les endpoints
PUTcréent ou mettent à jour les conditions du signataire par langue pour l’entreprise et l’espace de travail - les endpoints
DELETEsuppriment les conditions du signataire pour l’entreprise et l’espace de travail
Paramètres d’entreprise
Les nouveaux endpointsGET /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). Utiliseznullpour 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 OpenAPISuppression 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éponses400 "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 OpenAPIEndpoint de suppression de demande de signature
Nouvel endpointDELETE /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 :
200avecsigning_request_idetdeleted_onen cas de succès409 ALREADY_SENTsi la demande de signature a été envoyée404si introuvable ou déjà supprimée
Nouvel événement webhook
signing_request.deletedse déclenche lorsqu’une demande de signature est supprimée via l’API
Guide de migration
Aucun changement majeur. La nouvelle méthodeDELETE 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 OpenAPIGestion du webhook de l’espace de travail
L’endpointPATCH /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 surtruepour la première fois, un secret de webhook est automatiquement généré.ignore_company_webhooks(booléen) - Sitrue, les webhooks au niveau de l’entreprise ne se déclencheront pas pour les événements de cet espace de travail.
Changements de schéma
- PATCH /workspaces/ corps de requête : ajout de
webhook_enabled(booléen, optionnel) etignore_company_webhooks(booléen, optionnel) - PATCH /workspaces/ réponse : inclut désormais
webhook_enabled,webhook_secret,webhook_secret_rotated_at,webhook_secret_created_at, etignore_company_webhooks
Guide de migration
Aucun changement majeur. Les configurations de webhook d’espace de travail existantes ne sont pas affectées. UtilisezPATCH /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 OpenAPINouveaux 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).
- Paramètres d’entreprise (
{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 depuissupport@{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-12Nouveaux 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).
- Paramètres d’entreprise (
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éfinissezdisable_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-12Nouveaux 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_urlde Company est désormais en lecture seule dans les requêtes PATCH/PUT. Utilisez le nouvel endpointPOST /company/logopour gérer les logos.
Guide de migration
- Si vous définissiez
icon_urldirectement viaPATCH /companyouPATCH /workspaces/{id}, passez plutôt aux nouveaux endpointsPOST .../logo. Le champicon_urln’est plus accepté dans les corps de requête de mise à jour. icon_urldans les réponses GET renvoie désormais une URL publiquement accessible au lieu d’une référence interne.
v1.18.0
Date de sortie : 5 mai 2026Nouvelles 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
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 avecprefilled_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})
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 combinantread_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-requestsPOST /signing-requests/create-and-sendPATCH /templates/{id}(création et mise à jour de champ)PUT /templates/{id}(upsert de champ)
Priorité de valeur
Lorsqueprefilled_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: truedansformat_rulespour les rendre modifiables.
v1.17.0
Date de sortie : 30 avril 2026 Télécharger la spécification OpenAPINouvelles 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émaColorPalette 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
nullpar 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 OpenAPINouvelles 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 travailshow_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érez503avecRetry-Afterjusqu’à ce que le document soit prêt.
v1.15.3
Date de sortie : 27 avril 2026 Télécharger la spécification OpenAPIAlias 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 2026Télécharger la spécification OpenAPI
Corrections de bugs
Types de champ de create-and-send étendus
Le schémafields 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_buttonstext_areaurlfile
POST /signing-requests/create-and-send— énumérationfields[].type
v01.15.01
Date de sortie : 17 avril 2026Télécharger la spécification OpenAPI
Corrections de bugs
Énumération des langues mise à jour
Ajout des codes de langue manquantsru (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— champlanguagePUT /companyetPATCH /company— champlanguageGET /email-templates/defaults— paramètre de requêtelanguage
v01.15.00
Date de sortie : 16 avril 2026Té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 unworkspace_idoptionnel 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_idsur 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 surtrue.
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éswebhook_secret— Le secret de signature de webhook actuelwebhook_secret_created_at— Date de création du secret actuelwebhook_secret_rotated_at— Date de la dernière rotation du secretignore_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 /webhooksetGET /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_idest 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: falseetignore_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 2026Télécharger la spécification OpenAPI
Nouvelles fonctionnalités
Désignations des destinataires
Le champdesignation 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.
Types de champ d’approbation
Trois nouveaux types de champ pour les destinataires Approbateur :approval_signature— Un tampon d’approbation placé par l’approbateurapproval_checkmark— Une case à cocher d’approbationapproval_date— Date auto-remplie lorsque l’approbateur approuve
"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
designationde["Signer"]à["Signer", "Approver", "CC"]sur 7 schémas - Ajout de
approval_signature,approval_checkmark, etapproval_dateaux é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
designationsont optionnelles. Omettre le champdesignationutilise 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 champapproval_*pour leurs champs.
v01.13.00
Date de sortie : 12 avril 2026Télécharger la spécification OpenAPI
Nouvelles fonctionnalités
Type de champ Tampon
Nouveau type de champstamp 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
stampaux é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 avecread_only: true, l’image du tampon étant fournie en tant qu’URL de données PNG dansread_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_valueen tant qu’URL de données PNG.
v01.12.01
Date de sortie : 2 avril 2026Té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}/fieldsPOST /templates/{id}/replace-documentGET /signing-requests(liste)GET /signing-requests/{id}/fieldsGET /documents(legacy)
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 2026Té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)
- Espaces de travail — lister, créer, obtenir, mettre à jour
- Modèles — CRUD complet, duplication, consultation des champs/utilisateurs/rappels
- Demandes de signature — CRUD complet, envoi, annulation, renvoi, pistes d’audit
- Webhooks — CRUD complet, test de livraison
- Entreprise — consultation et mise à jour des informations d’entreprise
Aucun changement majeur
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 2026Télécharger la spécification OpenAPI
Nouvelles fonctionnalités
Type de champ Téléversement de fichier
Un nouveau type de champfile 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
format_rules :
Balises d’ancrage pour le placement automatique de champ
Un nouveau tableauanchor_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
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(avecacceptedFileTypes) en plus deDateFormatRuleset 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 explicitementuse_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 2026Té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 statiquerequired. 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.
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ètreshow_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 signaturefalse— Masquer le cadre de signaturenull— 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éenforce_remove_conditions contrôle le comportement :
false(par défaut) — La requête est rejetée avec une erreur listant les champs dépendantstrue— Supprime automatiquement les références de condition et poursuit la suppression
Changements de schéma
Field
Nouveaux schémas
SigningRequestSettings / WorkspaceSettings / Company
Suppression d’utilisateur de modèle et demande de signature
Nouveaux endpoints
Guide de migration
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_framea pour valeur par défautnull(hériter, ce qui est activé par défaut)force_remove_conditionsa pour valeur par défautfalse(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 2026Télécharger la spécification OpenAPI
Nouvelles fonctionnalités
Vérification par email OTP
Un nouveau paramètrerequire_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 documentfalse— Ne pas exiger la vérification OTPnull— Hériter du niveau parent (espace de travail → entreprise, demande de signature → espace de travail)
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
Changements de schéma
SigningRequestSettings
WorkspaceSettings
Nouveaux endpoints
Guide de migration
Aucun changement majeur. Le champrequire_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 2026Té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 champlanguage 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émaTemplate 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 monolithiqueSigningRequest 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 2026Télécharger la spécification OpenAPI
Nouvelles fonctionnalités
Signatures manuscrites uniquement
Un nouveau paramètrehand_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
Changements de schéma
Champs de paramètres legacy dépréciés
Le schémaSigningRequest 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 :
Guide de migration
Aucun changement majeur. Le paramètrehand_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 2026Té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émaSigningRequest :
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
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 2026Té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 :
- 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
warningsouwarningdans 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 2026Té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_valuepour définir l’URL cible - Utilisez
format_rules.urlDisplayTextpour personnaliser le texte d’affichage
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
fielddans le corps de la requête - Inclure
field.idpour mettre à jour un champ existant, l’omettre pour en créer un nouveau
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
fieldque pour les modèles
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 utilisertemplate_user_id pour faire correspondre explicitement les destinataires aux utilisateurs de modèle :
template_user_idest la méthode privilégiée pour la correspondanceorderreste disponible comme solution de repli
Changements de schéma
Énumération du type de champ
Mise à jour de :Schéma Recipient
- La création de demande de signature utilise désormais une référence au schéma
Recipientpartagé - Ajout de la propriété
template_user_idpour la correspondance explicite d’utilisateur de modèle
v01.03.00
Télécharger la spécification OpenAPINouvelles 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’entreprisePOST /company/domains- Ajouter un nouveau domaine d’emailGET /company/domains/{id}- Obtenir les détails d’un domaineDELETE /company/domains/{id}- Supprimer un domainePOST /company/domains/{id}/verify-ownership- Vérifier la propriété du domaine via un enregistrement TXTPOST /company/domains/{id}/finalize- Finaliser la configuration du domaine avec le fournisseur d’emailPOST /company/domains/{id}/verify-dns- Vérifier les enregistrements SPF, DKIM, DMARCPOST /company/domains/{id}/set-primary- Définir le domaine d’envoi principal
Domain- Configuration de domaine d’email avec statut de vérificationDomainDnsRecord- Détails d’enregistrement DNS pour la vérification de domaine
Suivi du coût en crédits
- Ajout du champ
credit_costau schémaTemplate- Nombre de crédits consommés lors de l’envoi - Ajout du champ
credit_costau schémaSigningRequest- Crédits consommés lors de l’envoi
Statut refusé de la demande de signature
- Ajout de
declinedaux valeurs d’énumérationSigningRequest.status - Ajout du champ
date_declinedau schémaSigningRequest
Améliorations de schéma
Champs de modèle
- Ajout du champ
date_defaultpour 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_numberest 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_idenrichie avec les mêmes améliorations que les champs de modèle
v01.02.00
Télécharger la spécification OpenAPIInformations utilisateur enrichies
Améliorations du schéma TemplateUser
Ajout de champs d’informations complètes sur le destinataire :first_name- Prénom du destinatairelast_name- Nom du destinatairephone_number- Numéro de téléphone de contactstreet_address- Adresse postalecity- Villestate_province- État ou provincepostal_code- Code postalcountry- Paystitle- Titre du postecompany- 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èlemissing_fields- Liste des champs requis actuellement videsrequired_read_only_fields- Champs en lecture seule nécessitant des valeurs prérempliesready_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 signerdecline_reason- Raison fournie par le destinataire pour le refuscustom_fields- Valeurs de champ personnalisé pour le destinataire- propriété
has_valuedansrequired_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 OpenAPINouveaux 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 base64PATCH /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èleGET /templates/{id}/fields- Obtenir tous les champs du modèleGET /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 heuresPOST /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ètresusers- 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 (deleteoureassign)fields- Upsert des champsreminders- Upsert des rappels
v01.00.02
Télécharger la spécification OpenAPINouvelles 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é
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é
typeexplicite avec valeurs d’énumération - Objet
positionavec x, y, width, height read_onlyetread_only_valuepour les champs préremplis
v01.00.01
Télécharger la spécification OpenAPIVersion 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_emailwebsite,icon_url,credits(lecture seule)date_created,date_changed
Workspace
id,name,protected,api_keydate_created,date_changed
Template
id,name,descriptiondocument_url(pré-signée, expire)document_url_expires_atdate_created,date_changed
SigningRequest
id,name,descriptiondocument_url,document_url_expires_atdocument_page_count,status,expiration_hourssettings,template_id- Champs de date :
date_created,date_sent,date_finished,date_cancelled,expires_at - objet
certificateavec 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_fieldspour des données supplémentaires- Support d’ID temporaire pour la création basée sur document
Field
id,type,position,page_number,requiredrecipient_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,enableddate_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_senddisponible 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
declinedajouté à 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
radiorenommé enradio_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_idpour 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/initialettextarea/text_areasont toutes deux acceptées avec normalisation automatique
Migration de v01.06.00 vers v01.07.00
- Aucun changement majeur
- Nouveau paramètre
hand_drawn_onlydisponible dans les paramètres de demande de signature (par défautfalse) - 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’objetsettings
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
languageajouté àCompanyetWorkspaceSettings - Schéma de modèle étendu avec
recipients,fields,settings,page_count,expiration_hoursen ligne use_signing_orderajouté à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_verificationdisponible aux niveaux entreprise, espace de travail et demande de signature - Nouvel endpoint
POST /templates/{id}/replace-documentpour 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_conditionsetvisibility_conditionssur 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}/auditpour récupérer les pistes d’audit - Nouveau paramètre
show_signature_frameaux niveaux entreprise, espace de travail et demande de signature - Nouveau paramètre
force_remove_conditionssur 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_orderest passée defalseàtrue— définissez explicitementuse_signing_order: falsesi vous comptez sur la livraison simultanée - Nouveau type de champ
filepour 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_colordisponible 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_namesur toutes les réponses de champ — renvoie le nom lisible par un humain de la définition de champ personnalisé, en plus duvariable_nameinterne variable_defined_nameaccepté comme entrée pour la correspondance de champ surPOST /signing-requests/create-and-send
Migration de v01.15.03 vers v01.16.00
- Aucun changement majeur
- Nouvel endpoint
GET /signing-requests/{id}/downloadpour récupérer une URL de téléchargement du document signé - Téléchargements partiels disponibles lorsque
allow_partial_downloadest 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
ColorPalettepour 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_navigationdisponible 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_partsur 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_idssurPOST /templates,POST /signing-requestsetPOST /signing-requests/create-and-send, et nouvelles routes/documentssur les modèles et les demandes de signature - Pour les entreprises activées,
anchor_tags[].document_indexsélectionne le document dans lequel une balise d’ancrage est recherchée sur les demandes multi-documents - Envoyez
documents_layout_versionavec 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_PDFavecmalformed_pages; rien n’est écrit - Un PDF illisible, y compris un PDF chiffré, renvoie
400 VALIDATION_ERRORau lieu de500
Migration de v1.40.1 vers v1.40.2
- Aucun changement de l’API
- La liste
eventsdePOST /webhooksetPUT /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