Marque Blanche

Firma propose des fonctionnalités complètes de marque blanche qui vous permettent de créer une expérience de signature électronique entièrement personnalisée. Des logos personnalisés et thèmes de couleurs aux interfaces intégrées, vous pouvez garantir que vos clients interagissent avec votre marque tout au long du processus de signature.

Aperçu

La marque blanche dans Firma comprend plusieurs composants :

Marque personnalisée - Téléversez des logos, définissez des thèmes de couleurs et masquez entièrement la marque Firma
Conditions de signataire personnalisées - Exigez que les signataires acceptent vos propres conditions d’utilisation
Libellés des boutons de signature - Personnalisez le texte des boutons de signature par langue
Domaines d’email personnalisés - Envoyez les emails de demande de signature depuis votre propre domaine
Adresse d’expéditeur d’email personnalisée - Contrôlez l’adresse « from » de tous les emails sortants
Modèles d’email personnalisés - Personnalisez le contenu et la marque des emails de notification de signature
Désactivation des emails Firma - Désactivez les emails automatiques par demande de signature et envoyez les vôtres
Expériences intégrées - Intégrez les éditeurs de signature et de modèles directement dans votre application

Tous les exemples d’API de cette page transmettent votre clé API directement dans l’en-tête Authorization. Le préfixe Bearer est facultatif - Authorization: YOUR_API_KEY et Authorization: Bearer YOUR_API_KEY fonctionnent tous les deux.

Marque personnalisée

Personnalisez les logos, les couleurs et la visibilité de la marque à la fois au niveau de l’entreprise et de l’espace de travail. Les paramètres de l’espace de travail remplacent les paramètres de l’entreprise, vous permettant de créer des expériences de marque distinctes pour chacun de vos clients.

Logo de l’entreprise

Téléversez un logo pour l’ensemble de votre compte Firma. Ce logo apparaît dans les emails de signature et l’expérience de signature.

curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/logo.png"

Exigences :

Format : PNG ou JPEG uniquement
Taille maximale : 2 Mo

Pour supprimer le logo de l’entreprise :

curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/company/logo \
 -H "Authorization: YOUR_API_KEY"

Logo de l’espace de travail

Remplacez le logo de l’entreprise pour un espace de travail spécifique :

curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY" \
 -F "file=@/path/to/workspace-logo.png"

Pour supprimer le logo d’un espace de travail (revient au logo de l’entreprise) :

curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspaces/{workspace_id}/logo \
 -H "Authorization: YOUR_API_KEY"

Thème de couleurs

Personnalisez la palette de couleurs de l’expérience de signature à l’aide de valeurs de couleur hexadécimales. Les couleurs peuvent être définies à la fois au niveau de l’entreprise et de l’espace de travail.

Paramètre de couleur	Description	Valeur par défaut de Firma
`color_primary`	Couleur d’accentuation principale (boutons, liens)	`#c285ff`
`color_primary_fg`	Couleur du texte sur les éléments primaires	`#ffffff`
`color_background`	Arrière-plan de la page	`#1c1c21`
`color_foreground`	Couleur du texte principal	`#ffffff`
`color_card`	Arrière-plan des cartes/panneaux	`#22222a`
`color_border`	Couleur de bordure	`#3b3b3b`
`color_accent`	Couleur d’accentuation secondaire	`#34eeff`
`color_accent_fg`	Couleur du texte sur les éléments d’accentuation	`#000000`
`color_canvas`	Arrière-plan du canevas/visionneuse de document	`#0f1419`
`color_muted`	Zones d’arrière-plan atténuées/subtiles	`#22222a`
`color_muted_fg`	Couleur du texte sur les zones atténuées	`#b8b8b8`

Définir les couleurs au niveau de l’entreprise :

curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#0066cc",
    "color_primary_fg": "#ffffff",
    "color_background": "#f5f5f5",
    "color_foreground": "#1a1a1a",
    "color_card": "#ffffff",
    "color_border": "#e0e0e0"
  }'

Définir les couleurs au niveau de l’espace de travail (remplace les couleurs de l’entreprise pour cet espace de travail) :

curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "color_primary": "#ff6600",
    "color_primary_fg": "#ffffff"
  }'

Les couleurs doivent être des valeurs hexadécimales à 6 chiffres (par exemple, #0066cc). Définissez une couleur sur null pour l’effacer et revenir au niveau suivant dans la hiérarchie.

Masquer la marque Firma

Supprimez toute la marque Firma de l’expérience de signature en activant show_custom_branding_only au niveau de l’entreprise :

curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "show_custom_branding_only": true
  }'

Paramètres d’affichage supplémentaires

Affinez l’expérience de signature avec ces paramètres, disponibles à la fois au niveau de l’entreprise et de l’espace de travail :

