Отримайте токен простору
- Як власник простору відкрийте Налаштування, Інтеграції.
- У розділі Доступ до 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. Показ у фреймі заборонено, доки ми не додамо адресу вашого сайту до списку дозволених, тому спершу запросіть доступ. Подробиці є на сторінці Вбудований віджет.