Получите токен пространства
- Как владелец пространства откройте Настройки, Интеграции.
- В разделе Доступ к API нажмите Создать токен.
- Сразу скопируйте токен. Он начинается с
vgs_live_и показывается один раз, потому что мы храним только его отпечаток.
У пространства один токен. Заменить токен заменяет его, и старый сразу перестаёт действовать. Отозвать удаляет его. На бесплатном плане вместо кнопки видно «API входит в планы «Про», «Команда» и «Корпоративный».» Если платное пространство переходит на бесплатный план, токен приостанавливается, а вызовы получают ответ 403 plan_required, пока вы снова не перейдёте на платный план.
Ваш первый запрос
Отправляйте токен в заголовке Authorization. Этот вызов показывает ваши комплекты, начиная с самых новых:
curl https://vg-sign.com/api/v1/envelopes \
-H "Authorization: Bearer vgs_live_…"Ответ содержит массив envelopes с total, limit, offset и has_more. Фильтруйте с помощью ?status=completed или собственного external_ref. limit доходит до 100.
Каждый токен может делать 600 запросов в минуту. Сверх этого вы получите 429 с заголовком Retry-After. Каждая конечная точка описана в OpenAPI 3.1 по адресу /api/v1/openapi.json, и большинство генераторов клиентов могут его прочитать.
Размещайте поля через API
POST /api/v1/envelopes принимает multipart/form-data: часть metadata с JSON и по одной части files на каждый PDF. Положите получателей и массив fields в этот JSON. Каждое поле является одним прямоугольником на одной странице для одного получателя:
{
"recipient_email": "client@example.com",
"document": "contract.pdf",
"type": "signature",
"page": 1,
"x": 0.12, "y": 0.60,
"width": 0.30, "height": 0.07
}- Координаты являются долями страницы, от 0 до 1, отсчитываемыми от левого верхнего угла.
documentявляется именем файла изdocuments. Не указывайте его, если документ на подпись только один.typeможет бытьsignature,initials,full_name,text,date,time,checkbox,strikethrough,multiline,dropdown,radioилиattachment.requiredпо умолчаниюtrue, и каждому подписанту нужно хотя бы одно обязательное поле.- Раскрывающемуся списку нужен
options(от 2 до 50 вариантов), можно добавитьdefault_option. Каждый переключатель это отдельная запись сgroupиoption_label; записи с однимgroupобразуют один вопрос из 2 до 10 вариантов для одного подписанта в одном документе.
Ответ имеет код 201 с идентификатором комплекта и fields_required: false. Отправьте его с помощью POST /api/v1/envelopes/{id}/send. Без полей вы получите fields_required: true и editor_url, чтобы разместить их вручную.
Через API файлы должны быть PDF до 25 МБ и 50 страниц, а комплект принимает до 15 документов (50 через from-refs), 50 получателей и 500 полей. Комплекты, созданные через API, также засчитываются в лимит 100 в месяц на плане «Про» и 500 на плане «Команда», без ограничения на плане «Корпоративный». Комплекты, отправленные из панели, в него никогда не засчитываются.
Вебхуки и MCP
Чтобы узнавать об изменениях без постоянных запросов, подпишитесь на вебхуки в разделе «Настройки», «Интеграции» или через API с помощью POST /api/v1/webhooks. Статья Интеграции объясняет подпись, а страница Вебхуки показывает содержимое доставки.
Сервер MCP позволяет Claude Code, Claude Desktop и Cursor работать с комплектами через тот же API и тот же токен. Это один файл, server.mjs, который запускается через Node и читает токен из VG_SIGN_API_TOKEN. Скачайте его и проверьте по опубликованной контрольной сумме, а не копируйте вручную:
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"
}
}
}
}Он может показывать и читать комплекты и шаблоны, создавать комплект из шаблона, отправлять, напоминать и отменять, а также скачивать подписанный PDF и сертификат. Загрузить новый PDF он не может: сделайте это в приложении или через API. Отправка, напоминание, отмена и создание с отправкой работают с настоящими комплектами и пишут настоящим людям. Отмена является тем, что отменяет отправку, а саму отмену другой вызов отменить не может.
Токенов с ограниченными правами нет, поэтому помощник может делать всё, что может токен. Создайте токен в отдельном пространстве, если хотите ограничить его доступ. Замена токена (Настройки, Интеграции) действует сразу и ломает все другие интеграции со старым токеном, поэтому заменяйте его всякий раз, когда он мог попасть к посторонним.
Чтобы встроить подписание в собственный продукт, встраиваемый виджет (бета-версия) размещает подписанта в iframe с помощью одного тега скрипта и сообщает вашей странице о подписании и отказе через postMessage. Показ во фрейме запрещён, пока мы не добавим адрес вашего сайта в список разрешённых, поэтому сначала запросите доступ. Подробности есть на странице Встраиваемый виджет.