Paramètre	Description	Valeur par défaut
`show_signature_frame`	Afficher le cadre/la bordure de dessin de la signature	`true`
`show_partial_watermark`	Afficher un filigrane sur les documents partiellement signés	`false`
`show_qr_code`	Inclure un code QR renvoyant vers la page de signature dans les emails	`true`
`require_otp_verification`	Exiger une vérification par OTP par email avant la signature	`false`
`require_terms_acceptance`	Exiger que les signataires acceptent les conditions avant de signer	`true`
`disable_guided_navigation`	Désactiver la navigation guidée étape par étape entre les champs	`false`
`allow_presigning_download`	Autoriser les signataires à télécharger le document avant de signer	`false`

Au niveau de l’espace de travail, définissez ces valeurs sur null pour hériter du paramètre au niveau de l’entreprise.

Hiérarchie des paramètres

Les paramètres de marque suivent une hiérarchie en cascade :

Paramètre de l’espace de travail (priorité la plus élevée)
Paramètre de l’entreprise
Valeur par défaut de Firma (priorité la plus basse)

Cela vous permet de définir des valeurs par défaut à l’échelle de l’entreprise et de les remplacer par espace de travail. Au niveau de l’espace de travail, définir une valeur sur null signifie « hériter de l’entreprise ». Consultez la référence de l’API des paramètres d’espace de travail pour la liste complète des paramètres configurables.

Conditions de signataire personnalisées

Exigez que les signataires acceptent vos propres conditions d’utilisation ou accord juridique avant de signer. Les conditions sont configurées par langue et suivent la même cascade entreprise/espace de travail que les autres paramètres.

Fonctionnement

Lorsque require_terms_acceptance est activé (par défaut), les signataires voient une case à cocher d’acceptation des conditions avant de pouvoir signer. Vous pouvez personnaliser le texte de la déclaration et éventuellement créer un lien vers un document de conditions complet. require_terms_acceptance suit la même cascade que les autres paramètres de marque : paramètre de l’espace de travail → paramètre de l’entreprise → valeur par défaut de Firma. La valeur par défaut de Firma est true (activé), donc l’acceptation des conditions est ACTIVÉE pour chaque document, sauf si vous la désactivez explicitement au niveau de l’entreprise ou de l’espace de travail. Les conditions sont stockées par langue afin que les signataires voient les conditions dans la langue de leur espace de travail, avec un repli en cascade :

Conditions de l’espace de travail pour la langue du signataire (priorité la plus élevée)
Conditions de l’entreprise pour la langue du signataire
Conditions de l’espace de travail pour la langue configurée de l’espace de travail
Conditions de l’entreprise pour la langue configurée de l’entreprise
Conditions par défaut de Firma (priorité la plus basse)

L’acceptation des conditions est suivie par signataire, par demande de signature - et non par adresse email du signataire. Un signataire qui accepte les conditions sur un document doit les accepter à nouveau sur le document suivant ; il n’existe pas d’état « accepter une fois » valable d’un document à l’autre.

Définir les conditions au niveau de l’entreprise

curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms/en \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "statement_text": "I agree to the <a href=\"https://acme.com/terms\">Terms of Service</a> and acknowledge that my electronic signature is legally binding.",
    "terms_url": "https://acme.com/terms"
  }'

Définir les conditions au niveau de l’espace de travail

curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms/en \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "statement_text": "I agree to the <a href=\"https://acmecorp.com/signing-terms\">Signing Terms</a>.",
    "terms_url": "https://acmecorp.com/signing-terms"
  }'

Champs :

statement_text (obligatoire) : texte HTML affiché à côté de la case à cocher d’acceptation. Les balises HTML de base sont autorisées (<a>, <b>, <i>, <br>).
terms_url (facultatif) : URL vers le document de conditions complet.

Lister les conditions

Récupérez toutes les conditions configurées pour une entreprise ou un espace de travail :

# Conditions de l'entreprise
curl https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms \
 -H "Authorization: YOUR_API_KEY"

# Conditions de l'espace de travail
curl https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms \
 -H "Authorization: YOUR_API_KEY"

Supprimer les conditions

Supprimez les conditions personnalisées pour une langue spécifique afin de revenir au niveau suivant de la cascade :

# Supprimer les conditions de l'entreprise pour l'anglais
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/company/signer-terms/en \
 -H "Authorization: YOUR_API_KEY"

# Supprimer les conditions de l'espace de travail pour l'anglais
curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/signer-terms/en \
 -H "Authorization: YOUR_API_KEY"

Désactiver l’acceptation des conditions

require_terms_acceptance peut être désactivé pour l’ensemble de votre compte ou pour un seul espace de travail. Désactiver pour l’ensemble de votre compte (tous les espaces de travail, sauf si un espace de travail le remplace) :

curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "require_terms_acceptance": false
  }'

Désactiver pour un seul espace de travail (remplace le paramètre de l’entreprise uniquement pour cet espace de travail) :

curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "require_terms_acceptance": false
  }'

Définissez require_terms_acceptance sur null au niveau de l’espace de travail pour supprimer le remplacement et hériter à nouveau du paramètre de l’entreprise.

Si le bouton du tableau de bord d’un espace de travail pour ce paramètre affiche une erreur de permissions, seuls les administrateurs de l’entreprise ou de l’espace de travail peuvent modifier ce paramètre depuis l’interface du tableau de bord. Les membres de l’équipe sans accès administrateur doivent demander à un administrateur de le mettre à jour, ou utiliser directement l’API avec votre clé API, qui n’est pas soumise à la restriction administrateur du tableau de bord.

