Passer au contenu principal
  • Accès partitionné : les utilisateurs, modèles et activités sont limités à un seul espace de travail.
  • Suivi de l’utilisation : consultez les enveloppes envoyées par espace de travail pour un reporting clair.
  • Sécurité par conception : aucune exposition croisée des documents ou des données entre espaces de travail.
Cela permet de donner facilement à chaque client ou équipe son propre environnement de signature privé, tout en gérant l’ensemble via la même API.

​
Points de terminaison principaux

Points de terminaison principaux (consultez la référence API pour tous les détails) :
  • POST /workspaces — créer un espace de travail
  • GET /workspaces/{workspace_id} — récupérer les détails d’un espace de travail
  • PUT /workspaces/{workspace_id} — mettre à jour un espace de travail
  • GET /workspaces — lister les espaces de travail (pagination)
  • GET /workspace/{workspace_id}/settings — récupérer les paramètres de l’espace de travail
  • PUT /workspace/{workspace_id}/settings — mettre à jour les paramètres de l’espace de travail
Consultez le guide sur les Limites de Débit.
Vous trouverez également des pages de référence dédiées sous api-reference/v01.15.00/workspaces :
  • api-reference/v01.15.00/workspaces/create-a-new-workspace
  • api-reference/v01.15.00/workspaces/list-workspaces
  • api-reference/v01.15.00/workspaces/update-a-workspace
Authentification Toutes les requêtes doivent inclure un en-tête Authorization utilisant votre clé API : 
Authorization: Bearer YOUR_API_KEY
Remarque : n’exposez jamais votre clé API principale aux navigateurs des utilisateurs finaux. Pour les opérations par espace de travail devant être initiées depuis le frontend, appelez votre backend qui détient la clé.

​
Créer un espace de travail

Point de terminaison : POST /workspaces Corps requis : { "name": "string" } Exemple (curl) : 
curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/workspaces" \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp Workspace" }'
La réponse réussie (201) renvoie la ressource Workspace, y compris la api_key (live) et la test_api_key de l’espace de travail. Exemple de structure : 
{
  "id": "workspace_123",
  "name": "Acme Corp Workspace",
  "protected": false,
  "api_key": "firma_live_…",
  "test_api_key": "firma_test_…",
  "created_date": "2025-09-04T12:00:00Z",
  "updated_date": "2025-09-04T12:00:00Z"
}
api_key est la clé live de l’espace de travail et test_api_key est sa clé de test. Consultez Authentification pour savoir comment fonctionne le mode test. Exemple serveur — Node (fetch) : 
import fetch from 'node-fetch'

export async function createWorkspace(name) {
  const resp = await fetch('https://api.firma.dev/functions/v1/signing-request-api/workspaces', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name })
  })
  if (!resp.ok) throw new Error(`create workspace failed: ${resp.status}`)
  return resp.json()
}
Exemple serveur — Python (requests) : 
import os
import requests

def create_workspace(name):
    url = 'https://api.firma.dev/functions/v1/signing-request-api/workspaces'
    resp = requests.post(url, headers={
        'Authorization': f"Bearer {os.environ['FIRMA_API_KEY']}",
        'Content-Type': 'application/json'
    }, json={ 'name': name })
    resp.raise_for_status()
    return resp.json()

​
Récupérer un espace de travail

Point de terminaison : GET /workspaces/{workspace_id} Exemple (curl) : 
curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY"
Réponse : la ressource Workspace (voir l’exemple ci-dessus).

​
Mettre à jour un espace de travail

Point de terminaison : PUT /workspaces/{workspace_id} — remplacement complet de la ressource. Le corps requis est le même que pour CreateWorkspace (par exemple, { "name": "New name" }). Exemple (curl) : 
curl -X PUT "https://api.firma.dev/functions/v1/signing-request-api/workspaces/workspace_123" \
  -H "Authorization: Bearer $FIRMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp - East Coast" }'
Exemple serveur — Node (fetch) : 
export async function updateWorkspace(workspaceId, name) {
  const resp = await fetch(`https://api.firma.dev/functions/v1/signing-request-api/workspaces/${workspaceId}`, {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name })
  })
  if (!resp.ok) throw new Error(`update workspace failed: ${resp.status}`)
  return resp.json()
}

​
Lister les espaces de travail

Point de terminaison : GET /workspaces Prend en charge les paramètres de requête page et page_size. Exemple : 
curl "https://api.firma.dev/functions/v1/signing-request-api/workspaces?page=1&page_size=20" \
  -H "Authorization: Bearer $FIRMA_API_KEY"
La structure de la réponse contient results (tableau de Workspace) et les métadonnées pagination.

​
Bonnes pratiques RBAC et clés API

  • Utilisez des clés API à portée limitée lorsque c’est possible : conservez une clé API principale réservée au serveur et créez des clés API par espace de travail pour les partenaires d’intégration si votre plateforme le permet.
  • Ne renvoyez jamais les clés API au navigateur. Pour les opérations initiées par les utilisateurs finaux, appelez votre backend qui effectue l’appel API vers Firma.
  • Utilisez l’idempotence lorsqu’elle est prise en charge (pour les points de terminaison acceptant Idempotency-Key) afin d’éviter les doubles créations lors de nouvelles tentatives.

​
Cas particuliers et dépannage

  • Noms en double : les noms d’espace de travail sont conviviaux pour l’affichage et peuvent ne pas être uniques ; utilisez id pour les références programmatiques.
  • Espaces de travail protégés : le drapeau protected indique les espaces de travail détenus par le système, qui ne peuvent pas être supprimés ou modifiés via les flux normaux.
  • Limites de débit et erreurs : examinez les réponses non-2xx pour { error, code } et affichez des messages pertinents aux opérateurs.
  • Limite de débit dépassée (429) : surveillez l’en-tête X-RateLimit-Remaining et mettez en œuvre un backoff exponentiel pour les nouvelles tentatives.

​
Étapes suivantes