API et développeurs

Bâtissez avec les mêmes briques que nous.

L’API REST de VG·Sign crée, envoie et suit les dossiers avec un jeton d’espace. Elle est incluse avec Pro, Équipe et Entreprise, et la référence complète se trouve sur la page de l’API.

Sur cette page

Obtenez un jeton d’espace

  1. En tant que propriétaire de l’espace, ouvrez Paramètres, Intégrations.
  2. Sous Accès à l’API, cliquez sur Créer un jeton.
  3. Copiez le jeton tout de suite. Il commence par vgs_live_ et n’est affiché qu’une fois, car nous n’en gardons qu’une empreinte.

Un espace a un seul jeton. Remplacer le jeton le remplace, et l’ancien cesse aussitôt de fonctionner. Révoquer le supprime. Avec le forfait gratuit, le bouton est remplacé par « L’API est offerte avec les forfaits Pro, Équipe et Entreprise. » Si un espace payant passe au forfait gratuit, son jeton est suspendu et les appels répondent 403 plan_required jusqu’à ce que vous repassiez à un forfait payant.

Votre première requête

Envoyez le jeton comme jeton porteur. Cet appel liste vos dossiers, du plus récent au plus ancien :

curl https://vg-sign.com/api/v1/envelopes \
  -H "Authorization: Bearer vgs_live_…"

La réponse contient un tableau envelopes avec total, limit, offset et has_more. Filtrez avec ?status=completed ou votre propre external_ref. limit va jusqu’à 100.

Chaque jeton peut faire 600 requêtes par minute. Au-delà, vous recevez un 429 avec un en-tête Retry-After. Chaque point d’accès est décrit en OpenAPI 3.1 à /api/v1/openapi.json, que la plupart des générateurs de clients savent lire.

Placez des champs par l’API

POST /api/v1/envelopes accepte du multipart/form-data : une partie metadata en JSON et une partie files par PDF. Mettez les destinataires et un tableau fields dans ce JSON. Chaque champ est une case sur une page pour un destinataire :

{
  "recipient_email": "client@example.com",
  "document": "contract.pdf",
  "type": "signature",
  "page": 1,
  "x": 0.12, "y": 0.60,
  "width": 0.30, "height": 0.07
}
  • Les coordonnées sont des fractions de la page, de 0 à 1, mesurées à partir du coin supérieur gauche.
  • document est un nom de fichier tiré de documents. Omettez-le s’il n’y a qu’un seul document à signer.
  • type vaut signature, initials, full_name, text, date, time, checkbox, strikethrough, multiline, dropdown, radio ou attachment. required vaut true par défaut, et chaque signataire a besoin d’au moins un champ obligatoire.
  • Une liste déroulante demande options (de 2 à 50) et accepte default_option. Chaque bouton radio est une entrée avec group et option_label; les entrées ayant le même group forment une question de 2 à 10 options pour un seul signataire dans un seul document.

La réponse est 201 avec l’identifiant du dossier et fields_required: false. Envoyez-le avec POST /api/v1/envelopes/{id}/send. Sans champs, vous obtenez fields_required: true et un editor_url pour les placer à la main.

Par l’API, les fichiers doivent être des PDF de 25 Mo et 50 pages au plus, et un dossier accepte jusqu’à 15 documents (50 par from-refs), 50 destinataires et 500 champs. Les dossiers créés par l’API comptent aussi dans une limite de 100 par mois avec Pro et de 500 avec Équipe, sans plafond avec Entreprise. Les dossiers envoyés depuis le tableau de bord n’y comptent jamais.

Webhooks et MCP

Pour être informé des changements sans interroger l’API, abonnez-vous aux webhooks dans Paramètres, Intégrations, ou par l’API avec POST /api/v1/webhooks. L’article Intégrations explique la signature, et la page Webhooks montre le contenu envoyé.

Le serveur MCP permet à Claude Code, Claude Desktop et Cursor de travailler avec les dossiers par la même API et le même jeton. C’est un seul fichier, server.mjs, exécuté avec Node, qui lit le jeton dans VG_SIGN_API_TOKEN. Téléchargez-le et vérifiez-le avec la somme de contrôle publiée plutôt que de le copier à la main :

curl -fsSLO https://vg-sign.com/mcp/server.mjs
curl -fsSL https://vg-sign.com/mcp/server.mjs.sha256 | sha256sum -c -
{
  "mcpServers": {
    "vg-sign": {
      "command": "node",
      "args": ["/path/to/server.mjs"],
      "env": {
        "VG_SIGN_API_TOKEN": "vgs_live_…",
        "VG_SIGN_DOWNLOAD_DIR": "/path/to/a/downloads/folder"
      }
    }
  }
}

Il peut lister et lire les dossiers et les modèles, créer un dossier à partir d’un modèle, l’envoyer, relancer et annuler, et télécharger le PDF signé et le certificat. Il ne peut pas téléverser un nouveau PDF : faites-le dans l’application ou par l’API. Envoyer, relancer, annuler et créer-et-envoyer agissent sur de vrais dossiers et écrivent à de vraies personnes. L’annulation est ce qui défait un envoi, et une annulation ne peut pas être défaite par un autre appel.

Il n’existe pas de jetons limités à certains droits : l’assistant peut faire tout ce que le jeton peut faire. Créez le jeton dans un espace dédié si vous voulez limiter ce qu’il peut atteindre. Remplacer le jeton (Paramètres, Intégrations) le change aussitôt et coupe toute autre intégration qui utilise l’ancien. Remplacez-le donc dès qu’il a pu être exposé.

Pour intégrer la signature à votre propre produit, le widget intégré (en bêta) place le signataire dans un iframe à partir d’une seule balise de script et signale à votre page les événements de signature et de refus par postMessage. L’affichage dans un cadre est refusé tant que nous n’avons pas ajouté l’origine de votre site à la liste autorisée. Demandez donc l’accès d’abord. La page Widget intégré donne les détails.

Retour au centre d’aide

  • Intégrez VG·Sign à vos outils.

    Publiez les événements de vos dossiers dans un canal Slack ou Microsoft Teams, ou envoyez du JSON signé à n’importe quelle adresse HTTPS, y compris Zapier, Make et n8n. Tout se règle dans Paramètres, sous Intégrations.

    Lire
  • Préparez une fois, envoyez toujours.

    Un modèle garde les documents d’un dossier, la disposition des champs et les rôles de signature. Entrez les noms et les courriels pour créer un nouveau dossier, ou envoyez un dossier pour chaque ligne d’un fichier CSV.

    Lire
  • Forfaits, factures et places.

    Le forfait gratuit couvre 5 dossiers par mois. Pro est pour un expéditeur à un prix mensuel fixe. Équipe est facturé par personne, pour 2 à 10 personnes.

    Lire