> ## Documentation Index
> Fetch the complete documentation index at: https://docs.firma.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Marque Blanche

> Configurez une marque personnalisée, des domaines d'email, des modèles d'email et des expériences intégrées pour créer une expérience de signature entièrement personnalisée pour vos clients.

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 :

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

<Note>
  Tous les exemples d'API utilisent votre clé API directement dans l'en-tête `Authorization`. N'utilisez pas le préfixe `Bearer`.
</Note>

***

## 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.

```bash theme={null}
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 :

```bash theme={null}
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 :

```bash theme={null}
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) :

```bash theme={null}
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 :**

```bash theme={null}
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) :

```bash theme={null}
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 :

```bash theme={null}
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 :

1. **Paramètre de l'espace de travail** (priorité la plus élevée)
2. **Paramètre de l'entreprise**
3. **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](/api-reference/v01.27.00/workspace-settings/get-workspace-settings) 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 :

1. **Conditions de l'espace de travail** pour la langue du signataire (priorité la plus élevée)
2. **Conditions de l'entreprise** pour la langue du signataire
3. **Conditions par défaut de Firma** (priorité la plus basse)

### Définir les conditions au niveau de l'entreprise

```bash theme={null}
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

```bash theme={null}
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 :

```bash theme={null}
# 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 :

```bash theme={null}
# 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 :

```bash theme={null}
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](/api-reference/v01.27.00/signer-terms/list-company-signer-terms) 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 :

```bash theme={null}
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 :

```bash theme={null}
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

<Note>
  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.
</Note>

***

## 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é :

```bash theme={null}
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)** :

```json theme={null}
{
  "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` |

<Note>
  La propagation DNS prend généralement quelques minutes mais peut prendre jusqu'à 48 heures.
</Note>

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

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

```bash theme={null}
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** :

```json theme={null}
{
  "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 :

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

**Réponse** :

```json theme={null}
{
  "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 :

```bash theme={null}
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)** :

```json theme={null}
{
  "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 :

```bash theme={null}
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**

```bash theme={null}
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](/api-reference/v01.27.00/email-domains/list-company-domains) 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 :**

1. Domaine vérifié de l'espace de travail (le principal étant privilégié)
2. Domaine vérifié de l'entreprise
3. `updates.firma.dev` (par défaut)

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

1. Paramètre `email_local_part` de l'espace de travail
2. Paramètre `email_local_part` de l'entreprise
3. `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) :

```bash theme={null}
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) :

```bash theme={null}
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 :

```bash theme={null}
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 :

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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 :

```bash theme={null}
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 :

1. **Modèle de l'espace de travail** (priorité la plus élevée)
2. **Modèle de l'entreprise**
3. **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.

<Warning>
  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.
</Warning>

Consultez la [référence de l'API des modèles d'email](/api-reference/v01.27.00/email-templates/list-workspace-email-templates) 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

```bash theme={null}
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 :

```js theme={null}
// 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 :

```html theme={null}
<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](embeddable-signing) - 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 :

```js theme={null}
// 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}`
```

```html theme={null}
<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](embeddable-template-editor) - 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 :

```html theme={null}
<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](embeddable-signing-request-editor) - 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

```js theme={null}
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

```js theme={null}
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

```js theme={null}
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)

```js theme={null}
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)

```js theme={null}
// 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)

```js theme={null}
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

```jsx theme={null}
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](#afficher-les-modèles-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](embeddable-signing) - Intégrer l'expérience de signature dans votre application
* [Éditeur de modèles intégrable](embeddable-template-editor) - Permettre aux utilisateurs de modifier des modèles avec authentification JWT
* [Éditeur de demande de signature intégrable](embeddable-signing-request-editor) - Configurer les demandes de signature dans votre interface
* [Création d'espaces de travail](creating-workspaces) - Configurer des environnements isolés pour les clients
* [Webhooks](webhooks) - Suivre les événements de signature en temps réel