Langues prises en charge : en, es, it, pt, fr, de, el, ru, pl, cs, sv, nl, ro, nb. Consultez la référence de l’API des conditions de signataire pour la documentation complète des points de terminaison.

Libellés personnalisés des boutons de signature

Personnalisez le texte des boutons de signature par espace de travail et par langue. Cela vous permet d’adapter les libellés des boutons à la terminologie ou à la localisation de votre produit.

Définir les remplacements de libellés de boutons

Les libellés des boutons sont définis sous forme d’objet JSONB dans les paramètres de l’espace de travail, classés par langue puis par clé de bouton :

curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_button_label_overrides": {
      "en": {
        "sign": "Approve and Sign",
        "next": "Continue",
        "finish": "Complete Signing"
      },
      "es": {
        "sign": "Aprobar y Firmar",
        "next": "Continuar",
        "finish": "Completar Firma"
      }
    }
  }'

Effacer les remplacements de libellés de boutons

Définissez sur null pour revenir aux libellés de boutons par défaut de Firma :

curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "signing_button_label_overrides": null
  }'

Validation :

Chaque libellé doit être une chaîne de caractères : les valeurs de plus de 200 caractères sont tronquées automatiquement sans avertissement
Les clés de langue sont des chaînes de caractères (10 caractères maximum, non validées par rapport à la liste des langues prises en charge)
Les balises HTML et les caractères de contrôle sont supprimés automatiquement

Les remplacements de libellés de boutons sont un paramètre au niveau de l’espace de travail uniquement. Il n’existe pas de remplacement au niveau de l’entreprise.

Domaines d’email personnalisés

Par défaut, les emails de demande de signature sont envoyés depuis le domaine de Firma. Avec des domaines d’email personnalisés, les emails semblent provenir directement de votre entreprise ou des entreprises de vos clients.

Domaines d’email au niveau du compte (entreprise)

Configurez un domaine d’email personnalisé pour l’ensemble de votre compte Firma. Tous les espaces de travail utiliseront ce domaine par défaut, sauf remplacement.

Étape 1 : Ajoutez votre domaine

Utilisez l’API pour ajouter un domaine d’email personnalisé :

curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "domain": "acme.com"
  }'

Réponse (201 Created) :

{
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 0,
    "domain_status": 0,
    "is_primary": false,
    "verification_token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "date_created": "2024-01-15T10:30:00Z"
  },
  "verification_instructions": {
    "record_type": "TXT",
    "record_name": "_firma-verification.acme.com",
    "record_value": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "next_step": "Add this TXT record to your DNS, then call POST /company/domains/{id}/verify-ownership"
  }
}

Étape 2 : Ajoutez l’enregistrement TXT de vérification

Ajoutez l’enregistrement TXT de vérification à votre DNS :

Type	Nom	Valeur
TXT	`_firma-verification.acme.com`	`a1b2c3d4-e5f6-7890-abcd-ef1234567890`

La propagation DNS prend généralement quelques minutes mais peut prendre jusqu’à 48 heures.

Étape 3 : Vérifiez la propriété du domaine

Une fois l’enregistrement TXT ajouté, vérifiez la propriété :

curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-ownership \
 -H "Authorization: YOUR_API_KEY"

Réponse :

{
  "message": "Domain ownership verified",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 1,
    "domain_status": 0
  },
  "next_step": "Call POST /company/domains/{id}/finalize to complete domain setup and receive DNS records for email sending"
}

Étape 4 : Finalisez la configuration du domaine

Une fois la propriété vérifiée, finalisez le domaine pour recevoir les enregistrements DNS d’envoi d’email :

curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/finalize \
 -H "Authorization: YOUR_API_KEY"

Réponse :

{
  "message": "Domain finalized. Add the following DNS records to enable email sending.",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 2,
    "domain_status": 0
  },
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "ttl": "Auto", "status": "pending" },
    { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "ttl": "Auto", "status": "pending" },
    { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "ttl": "Auto", "status": "pending" }
  ],
  "next_step": "Add these DNS records, then call POST /company/domains/{id}/verify-dns to complete verification"
}

Étape 5 : Ajoutez les enregistrements DNS

Ajoutez les trois enregistrements DNS à votre domaine :

Type	Nom	Valeur
TXT	`@`	`v=spf1 include:amazonses.com ~all`
CNAME	`resend._domainkey`	`resend._domainkey.amazonses.com`
TXT	`_dmarc`	`v=DMARC1; p=none;`

Étape 6 : Vérifiez les enregistrements DNS

Une fois les enregistrements DNS ajoutés, vérifiez-les :

curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/verify-dns \
 -H "Authorization: YOUR_API_KEY"

Réponse (tous vérifiés) :

