Éditeur de modèles intégrable

Intégrez l’éditeur de modèles de Firma directement dans votre application grâce à une authentification JWT pour un accès sécurisé et limité dans le temps. C’est idéal pour les intégrations en marque blanche et les applications multi-tenant.

Cas d’usage

Édition de modèles en marque blanche : laissez vos utilisateurs éditer des modèles sous votre propre marque
Applications multi-tenant : accès sécurisé aux modèles par utilisateur sans exposer de clés API
Workflows intégrés : création de modèles fluide au sein de votre produit
Accès limité dans le temps : les jetons expirent automatiquement pour plus de sécurité

Comment ça fonctionne

Votre serveur demande un jeton JWT à l’API de Firma en utilisant votre clé API
Firma renvoie un jeton JWT de courte durée contenant l’ID du modèle
Votre frontend intègre l’éditeur avec le jeton JWT
Le jeton expire automatiquement (expiration configurable)

Limite de débit : les endpoints JWT prennent en charge 120 requêtes par minute par clé API pour les applications à fort volume.

Authentification JWT

Générer un jeton JWT

Générez un jeton JWT pour un modèle spécifique via l’endpoint /generate-template-token. Endpoint : POST /generate-template-token Corps de la requête :

{
  "companies_workspaces_templates_id": "123e4567-e89b-12d3-a456-426614174000"
}

Réponse (201 Created) :

{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2024-04-20T10:00:00Z",
  "jwt_record_id": "jwt123-e89b-12d3-a456-426614174000"
}

En-têtes de limite de débit :

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 1729180800

Guide d’implémentation

Sécurité : n’exposez jamais votre clé API dans du code côté client. Générez toujours les jetons JWT depuis votre backend sécurisé.

Backend : générer un jeton JWT

Appelez l’API de Firma depuis votre backend pour générer un jeton JWT. Votre endpoint backend doit accepter un ID de modèle et renvoyer le JWT à votre frontend. Exemple Node.js :

// Example: Simple backend function to generate JWT
async function generateTemplateToken(templateId) {
  const response = await fetch('https://api.firma.dev/functions/v1/signing-request-api/generate-template-token', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      companies_workspaces_templates_id: templateId
    })
  })
  
  const data = await response.json()
  return data.token
}

Exemple Python :

import os
import requests

def generate_template_token(template_id):
    response = requests.post(
        'https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
        headers={
            'Authorization': f'Bearer {os.getenv("FIRMA_API_KEY")}',
            'Content-Type': 'application/json'
        },
        json={
            'companies_workspaces_templates_id': template_id
        }
    )
    data = response.json()
    return data['token']

Implémentation frontend — HTML / JavaScript natif

<!-- Load the Firma Template Editor library -->
<script src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>

<!-- Create a container for the editor -->
<div id="template-editor-container"></div>

<script>
  // Assuming you've already fetched the JWT from your backend
  const jwt = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...';
  const templateId = '08f72e3b-79a8-4eac-a268-b3f9efaf6573';
  
  // Initialize the template editor
  const editor = new FirmaTemplateEditor({
    container: '#template-editor-container',
    jwt: jwt,
    templateId: templateId,
    
    // Optional configuration
    width: '100%',        // Custom width (default: '100%')
    height: '100vh',      // Custom height (default: '100vh')
    showCloseButton: true, // Show close button in header
    
    // Optional callbacks
    onSave: (data) => {
      console.log('Template saved:', data);
    },
    onClose: (data) => {
      if (data.hasUnsavedChanges) {
        // Prompt user to save before leaving
      }
      console.log('Editor closed, unsaved changes:', data.hasUnsavedChanges);
    },
    onError: (error) => {
      console.error('Editor error:', error);
    },
    onLoad: (template) => {
      console.log('Editor loaded successfully:', template);
    }
  });
</script>

Implémentation frontend — React

import { useEffect, useRef, useState } from 'react';

