Utilisation

Sécurité : Pour vérifier l’authenticité du conteneur et inspecter son SBOM, consultez le Guide d’attestation & vérification.

Utilisation du Conteneur

Exécutez le conteneur API proxy avec Docker :

docker run -p 8080:8080 subnoto/api-proxy:latest

Le conteneur expose le service API proxy sur le port 8080. Vous pouvez mapper ceci sur n’importe quel port de votre machine hôte en changeant le premier numéro de port (par exemple, -p 3000:8080 pour exposer sur le port 3000).

Utilisateurs Mac (Apple Silicon) : Si vous rencontrez des problèmes de connexion, liez explicitement à localhost et spécifiez la plateforme :

docker run --platform linux/amd64 -p 127.0.0.1:8080:8080 subnoto/api-proxy:latest

Note : Le conteneur ne nécessite pas de variables d’environnement pour s’exécuter. Les identifiants API sont fournis lors des requêtes, pas au démarrage du conteneur.

Authentification API

Pour utiliser le proxy API, vous avez besoin d’une clé d’accès et d’une clé secrète. Ces identifiants sont fournis lorsque vous créez une clé API dans votre espace de travail Subnoto.

Obtention des Identifiants

1. Connectez-vous à votre espace de travail Subnoto sur app.subnoto.com
2. Naviguez vers Paramètres → Clés API
3. Créez une nouvelle clé API
4. Sauvegardez la ACCESS_KEY et la SECRET_KEY en toute sécurité

Effectuer des Requêtes Authentifiées

Incluez vos identifiants dans l’en-tête Authorization en utilisant le format de jeton Bearer :

Authorization: Bearer $ACCESS_KEY:$SECRET_KEY

Utilisation Basique de l’API

Testez votre connexion avec le point de terminaison whoami :

curl http://localhost:8080/public/utils/whoami \
  -H "Authorization: Bearer $ACCESS_KEY:$SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Remplacez :

• localhost:8080 par votre URL de déploiement si le conteneur s’exécute ailleurs
• $ACCESS_KEY par votre clé d’accès réelle
• $SECRET_KEY par votre clé secrète réelle

Une réponse réussie retournera des informations sur votre session authentifiée :

{
  "userId": "...",
  "workspaceId": "...",
  "permissions": [...]
}

Points de Terminaison Disponibles

Le proxy API donne accès aux fonctionnalités principales de Subnoto :

• Templates : list, lister les modèles disponibles
• Enveloppes : create-from-template, send
• Utils : whoami

Pour la documentation complète de l’API et la référence des points de terminaison, consultez la Documentation API Subnoto.

Important : Tous les points de terminaison API doivent être accessibles via le conteneur proxy API. N’appelez pas enclave.subnoto.com directement.

Exemple : Créer une Enveloppe à partir d’un Modèle

# D'abord, listez les modèles disponibles
curl http://localhost:8080/public/template/list \
  -H "Authorization: Bearer $ACCESS_KEY:$SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"page": 1}'

# Ensuite, créez une enveloppe à partir d'un modèle
curl http://localhost:8080/public/envelope/create-from-template \
  -H "Authorization: Bearer $ACCESS_KEY:$SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workspaceUuid": "votre-uuid-workspace",
    "templateUuid": "uuid-template",
    "recipients": [
      {
        "type": "manual",
        "label": "customer",
        "email": "[email protected]",
        "firstname": "Jean",
        "lastname": "Dupont"
      }
    ]
  }'

Notes Importantes

Exigence de l’UUID de l’Espace de Travail

Le paramètre workspaceUuid est requis dans les requêtes pour spécifier à quel espace de travail appartient la ressource. Meilleure pratique : Créez un espace de travail dédié pour les enveloppes créées via l’API afin de les organiser séparément des enveloppes créées manuellement.

Limitation d’un Seul Document

Actuellement, un seul document par enveloppe est pris en charge, à la fois via l’API et l’interface utilisateur. Il s’agit d’une limitation actuelle de la plateforme.

Restrictions d’Espace de Travail pour les Clés API

Les restrictions d’espace de travail pour les clés API ne sont pas actuellement disponibles. Cette fonctionnalité sera ajoutée dans une version future, vous permettant de limiter les clés API à l’accès uniquement à des espaces de travail spécifiques.