{
  "verified": true,
  "message": "Domain is fully verified and ready to send emails",
  "domain": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "domain": "acme.com",
    "verification_status": 2,
    "domain_status": 1,
    "is_primary": true
  },
  "dns_records": [
    { "type": "TXT", "name": "@", "value": "v=spf1 include:amazonses.com ~all", "status": "verified" },
    { "type": "CNAME", "name": "resend._domainkey", "value": "resend._domainkey.amazonses.com", "status": "verified" },
    { "type": "TXT", "name": "_dmarc", "value": "v=DMARC1; p=none;", "status": "verified" }
  ]
}

Étape 7 : Définir comme domaine principal (facultatif)

Si vous avez plusieurs domaines, définissez-en un par défaut :

curl -X POST https://api.firma.dev/functions/v1/signing-request-api/company/domains/{domain_id}/set-primary \
 -H "Authorization: YOUR_API_KEY"

Domaines d’email au niveau de l’espace de travail

Pour les applications SaaS multi-tenant, vous pouvez configurer différents domaines d’email par espace de travail. Les domaines d’espace de travail remplacent le domaine au niveau de l’entreprise. Le flux de travail est identique aux domaines d’entreprise, mais utilise des points de terminaison propres à l’espace de travail :

Action	Point de terminaison
Lister les domaines	`GET /workspace/{workspace_id}/domains`
Ajouter un domaine	`POST /workspace/{workspace_id}/domains`
Obtenir un domaine	`GET /workspace/{workspace_id}/domains/{id}`
Supprimer un domaine	`DELETE /workspace/{workspace_id}/domains/{id}`
Vérifier la propriété	`POST /workspace/{workspace_id}/domains/{id}/verify-ownership`
Finaliser la configuration	`POST /workspace/{workspace_id}/domains/{id}/finalize`
Vérifier le DNS	`POST /workspace/{workspace_id}/domains/{id}/verify-dns`
Définir comme principal	`POST /workspace/{workspace_id}/domains/{id}/set-primary`

Exemple : Ajouter un domaine d’espace de travail

curl -X POST https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/domains \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "domain": "sign.acmecorp.com"
  }'

Consultez la référence de l’API des domaines d’email pour la documentation complète des points de terminaison, ou Domaines personnalisés pour les détails des enregistrements DNS, la résolution des conflits avec Resend, et le dépannage de l’état de vérification.

Adresse d’expéditeur d’email personnalisée

Contrôlez l’adresse « from » de tous les emails sortants en combinant un domaine personnalisé avec une partie locale personnalisée.

Comment les adresses email sont résolues

Lorsque Firma envoie un email, l’adresse de l’expéditeur est construite à partir de trois composants :

{sender_name} <{local_part}@{domain}>

Chaque composant est résolu via une chaîne de repli : Résolution du domaine :

Domaine vérifié de l’espace de travail (le principal étant privilégié)
Domaine vérifié de l’entreprise
updates.firma.dev (par défaut)

Résolution de la partie locale (s’applique uniquement lors de l’utilisation d’un domaine personnalisé) :

Paramètre email_local_part de l’espace de travail
Paramètre email_local_part de l’entreprise
support (par défaut)

Le nom de l’expéditeur est le nom de l’espace de travail (ou le nom de l’entreprise si l’espace de travail n’a pas de nom défini). Par exemple, si votre espace de travail s’appelle « Acme Legal » et que vous définissez email_local_part sur noreply avec un domaine vérifié sign.acmecorp.com, les emails seront envoyés depuis :

Acme Legal <noreply@sign.acmecorp.com>

Définir la partie locale de l’email

Niveau entreprise (valeur par défaut pour tous les espaces de travail) :

curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "email_local_part": "noreply"
  }'

Niveau espace de travail (remplace le paramètre de l’entreprise) :

curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/settings \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "email_local_part": "signing"
  }'

Règles de validation :

1 à 64 caractères, lettres minuscules, chiffres, points, tirets bas et traits d’union
Doit commencer et se terminer par une lettre ou un chiffre
Pas de points consécutifs
Les valeurs réservées (postmaster, abuse, mailer-daemon) ne sont pas autorisées

Définissez sur null au niveau de l’espace de travail pour hériter du paramètre de l’entreprise.

Modèles d’email personnalisés

Personnalisez les emails de notification que Firma envoie en votre nom afin qu’ils correspondent à la voix et au style de votre marque. Vous pouvez définir des modèles à la fois au niveau de l’entreprise et de l’espace de travail, les modèles d’espace de travail remplaçant les valeurs par défaut de l’entreprise.

Types d’email personnalisables

Type d’email	Quand il est envoyé
`signing_invite`	Lorsqu’une demande de signature est envoyée à un destinataire
`next_signer`	Lorsque c’est le tour du signataire suivant dans un ordre de signature
`resend_notification`	Lorsque l’expéditeur renvoie manuellement une invitation de signature
`reminder_default`	Lorsqu’un rappel automatique est envoyé pour une signature en attente
`signing_expired`	Lorsqu’une demande de signature expire
`signing_cancelled`	Lorsqu’une demande de signature est annulée
`signing_declined`	Lorsqu’un signataire refuse (envoyé aux autres signataires)
`signing_declined_admin`	Lorsqu’un signataire refuse (envoyé à l’expéditeur, inclut le motif du refus)
`signing_completed`	Lorsque tous les signataires ont terminé de signer
`signer_identity_changed`	Lorsqu’un signataire change son nom pendant la signature