function TemplateEditorComponent({ templateId, jwt }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const editorRef = useRef<any>(null);
  const [isLoaded, setIsLoaded] = useState(false);

  // Load the Firma Template Editor library
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://api.firma.dev/functions/v1/embed-proxy/template-editor.js';
    script.async = true;
    
    script.onload = () => setIsLoaded(true);
    document.body.appendChild(script);
    
    return () => {
      if (document.body.contains(script)) {
        document.body.removeChild(script);
      }
    };
  }, []);

  // Initialize the editor when library and JWT are ready
  useEffect(() => {
    if (!isLoaded || !containerRef.current || !jwt) return;

    editorRef.current = new window.FirmaTemplateEditor({
      container: containerRef.current,
      jwt: jwt,
      templateId: templateId,
      
      // Optional configuration
      theme: 'dark',        // 'light' | 'dark' (default: 'dark')
      readOnly: false,      // Disable editing (default: false)
      width: '100%',        // Custom width (default: '100%')
      height: '100vh',      // Custom height (default: '100vh')
      showCloseButton: true, // Show close button in header
      
      // Optional callbacks
      onSave: (data) => console.log('Saved:', data),
      onClose: (data) => {
        if (data.hasUnsavedChanges) {
          // Prompt user to save before leaving
        }
      },
      onError: (error) => console.error('Error:', error),
      onLoad: (template) => console.log('Loaded:', template)
    });

    return () => {
      if (editorRef.current?.destroy) {
        editorRef.current.destroy();
      }
    };
  }, [isLoaded, jwt, templateId]);

  return <div ref={containerRef} className="w-full h-full" />;
}

export default TemplateEditorComponent;

Options de configuration

Option	Type	Description
`container`	HTMLElement \| string	Élément DOM ou sélecteur CSS où monter l’éditeur (requis)
`jwt`	string	Jeton d’authentification fourni par votre backend (requis)
`templateId`	string	Identifiant du modèle (requis)
`theme`	`'dark'` \| `'light'`	Thème de l’éditeur (par défaut : `'dark'`)
`readOnly`	boolean	Active le mode lecture seule (par défaut : `false`)
`height`	string	Hauteur du conteneur (par défaut : `'100vh'`)
`width`	string	Largeur du conteneur (par défaut : `'100%'`)
`showCloseButton`	boolean	Affiche un bouton de fermeture dans l’en-tête de l’éditeur (par défaut : `false`)
`onSave`	function	Callback appelé lorsque le modèle est enregistré
`onClose`	function	Callback appelé quand le bouton de fermeture est cliqué ou que `triggerClose()` est appelé. Reçoit `{ hasUnsavedChanges: boolean }`
`onError`	function	Callback pour la gestion des erreurs
`onLoad`	function	Callback appelé lorsque l’éditeur se charge avec les données du modèle

Méthodes d’instance

Méthode	Description
`triggerClose()`	Déclenche le flux de fermeture par programmation. Vérifie les changements non enregistrés et invoque `onClose` avec `{ hasUnsavedChanges: boolean }`

Utilisez triggerClose() lorsque votre application hôte doit fermer l’éditeur depuis sa propre interface, par exemple lors d’un événement de navigation parent ou d’un bouton « retour » :

// Close the editor from your app's UI
document.getElementById('my-back-button').addEventListener('click', () => {
  editor.triggerClose();
});

Événements postMessage (éditeur → hôte)

L’éditeur de Firma émet des événements postMessage pour les actions importantes du cycle de vie. Voici un schéma d’événements minimal recommandé que vous pouvez implémenter pour réagir aux enregistrements et publications dans l’éditeur. Si vous disposez d’un schéma canonique dans votre plateforme, remplacez ces noms par vos noms d’événements officiels.

Utilisez ces événements pour suivre l’activité de l’éditeur sans effectuer d’appels API supplémentaires, afin de rester dans les limites de débit.

Enveloppe de l’événement (payload window.postMessage) :

{
	"type": "editor.event",
	"event": "editor.saved", // or editor.published, editor.closed
	"payload": {
		"template_id": "tmpl_123",
		"updated_at": "2025-09-04T12:34:56Z",
		"draft": false
	}
}

Exemple d’écouteur côté client (JS simple)

window.addEventListener('message', (ev) => {
	// 1) Validate origin
	if (ev.origin !== 'https://app.firma.dev') return
	// 2) Validate shape
	const data = ev.data || {}
	if (data.type !== 'editor.event') return

	switch (data.event) {
		case 'editor.saved':
			console.log('Template saved', data.payload)
			// Optionally fetch the latest template via API
			break
		case 'editor.published':
			console.log('Template published', data.payload)
			break
		case 'editor.closed':
			console.log('Editor closed')
			break
		default:
			break
	}
})

