API

Conçu pour l’intégration.

REST et JSON sur HTTPS, authentification par jeton porteur propre à chaque espace, webhooks pour chaque changement d’état. C’est la couche de signature sous votre produit, et non une destination distincte.

Sur cette page

Aperçu rapide

L’authentification se fait par un jeton porteur propre à l’espace, que vous créez dans les paramètres. Un envoi complet demande trois appels au plus : créer le dossier avec ses documents, ses destinataires et le placement des champs, l’envoyer, puis lire l’état (ou attendre le webhook). Personne n’a besoin d’ouvrir notre éditeur pour cela.

URL de base

https://vg-sign.com/api/v1

Le chemin de base était auparavant /api/v1/internal. Ce préfixe répond toujours et continuera de répondre, donc rien de ce qui a été construit dessus n’a besoin de changer. Il n’a jamais été exact : chaque point de terminaison ci-dessous accepte un jeton d’espace ordinaire.

Une description lisible par machine de tout le contenu de cette page se trouve à /api/v1/openapi.json (OpenAPI 3.1). Donnez-la à un générateur de client ou importez-la dans Postman ou Insomnia.

Authentification

Créez un jeton d’API d’espace dans Paramètres, Intégrations, puis appelez l’API avec Authorization: Bearer vgs_live_…. Les jetons sont limités à votre espace, stockés sous forme hachée et révocables à tout moment.

L’API exige le forfait Pro, Équipe ou Entreprise. Un jeton d’un espace gratuit reçoit 403 plan_required jusqu’au changement de forfait.

Connecter un agent depuis un CRM est un privilège distinct et plus élevé. Le transfert de connexion unique à usage unique à /oauth/authorize, l’en-tête On-Behalf-Of et le retrait des droits ne répondent que pour un espace que nous avons activé comme compte de service CRM, et seulement pour des personnes qui font déjà partie de cet espace. Un jeton d’espace ordinaire reçoit 403 not_a_service_account sur ces trois éléments; tout le reste de cette page fonctionne avec n’importe quel jeton. Écrivez-nous à info@vg-realestate.ca pour faire activer un espace.

Principaux points d’accès

  • POST /envelopes : crée un dossier à partir d’un ou de plusieurs PDF téléversés (multipart/form-data : une partie JSON metadata et une partie files par document). Les destinataires, l’ordre de signature et, au besoin, le placement des champs sont tous dans la même requête. Renvoie 201 avec l’identifiant du dossier, status: "draft" et fields_required, qui vaut false une fois que vous avez placé les champs vous-même.
  • POST /envelopes/:id/send : envoie un brouillon pour signature. Envoie un courriel aux signataires, renouvelle leurs liens de signature et inscrit l’envoi au journal d’audit.
  • GET /envelopes : liste les dossiers de l’espace, du plus récent au plus ancien. Filtres : status, external_ref; pagination : limit (100 au maximum), offset.
  • GET /envelopes/:id : lit l’état du dossier, l’avancement des destinataires et le journal d’audit.
  • GET /envelopes/:id/final : récupère le ou les PDF signés et aplatis.
  • GET /envelopes/:id/attachments/:attachmentId : obtenir un lien de téléchargement valable 60 secondes pour un fichier joint par un signataire. GET /envelopes/:id liste ces fichiers. Les webhooks ne transportent jamais de fichier ni de lien.
  • GET /envelopes/:id/certificate : récupère le certificat de fin de signature.
  • POST /envelopes/:id/remind : renvoie l’avis de signature aux destinataires en attente.
  • POST /envelopes/:id/void : annule un dossier en cours.
  • POST /envelopes/from-refs : crée un dossier à partir de documents déjà téléversés par /uploads/init, par référence.
  • POST /webhooks · GET /webhooks · DELETE /webhooks/:id : gèrent les abonnements aux événements du cycle de vie.

Destinataires

GET /envelopes/:id/recipients renvoie les personnes d’un dossier et où chacune en est. Sur un brouillon, POST /envelopes/:id/recipients ajoute une personne, PATCH /envelopes/:id/recipients/:rid la modifie (nom, courriel, téléphone, libellé, signataire ou copie seulement, place dans l’ordre de signature) et DELETE la retire. Le retrait est refusé tant que cette personne a des champs placés, car il supprimerait aussi ces champs; ajoutez ?force=true pour l’accepter.

Après l’envoi, le même PATCH règle le cas d’une adresse mal saisie : nom et courriel seulement, et seulement pour une personne qui n’a encore ni signé ni refusé. Changer le courriel retire le lien envoyé à la mauvaise adresse et en crée un nouveau, envoyé à l’adresse corrigée quand vient le tour de cette personne. L’échéance est conservée plutôt que recommencée, et le remplacement est inscrit au journal d’audit. POST /envelopes/:id/recipients/:rid/remind envoie un rappel à une personne précise, alors que le rappel au niveau du dossier vise la personne dont on attend la signature.