Variables disponibles

Les modèles prennent en charge des corps HTML avec des variables dynamiques utilisant la syntaxe {{placeholder}}. Variables du signataire :

Variable	Description
`{{signer_first_name}}`	Prénom du signataire
`{{signer_last_name}}`	Nom de famille du signataire
`{{signer_name}}`	Nom complet du signataire
`{{signer_email}}`	Adresse email du signataire
`{{signer_title}}`	Titre professionnel du signataire
`{{signer_company}}`	Nom de l’entreprise du signataire

Variables du document :

Variable	Description
`{{signing_request_name}}`	Nom de la demande de signature
`{{signing_link}}`	URL permettant au signataire de signer
`{{expiration_date}}`	Date d’expiration de la demande de signature
`{{download_link}}`	Lien pour télécharger le document signé
`{{decliner_name}}`	Nom du signataire qui a refusé
`{{decline_reason}}`	Motif fourni lors du refus
`{{signing_qr_code}}`	Image de code QR renvoyant vers la page de signature

Variables d’équipe :

Variable	Description
`{{team_name}}`	Nom de l’espace de travail/équipe
`{{team_email}}`	Email de contact de l’espace de travail
`{{company_name}}`	Nom de l’entreprise
`{{company_logo}}`	Image du logo de l’entreprise

Vous pouvez également récupérer cette liste par programmation :

curl https://api.firma.dev/functions/v1/signing-request-api/email-templates/placeholders \
 -H "Authorization: YOUR_API_KEY"

Afficher les modèles par défaut

Récupérez les modèles par défaut intégrés de Firma pour n’importe quelle langue prise en charge, à utiliser comme point de départ :

curl https://api.firma.dev/functions/v1/signing-request-api/email-templates/defaults/en \
 -H "Authorization: YOUR_API_KEY"

Langues prises en charge : en, es, it, pt, fr, de, el, ru, pl, cs, sv, nl, ro, nb.

Définir un modèle d’email d’espace de travail

curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "subject": "Action required: Please sign {{signing_request_name}}",
    "body": "<p>Hi {{signer_name}},</p><p>Please review and sign {{signing_request_name}}.</p><p><a href=\"{{signing_link}}\">Sign now</a></p><p>- The {{team_name}} Team</p>"
  }'

Validation :

subject : obligatoire, 500 caractères maximum
body : obligatoire, 50 000 caractères maximum

Définir un modèle d’email d’entreprise

curl -X PUT https://api.firma.dev/functions/v1/signing-request-api/company/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "subject": "{{company_name}}: Please sign {{signing_request_name}}",
    "body": "<p>Hi {{signer_name}},</p><p>You have a document to sign.</p><p><a href=\"{{signing_link}}\">Sign now</a></p>"
  }'

Supprimer un modèle personnalisé

Supprimez un modèle personnalisé pour revenir au niveau suivant de la hiérarchie :

curl -X DELETE https://api.firma.dev/functions/v1/signing-request-api/workspace/{workspace_id}/email-templates/signing_invite \
 -H "Authorization: YOUR_API_KEY"

Hiérarchie des modèles

Les modèles d’email suivent une hiérarchie en cascade :

Modèle de l’espace de travail (priorité la plus élevée)
Modèle de l’entreprise
Valeur par défaut intégrée pour la langue de l’espace de travail (priorité la plus basse)

Cela vous permet de définir un modèle personnalisé à l’échelle de l’entreprise et de le remplacer pour des espaces de travail spécifiques si nécessaire. La suppression d’un modèle à un niveau donné entraîne un retour au niveau suivant.

Un avertissement est renvoyé si le corps d’un modèle ne contient pas la variable {{signing_link}}, car les destinataires ont besoin d’un lien pour accéder au flux de signature.

Consultez la référence de l’API des modèles d’email pour la documentation complète des points de terminaison.

Désactivation des emails Firma

Pour un contrôle total sur les communications avec vos clients, vous pouvez désactiver les emails automatiques de Firma par demande de signature. Cela vous permet de :

Envoyer les liens de demande de signature via votre propre système d’emailing
Intégrer vos flux de notification existants
Personnaliser le calendrier des emails et les séquences de relance
Utiliser votre propre infrastructure de distribution d’emails

Paramètres d’email sur les demandes de signature

Chaque demande de signature dispose de paramètres qui contrôlent les emails envoyés :

Paramètre	Description	Valeur par défaut
`send_signing_email`	Envoyer des emails de notification de demande de signature aux signataires	`true`
`send_finish_email`	Envoyer un email d’achèvement lorsque tous les signataires ont terminé	`true`
`send_expiration_email`	Envoyer une notification d’expiration lorsque la demande expire	`true`
`send_cancellation_email`	Envoyer une notification d’annulation lorsque la demande est annulée	`true`

Créer une demande de signature avec les emails désactivés