Gestion du cycle de vie du jeton

Les jetons JWT sont générés avec une durée d’expiration suffisante pour des sessions d’édition classiques. L’éditeur gère automatiquement l’expiration du jeton.

Expiration automatique

Les jetons JWT expirent automatiquement en fonction de l’horodatage expires_at. Après expiration :

L’éditeur intégré rejette le jeton
Les utilisateurs doivent demander un nouveau jeton pour continuer
Aucun appel API n’est nécessaire, les jetons expirent de manière passive

Limite de débit

Consultez le guide sur les Limites de débit.

Bonnes pratiques de sécurité

N’exposez jamais votre clé API dans du code côté client. Générez toujours les jetons JWT depuis un endpoint serveur sécurisé.

✅ À faire

✅ Générez les jetons depuis votre serveur backend
✅ Surveillez les limites de débit
✅ Utilisez HTTPS pour toutes les requêtes API

❌ À ne pas faire

❌ N’exposez pas les clés API dans le code frontend
❌ Ne réutilisez pas les jetons entre différents utilisateurs
❌ Ne journalisez pas les jetons JWT (risque de sécurité)
❌ Ne partagez pas les jetons entre différents modèles

Dépannage

Erreur de jeton expiré

Symptôme : l’éditeur affiche « Token expired » ou une erreur d’authentification Solution :

Implémentez le renouvellement du jeton avant son expiration
Générez un nouveau jeton et rechargez l’iframe
Vérifiez la synchronisation de l’horloge système

401 Unauthorized

Symptôme : la génération du JWT échoue avec un 401 Causes possibles :

Clé API invalide ou manquante
La clé API ne dispose pas des permissions requises
La clé API est désactivée

Solution : vérifiez la clé API dans le tableau de bord et contrôlez les permissions

404 Not Found

Symptôme : modèle introuvable lors de la génération du JWT Causes possibles :

L’ID du modèle n’existe pas
Le modèle appartient à un autre espace de travail
Le modèle a été supprimé

Solution : vérifiez l’ID du modèle et l’accès à l’espace de travail

Limite de débit dépassée

Symptôme : 429 Too Many Requests Solution :

Implémentez la mise en cache des jetons
Augmentez la durée d’expiration du jeton
Attendez la réinitialisation de la limite de débit (vérifiez l’en-tête X-RateLimit-Reset)
Implémentez une logique de nouvelle tentative avec backoff

Étapes suivantes

Intégrer l’interface de signature pour une signature en marque blanche (100 req/min)
Envoyer des demandes de signature avec des modèles personnalisés (100 req/min)
Configurer des webhooks pour suivre les événements liés aux modèles (60 req/min)

​Cas d’usage

​Comment ça fonctionne

​Authentification JWT

​Générer un jeton JWT

​Guide d’implémentation

​Backend : générer un jeton JWT

​Implémentation frontend — HTML / JavaScript natif

​Implémentation frontend — React

​Options de configuration

​Méthodes d’instance

​Événements postMessage (éditeur → hôte)

​Exemple d’écouteur côté client (JS simple)

​Gestion du cycle de vie du jeton

​Expiration automatique

​Limite de débit

​Bonnes pratiques de sécurité

​✅ À faire

​❌ À ne pas faire

​Dépannage

​Erreur de jeton expiré

​401 Unauthorized

​404 Not Found

​Limite de débit dépassée

​Étapes suivantes

Cas d’usage

Comment ça fonctionne

Authentification JWT

Générer un jeton JWT

Guide d’implémentation

Backend : générer un jeton JWT

Implémentation frontend — HTML / JavaScript natif

Implémentation frontend — React

Options de configuration

Méthodes d’instance

Événements postMessage (éditeur → hôte)

Exemple d’écouteur côté client (JS simple)

Gestion du cycle de vie du jeton

Expiration automatique

Limite de débit

Bonnes pratiques de sécurité

✅ À faire

❌ À ne pas faire

Dépannage

Erreur de jeton expiré

401 Unauthorized

404 Not Found

Limite de débit dépassée

Étapes suivantes