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 utilisent votre clé API directement dans l’en-tête Authorization. N’utilisez pas le préfixe Bearer.

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	`#c285ff`
`color_accent_fg`	Couleur du texte sur les éléments d’accentuation	`#ffffff`
`color_canvas`	Arrière-plan du canevas/visionneuse de document	`#1c1c21`
`color_muted`	Zones d’arrière-plan atténuées/subtiles	`#22222a`
`color_muted_fg`	Couleur du texte sur les zones atténuées	`#a1a1aa`

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	`false`
`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. 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 par défaut de Firma (priorité la plus basse)

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

Pour désactiver entièrement l’exigence d’acceptation des conditions :

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
  }'

Langues prises en charge : en, es, it, pt, fr, de, el, ru, pl. 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, 500 caractères maximum
Les clés de langue doivent être des codes de langue valides (10 caractères maximum)
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": "firma-verify=abc123xyz",
    "date_created": "2024-01-15T10:30:00Z"
  },
  "verification_instructions": {
    "record_type": "TXT",
    "record_name": "_firma-verification.acme.com",
    "record_value": "firma-verify=abc123xyz",
    "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`	`firma-verify=abc123xyz`

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.

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’utilisateur qui a envoyé la demande de signature. Par exemple, si vous définissez email_local_part sur noreply et que votre domaine vérifié est sign.acmecorp.com, les emails seront envoyés depuis :

Jane Smith <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.

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 :

// Générer un jeton JWT depuis votre backend
const token = await generateTemplateToken(templateId)

// Intégrer l'éditeur de modèles
const editorUrl = `https://app.firma.dev/template-editor?token=${token}`

<iframe 
  src="https://app.firma.dev/template-editor?token={jwt_token}"
  style="width:100%;height:900px;border:0;"
  title="Edit Template"
></iframe>

Guide de l’éditeur de modèles intégrable - Authentification JWT et implémentation complète

Éditeur de demande de signature intégrable

Fournissez une interface pour configurer les destinataires et options des demandes de signature :

<iframe 
  src="https://app.firma.dev/signing-request-editor?token={jwt_token}"
  style="width:100%;height:700px;border:0;"
  title="Configure Signing Request"
></iframe>

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
Utilisez des durées d’expiration de jeton courtes (recommandé : 1 à 4 heures)
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

Espaces de Travail Localisation

⌘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