curl -X POST https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
 -H "Authorization: YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "workspace_id": "workspace_123",
    "template_id": "template_456",
    "settings": {
      "send_signing_email": false,
      "send_finish_email": false,
      "send_expiration_email": false,
      "send_cancellation_email": false
    },
    "recipients": [
      {
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jane@example.com",
        "designation": "Signer",
        "order": 1
      }
    ]
  }'

Obtenir les URL de signature pour une distribution manuelle

Lorsque les emails sont désactivés, récupérez les URL de signature depuis l’API et envoyez-les via vos propres canaux :

// Créer une demande de signature avec les emails désactivés
const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      workspace_id: workspaceId,
      template_id: templateId,
      settings: {
        send_signing_email: false,
        send_finish_email: false
      },
      recipients: [
        { first_name: 'Jane', last_name: 'Smith', email: 'jane@example.com', designation: 'Signer', order: 1 }
      ]
    })
  }
)
const signingRequest = await response.json()

// Obtenir les URL de signature pour chaque destinataire
const usersResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/signing-requests/${signingRequest.id}/users`,
  {
    headers: { 'Authorization': API_KEY }
  }
)
const { results: users } = await usersResponse.json()

// Envoyer les emails via votre propre système
for (const user of users) {
  const signingUrl = `https://app.firma.dev/signing/${user.id}`
  await yourEmailService.send({
    to: user.email,
    subject: 'Please sign your document',
    body: `Click here to sign: ${signingUrl}`
  })
}

Expériences intégrées

La fonctionnalité de marque blanche la plus puissante consiste à intégrer les interfaces de Firma directement dans votre application. Cela supprime toute marque Firma et crée une expérience fluide au sein de votre produit.

Signature intégrable

Intégrez le flux de signature afin que les destinataires signent les documents sans quitter votre application :

<iframe 
  src="https://app.firma.dev/signing/{signing_request_user_id}" 
  style="width:100%;height:900px;border:0;" 
  allow="camera;microphone;clipboard-write"
  title="Sign Document"
></iframe>

Guide de signature intégrable - Détails d’implémentation complets

Éditeur de modèles intégrable

Permettez aux utilisateurs de créer et modifier des modèles au sein de votre application à l’aide de l’authentification JWT. L’éditeur se charge via une balise script et s’intègre dans un élément conteneur via le Shadow DOM, et non via un iframe :

<div id="firma-template-editor"></div>
<script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>
<script>
  const editor = new FirmaTemplateEditor({
    container: document.getElementById('firma-template-editor'),
    jwt: 'YOUR_JWT_TOKEN',
    templateId: 'YOUR_TEMPLATE_ID'
  })
</script>

Guide de l’éditeur de modèles intégrable - Génération de JWT, événements et implémentation complète

Éditeur de demande de signature intégrable

Même modèle : balise script + constructeur, et non un iframe :

<div id="firma-sr-editor"></div>
<script src="https://api.firma.dev/functions/v1/embed-proxy/signing-request-editor.js"></script>
<script>
  const editor = new FirmaSigningRequestEditor({
    container: document.getElementById('firma-sr-editor'),
    jwt: 'YOUR_JWT_TOKEN',
    signingRequestId: 'YOUR_SIGNING_REQUEST_ID'
  })
</script>

Guide de l’éditeur de demande de signature intégrable - guide d’implémentation complet

Configuration complète en marque blanche

Voici un exemple complet de configuration d’un espace de travail entièrement en marque blanche pour un client :

1. Créer l’espace de travail

const workspace = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', {
  method: 'POST',
  headers: {
    'Authorization': API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Acme Corporation'
  })
}).then(r => r.json())

console.log('Created workspace:', workspace.id)

2. Téléverser un logo

const logoForm = new FormData()
logoForm.append('file', logoFile)

await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspace.id}/logo`,
  {
    method: 'POST',
    headers: { 'Authorization': API_KEY },
    body: logoForm
  }
)

3. Configurer la marque

await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/settings`,
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      color_primary: '#0066cc',
      color_primary_fg: '#ffffff',
      color_background: '#f8f9fa',
      color_foreground: '#212529',
      color_card: '#ffffff',
      color_border: '#dee2e6',
      email_local_part: 'noreply'
    })
  }
)

4. Masquer la marque Firma (niveau entreprise)

await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/company/settings',
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      show_custom_branding_only: true
    })
  }
)

5. Configurer un domaine d’email personnalisé (facultatif)

// Ajouter le domaine
const domainResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains`,
  {
    method: 'POST',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ domain: 'sign.acmecorp.com' })
  }
).then(r => r.json())

const domainId = domainResponse.domain.id

// L'utilisateur ajoute l'enregistrement TXT au DNS...
// Vérifier la propriété
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/verify-ownership`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

// Finaliser (renvoie les enregistrements SPF, DKIM, DMARC)
const finalizeResponse = await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/finalize`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
).then(r => r.json())

console.log('Add these DNS records:', finalizeResponse.dns_records)

// L'utilisateur ajoute les enregistrements DNS...
// Vérifier le DNS
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/verify-dns`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

