API и разработчики

Создавайте из тех же элементов, что и мы.

API REST от VG·Sign создаёт, отправляет и отслеживает комплекты с помощью токена пространства. Он входит в планы «Про», «Команда» и «Корпоративный», а полная справка есть на странице API.

На этой странице

Получите токен пространства

  1. Как владелец пространства откройте Настройки, Интеграции.
  2. В разделе Доступ к API нажмите Создать токен.
  3. Сразу скопируйте токен. Он начинается с 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. Показ во фрейме запрещён, пока мы не добавим адрес вашего сайта в список разрешённых, поэтому сначала запросите доступ. Подробности есть на странице Встраиваемый виджет.

Назад к справке

  • Подключите VG·Sign к своим инструментам.

    Публикуйте события комплектов в канале Slack или Microsoft Teams либо отправляйте подписанный JSON на любой адрес HTTPS, включая Zapier, Make и n8n. Всё это настраивается в разделе «Настройки», в подразделе «Интеграции».

    Читать
  • Подготовьте один раз, отправляйте всегда.

    Шаблон хранит документы комплекта, размещение полей и роли подписания. Введите имена и электронные адреса, чтобы создать из него новый комплект, или отправьте отдельный комплект для каждой строки файла CSV.

    Читать
  • Планы, счета и места.

    Бесплатный план включает 5 комплектов в месяц. «Про» предназначен для одного отправителя по фиксированной месячной цене. Цена плана «Команда» зависит от числа людей, от 2 до 10.

    Читать