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.

    Читати