// Définir comme principal
await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/domains/${domainId}/set-primary`,
  { method: 'POST', headers: { 'Authorization': API_KEY } }
)

6. Personnaliser les modèles d’email (facultatif)

await fetch(
  `https://api.firma.dev/functions/v1/signing-request-api/workspace/${workspace.id}/email-templates/signing_invite`,
  {
    method: 'PUT',
    headers: {
      'Authorization': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      subject: '{{company_name}}: Please sign {{signing_request_name}}',
      body: '<p>Hi {{signer_name}},</p><p>You have a document to review and sign.</p><p><a href="{{signing_link}}">Sign now</a></p><p>- The {{team_name}} Team</p>'
    })
  }
)

7. Intégrer les expériences

function AcmeSigningApp({ signingRequestUserId }) {
  return (
    <div className="acme-signing-portal">
      {/* Votre en-tête personnalisé */}
      <header className="acme-header">
        <img src="/acme-logo.png" alt="Acme Corp" />
      </header>
      
      {/* Signature Firma intégrée */}
      <iframe
        src={`https://app.firma.dev/signing/${signingRequestUserId}`}
        style={{ width: '100%', height: '800px', border: 'none' }}
        allow="camera;microphone;clipboard-write"
      />
      
      {/* Votre pied de page personnalisé */}
      <footer className="acme-footer">
        &copy; 2026 Acme Corporation
      </footer>
    </div>
  )
}

Bonnes pratiques

Marque

Utilisez une palette de couleurs cohérente entre les logos, les modèles d’email et les expériences intégrées
Téléversez les logos au format PNG avec un arrière-plan transparent pour de meilleurs résultats
Activez show_custom_branding_only pour supprimer entièrement la marque de Firma
Définissez la marque au niveau de l’entreprise comme base, puis remplacez-la par espace de travail si nécessaire
Testez l’ensemble du flux de signature du point de vue de vos clients

Configuration du domaine d’email

Utilisez un sous-domaine (par exemple, sign.yourcompany.com) plutôt que votre domaine principal
Configurez tous les enregistrements DNS (SPF, DKIM, DMARC) pour une délivrabilité optimale
Surveillez les taux de rebond des emails et ajustez si nécessaire
Testez la distribution des emails avant la mise en production avec les clients

Modèles d’email

Utilisez le point de terminaison des valeurs par défaut pour voir les modèles intégrés de Firma comme point de départ
Incluez toujours {{signing_link}} dans les modèles d’invitation et de rappel
Définissez un modèle au niveau de l’entreprise comme base personnalisée, puis remplacez-le par espace de travail si nécessaire
Utilisez {{company_logo}} dans les modèles pour inclure le logo de l’espace de travail ou de l’entreprise

Sécurité

Générez toujours les jetons JWT sur votre backend
N’exposez jamais les clés API dans le code côté client
La durée d’expiration du jeton est fixée côté serveur : 24 heures pour les jetons de l’éditeur de modèles, 7 jours pour les jetons de demande de signature - non configurable par l’appelant
Validez les origines postMessage lors de la gestion des événements iframe

Dépannage

Échec de la vérification de la propriété du domaine

Causes possibles :

Enregistrements DNS non propagés (attendre jusqu’à 48 heures)
Nom ou valeur d’enregistrement TXT incorrect
Enregistrement TXT ajouté à la mauvaise zone

Solution : Vérifiez que votre configuration DNS correspond aux verification_instructions renvoyées lors de l’ajout du domaine

Les enregistrements DNS ne se vérifient pas

Causes possibles :

Enregistrements pas encore propagés
Valeurs d’enregistrement incorrectes
Enregistrements manquants

Solution : Appelez GET /company/domains/{id} ou verify-dns pour voir quels enregistrements spécifiques sont en attente

L’iframe de signature ne se charge pas

Causes possibles :

ID d’utilisateur de demande de signature invalide
Demande de signature expirée ou annulée
Politique de sécurité du contenu bloquant l’iframe

Solution : Vérifiez le statut de la demande de signature et consultez la console du navigateur pour les erreurs CSP

Jeton JWT expiré

Causes possibles :

Durée de vie du jeton trop courte pour le cas d’usage
Décalage d’horloge entre les serveurs

Solution : Générez des jetons avec une expiration appropriée, envisagez de rafraîchir les jetons de manière proactive

Les couleurs ne s’appliquent pas

Causes possibles :