Modèles

Un modèle contient les documents, la disposition des champs et les rôles de signature, de sorte qu’un ensemble récurrent demande un seul appel plutôt qu’un téléversement, une disposition de champs et un envoi. GET /templates les liste; GET /templates/:id renvoie les rôles à remplir; POST /templates/:id/envelopes associe une vraie personne à chaque rôle et crée le dossier. Ajoutez "send": true pour l’envoyer dans la même requête.

POST /templates/8f3c…/envelopes
{
  "assignments": [
    { "signing_order": 1, "full_name": "Dana Reyes", "email": "dana@example.com" }
  ],
  "external_ref": "deal-4417",
  "send": true
}

Placement des champs

Chaque entrée de fields[] est une case sur une page, attribuée à un destinataire. Les coordonnées sont des fractions de la page (de 0 à 1, mesurées depuis le coin supérieur gauche), donc elles valent pour tout format de page. document nomme un fichier de documents[] et peut être omis lorsque le dossier ne contient qu’un seul document à signer.

{
  "recipient_email": "buyer@example.com",
  "document": "contract.pdf",
  "type": "signature",
  "page": 1,
  "x": 0.12, "y": 0.60,
  "width": 0.30, "height": 0.07,
  "required": true
}

Types : signature, initials, full_name, text, date, time, checkbox, strikethrough, multiline, dropdown, radio, attachment. 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, et peut porter group_label; les entrées ayant le même group forment une question de 2 à 10 options pour un seul signataire dans un seul document. Les champs de texte acceptent aussi placeholder, max_length et validation (email · number · phone); les dates acceptent date_format, les heures time_format et time_mode, les cases à cocher checkbox_style. Un placement refusé revient avec un 400 qui nomme l’entrée, par exemple fields[2].page is 9 but "contract.pdf" has 4 page(s).

Sans fields[], la réponse contient fields_required: true et un editor_url : le dossier attend à l’état de brouillon jusqu’à ce que quelqu’un place les champs dans l’éditeur de VG·Sign. Chaque signataire doit avoir au moins un champ obligatoire, sinon l’envoi est refusé.

Événements des webhooks

Chaque changement d’état émet un webhook avec un contenu signé. Les événements auxquels une intégration s’abonne habituellement : envelope.created, envelope.sent, envelope.opened, envelope.document_signed, envelope.all_signed, envelope.completed, envelope.declined, envelope.voided, envelope.expired, envelope.recalled, envelope.reminded.

Chaque livraison porte un en-tête X-VG-Signature: sha256=<hex>, un HMAC-SHA256 du corps brut de la requête, calculé avec la clé secrète de votre abonnement. Recalculez-le et comparez avant de traiter la requête. X-VG-Delivery-Id reprend le id du corps. Servez-vous-en pour écarter les doublons, car une même livraison peut arriver plus d’une fois.

SDK

L’API est simplement REST + JSON, donc tout client HTTP convient. Il n’existe pas de SDK client écrit à la main, mais /api/v1/openapi.json est une description OpenAPI 3.1 complète, dont la plupart des générateurs tireront un client typé pour votre langage. Si vous préférez que nous en maintenions un, écrivez-nous à info@vg-realestate.ca.

Limites de débit

Chaque jeton d’espace est limité à 600 requêtes par minute (et 600 par minute par adresse IP source), mesurées sur une période glissante de 60 secondes. Les envois de rappels ont une limite plus basse, 60 par minute. Une requête au-delà de la limite reçoit un 429 avec un en-tête Retry-After. Besoin d’une limite plus haute? Contactez-nous.

Limites

Jusqu’à 15 documents par dossier (50 par POST /envelopes/from-refs), 25 Mo et 50 pages par PDF, 50 destinataires et 500 placements de champs. Les téléversements vers POST /envelopes doivent être des PDF; les autres formats passent par le téléverseur Web, qui les convertit d’abord.

La création de dossiers est comptée deux fois. Elle s’impute à l’allocation mensuelle de votre forfait, qui répond 402 quota_exceeded une fois épuisée, et à une allocation d’API de 100 dossiers par mois avec Pro, 500 avec Équipe, qui répond 429 api_quota_exceeded. Les deux sont séparées à dessein : la seconde permet à un prix mensuel fixe de rester fixe pour les personnes qui envoient leurs documents à la main. Elle s’applique à POST /envelopes, POST /envelopes/from-refs et POST /templates/{id}/envelopes, et jamais à ce que vous envoyez depuis le tableau de bord. Les intégrations antérieures à cette allocation ne sont pas plafonnées, pas plus que le forfait Entreprise. Besoin de plus? Contactez-nous.