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, create-from-template, send, list
• Documents : upload-document (endpoint d’upload simplifié)
• Contacts : list
• Utils : whoami, workspace list

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.

Téléchargement de Documents

Le proxy API fournit un endpoint /upload-document simplifié qui gère automatiquement le chiffrement et le stockage des documents. C’est la méthode recommandée pour télécharger des documents lors de l’utilisation du proxy API.

Utilisation de l’Endpoint d’Upload

curl -X POST http://localhost:8080/upload-document \
  -H "Authorization: Bearer $ACCESS_KEY:$SECRET_KEY" \
  -F "workspaceUuid=votre-uuid-workspace" \
  -F "envelopeTitle=Mon Document" \
  -F "file=@/chemin/vers/document.pdf"

L’endpoint accepte des données multipart/form-data avec :

Champ	Type	Requis	Description
workspaceUuid	string	Oui	L’UUID de l’espace de travail où créer l’enveloppe
envelopeTitle	string	Oui	Le titre de l’enveloppe à créer
file	file	Oui	Le document PDF à télécharger (max 200 Mo)

Une réponse réussie :

{
    "envelopeUuid": "uuid-de-lenveloppe-creee",
    "documentUuid": "uuid-du-document-telecharge",
    "message": "Document uploaded successfully"
}

Exemple Complet de Workflow d’Upload

#!/bin/bash

# Configuration
PROXY_URL="http://localhost:8080"
ACCESS_KEY="votre-cle-dacces"
SECRET_KEY="votre-cle-secrete"
FILE_PATH="chemin/vers/document.pdf"
ENVELOPE_TITLE="Contrat"

# Étape 1 : Obtenir l'UUID de l'espace de travail
echo "Récupération des espaces de travail..."
WORKSPACE_RESPONSE=$(curl -s -X POST "$PROXY_URL/public/workspace/list" \
  -H "Authorization: Bearer $ACCESS_KEY:$SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{}')

WORKSPACE_UUID=$(echo "$WORKSPACE_RESPONSE" | grep -o '"uuid":"[^"]*"' | head -1 | cut -d'"' -f4)
echo "Utilisation de l'espace de travail : $WORKSPACE_UUID"

# Étape 2 : Télécharger le document
echo "Téléchargement du document..."
UPLOAD_RESPONSE=$(curl -s -X POST "$PROXY_URL/upload-document" \
  -H "Authorization: Bearer $ACCESS_KEY:$SECRET_KEY" \
  -F "workspaceUuid=$WORKSPACE_UUID" \
  -F "envelopeTitle=$ENVELOPE_TITLE" \
  -F "file=@$FILE_PATH")

ENVELOPE_UUID=$(echo "$UPLOAD_RESPONSE" | grep -o '"envelopeUuid":"[^"]*"' | cut -d'"' -f4)
echo "Enveloppe créée : $ENVELOPE_UUID"

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

Exemple : Envoyer une Enveloppe

Après avoir créé une enveloppe (via upload ou à partir d’un modèle), envoyez-la aux destinataires :

curl http://localhost:8080/public/envelope/send \
  -H "Authorization: Bearer $ACCESS_KEY:$SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workspaceUuid": "votre-uuid-workspace",
    "envelopeUuid": "votre-uuid-enveloppe",
    "customInvitationMessage": "Veuillez consulter et signer ce document."
  }'

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.

Limites de Taille de Fichier

L’endpoint /upload-document accepte des fichiers jusqu’à 200 Mo. Pour des fichiers plus volumineux ou si vous avez besoin de plus de contrôle sur le processus d’upload, vous pouvez utiliser l’helper d’upload du SDK qui gère le chiffrement et les uploads par morceaux.

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.

Dépannage