Format hexadécimal invalide (doit être à 6 chiffres, par exemple #0066cc, pas à 3 chiffres #06c)
Paramètre appliqué au niveau de l’entreprise mais l’espace de travail dispose de son propre remplacement

Solution : Vérifiez d’abord les paramètres de l’espace de travail, puis les paramètres de l’entreprise. Utilisez null au niveau de l’espace de travail pour effacer un remplacement.

Guides associés

Signature intégrable - Intégrer l’expérience de signature dans votre application
Éditeur de modèles intégrable - Permettre aux utilisateurs de modifier des modèles avec authentification JWT
Éditeur de demande de signature intégrable - Configurer les demandes de signature dans votre interface
Création d’espaces de travail - Configurer des environnements isolés pour les clients
Webhooks - Suivre les événements de signature en temps réel

⌘I

​Aperçu

​Marque personnalisée

​Logo de l’entreprise

​Logo de l’espace de travail

​Thème de couleurs

​Masquer la marque Firma

​Paramètres d’affichage supplémentaires

​Hiérarchie des paramètres

​Conditions de signataire personnalisées

​Fonctionnement

​Définir les conditions au niveau de l’entreprise

​Définir les conditions au niveau de l’espace de travail

​Lister les conditions

​Supprimer les conditions

​Désactiver l’acceptation des conditions

​Libellés personnalisés des boutons de signature

​Définir les remplacements de libellés de boutons

​Effacer les remplacements de libellés de boutons

​Domaines d’email personnalisés

​Domaines d’email au niveau du compte (entreprise)

​Étape 1 : Ajoutez votre domaine

​Étape 2 : Ajoutez l’enregistrement TXT de vérification

​Étape 3 : Vérifiez la propriété du domaine

​Étape 4 : Finalisez la configuration du domaine

​Étape 5 : Ajoutez les enregistrements DNS

​Étape 6 : Vérifiez les enregistrements DNS

​Étape 7 : Définir comme domaine principal (facultatif)

​Domaines d’email au niveau de l’espace de travail

​Adresse d’expéditeur d’email personnalisée

​Comment les adresses email sont résolues

​Définir la partie locale de l’email

​Modèles d’email personnalisés

​Types d’email personnalisables

​Variables disponibles

​Afficher les modèles par défaut

​Définir un modèle d’email d’espace de travail

​Définir un modèle d’email d’entreprise

​Supprimer un modèle personnalisé

​Hiérarchie des modèles

​Désactivation des emails Firma

​Paramètres d’email sur les demandes de signature

​Créer une demande de signature avec les emails désactivés

​Obtenir les URL de signature pour une distribution manuelle

​Expériences intégrées

​Signature intégrable

​Éditeur de modèles intégrable

​Éditeur de demande de signature intégrable

​Configuration complète en marque blanche

​1. Créer l’espace de travail

​2. Téléverser un logo

​3. Configurer la marque

​4. Masquer la marque Firma (niveau entreprise)

​5. Configurer un domaine d’email personnalisé (facultatif)

​6. Personnaliser les modèles d’email (facultatif)

​7. Intégrer les expériences

​Bonnes pratiques

​Marque

​Configuration du domaine d’email

​Modèles d’email

​Sécurité

​Dépannage

​Échec de la vérification de la propriété du domaine

​Les enregistrements DNS ne se vérifient pas

​L’iframe de signature ne se charge pas

​Jeton JWT expiré

​Les couleurs ne s’appliquent pas

​Guides associés

Aperçu

Marque personnalisée

Logo de l’entreprise

Logo de l’espace de travail

Thème de couleurs

Masquer la marque Firma

Paramètres d’affichage supplémentaires

Hiérarchie des paramètres

Conditions de signataire personnalisées

Fonctionnement

Définir les conditions au niveau de l’entreprise

Définir les conditions au niveau de l’espace de travail

Lister les conditions

Supprimer les conditions

Désactiver l’acceptation des conditions

Libellés personnalisés des boutons de signature

Définir les remplacements de libellés de boutons

Effacer les remplacements de libellés de boutons

Domaines d’email personnalisés

Domaines d’email au niveau du compte (entreprise)

Étape 1 : Ajoutez votre domaine

Étape 2 : Ajoutez l’enregistrement TXT de vérification

Étape 3 : Vérifiez la propriété du domaine

Étape 4 : Finalisez la configuration du domaine

Étape 5 : Ajoutez les enregistrements DNS

Étape 6 : Vérifiez les enregistrements DNS

Étape 7 : Définir comme domaine principal (facultatif)

Domaines d’email au niveau de l’espace de travail

Adresse d’expéditeur d’email personnalisée

Comment les adresses email sont résolues

Définir la partie locale de l’email

Modèles d’email personnalisés

Types d’email personnalisables

Variables disponibles

Afficher les modèles par défaut

Définir un modèle d’email d’espace de travail

Définir un modèle d’email d’entreprise

Supprimer un modèle personnalisé

Hiérarchie des modèles

Désactivation des emails Firma

Paramètres d’email sur les demandes de signature

Créer une demande de signature avec les emails désactivés

Obtenir les URL de signature pour une distribution manuelle

Expériences intégrées

Signature intégrable

Éditeur de modèles intégrable

Éditeur de demande de signature intégrable

Configuration complète en marque blanche

1. Créer l’espace de travail

2. Téléverser un logo

3. Configurer la marque

4. Masquer la marque Firma (niveau entreprise)

5. Configurer un domaine d’email personnalisé (facultatif)

6. Personnaliser les modèles d’email (facultatif)

7. Intégrer les expériences

Bonnes pratiques

Marque

Configuration du domaine d’email

Modèles d’email

Sécurité

Dépannage

Échec de la vérification de la propriété du domaine

Les enregistrements DNS ne se vérifient pas

L’iframe de signature ne se charge pas

Jeton JWT expiré

Les couleurs ne s’appliquent pas

Guides associés