Короткий огляд
Автентифікація відбувається за токеном простору, який ви створюєте в налаштуваннях. Повне надсилання потребує щонайбільше трьох викликів: створити комплект із документами, одержувачами й розміщенням полів, надіслати його, а потім прочитати стан (або дочекатися вебхука). Для цього нікому не треба відкривати наш редактор.
Базова адреса
https://vg-sign.com/api/v1Раніше базовий шлях був /api/v1/internal. Цей префікс досі відповідає і відповідатиме надалі, тому нічого з уже побудованого змінювати не треба. Він ніколи не був точним: кожна кінцева точка нижче приймає звичайний токен простору.
Машиночитний опис усього, що є на цій сторінці, розміщено за адресою /api/v1/openapi.json (OpenAPI 3.1). Передайте його генератору клієнтів або імпортуйте в Postman чи Insomnia.
Автентифікація
Створіть токен API простору в розділі Налаштування, Інтеграції, а потім викликайте API із заголовком Authorization: Bearer vgs_live_…. Токени обмежені вашим простором, зберігаються в гешованому вигляді, і їх можна відкликати будь-коли.
API потребує плану «Про», «Команда» або «Корпоративний». Токен із простору на безкоштовному плані отримує 403 plan_required, доки простір не змінить план.
Вхід агента з CRM є окремим, вищим правом. Одноразова передача єдиного входу на /oauth/authorize, заголовок On-Behalf-Of і відкликання прав працюють лише для простору, який ми ввімкнули як службовий обліковий запис CRM, і лише для людей, які вже є в цьому просторі. Звичайний токен простору отримує на цих трьох 403 not_a_service_account; усе інше на цій сторінці працює з будь-яким токеном. Щоб увімкнути простір, напишіть нам на info@vg-realestate.ca.
Основні кінцеві точки
POST /envelopes: створює комплект з одного або кількох завантажених PDF (multipart/form-data: частина JSONmetadataі по одній частиніfilesна документ). Одержувачі, порядок підписання і, за бажанням, розміщення полів передаються в тому самому запиті. Повертає201з ідентифікатором комплекту,status: "draft"іfields_required, яке дорівнюєfalse, якщо ви вже розмістили поля самі.POST /envelopes/:id/send: надсилає чернетку на підпис. Надсилає листи підписантам, оновлює їхні посилання для підписання і записує надсилання в журнал аудиту.GET /envelopes: перелік комплектів простору, спочатку найновіші. Фільтри:status,external_ref; сторінки:limit(щонайбільше 100),offset.GET /envelopes/:id: читає стан комплекту, поступ одержувачів і журнал аудиту.GET /envelopes/:id/final: отримує підписані PDF зі вбудованим вмістом.GET /envelopes/:id/attachments/:attachmentId: отримати посилання на 60 секунд для завантаження файлу, який додав підписант.GET /envelopes/:idпоказує список цих файлів. Вебхуки ніколи не містять файлу чи посилання.GET /envelopes/:id/certificate: отримує сертифікат завершення.POST /envelopes/:id/remind: повторно надсилає сповіщення про підписання одержувачам, яких очікують.POST /envelopes/:id/void: скасовує комплект, що вже в роботі.POST /envelopes/from-refs: створює комплект за посиланнями на документи, уже завантажені через/uploads/init.POST /webhooks·GET /webhooks·DELETE /webhooks/:id: керування підписками на події життєвого циклу.
Одержувачі
GET /envelopes/:id/recipients повертає людей у комплекті та стан кожної з них. У чернетці POST /envelopes/:id/recipients додає людину, PATCH /envelopes/:id/recipients/:rid змінює її дані (ім’я, електронна адреса, телефон, позначка, підписант чи отримує копію, місце в порядку підписання), а DELETE вилучає її. Вилучення відхиляється, доки за цією людиною закріплені розміщені поля, бо разом з нею зникли б і вони; передайте ?force=true, щоб погодитися на це.
Після надсилання той самий PATCH виправляє помилку в адресі: лише ім’я та електронну адресу і лише для людини, яка ще не підписала й не відхилила. Зміна адреси скасовує посилання, що пішло на хибну адресу, і створює нове, яке надходить на виправлену адресу, коли настає черга цієї людини. Кінцевий термін зберігається, а не починається заново, і заміна записується в журнал аудиту. POST /envelopes/:id/recipients/:rid/remind нагадує одній названій людині, тоді як нагадування на рівні комплекту надходить тому, чийого підпису зараз чекають.
Шаблони
Шаблон містить документи, розташування полів і ролі для підписання, тому постійний набір потребує одного виклику, а не завантаження, розташування полів і надсилання окремо. GET /templates показує їх перелік; GET /templates/:id повертає ролі, які треба заповнити; POST /templates/:id/envelopes прив’язує реальну людину до кожної ролі та створює комплект. Додайте "send": true, щоб надіслати його тим самим запитом.
POST /templates/8f3c…/envelopes
{
"assignments": [
{ "signing_order": 1, "full_name": "Dana Reyes", "email": "dana@example.com" }
],
"external_ref": "deal-4417",
"send": true
}Розміщення полів
Кожен запис у fields[] це одна рамка на одній сторінці, призначена одному одержувачу. Координати є частками сторінки (від 0 до 1, від верхнього лівого кута), тож вони підходять для будь-якого розміру сторінки. document називає файл із documents[], і його можна пропустити, якщо в комплекті один документ на підпис.
{
"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
}Типи: signature, initials, full_name, text, date, time, checkbox, strikethrough, multiline, dropdown, radio, attachment. Випадному списку потрібен options (від 2 до 50), можна додати default_option. Кожен перемикач це окремий запис із group та option_label, можна додати group_label; записи з однаковим group утворюють одне запитання з 2 до 10 варіантів для одного підписанта в одному документі. Текстові поля також приймають placeholder, max_length і validation (email · number · phone); дати приймають date_format, час приймає time_format і time_mode, прапорці приймають checkbox_style. Відхилене розміщення повертається з кодом 400 і назвою запису, наприклад fields[2].page is 9 but "contract.pdf" has 4 page(s).
Якщо пропустити fields[], відповідь міститиме fields_required: true і editor_url: комплект чекає як чернетка, доки хтось не розмістить поля в редакторі VG·Sign. Кожен підписант повинен мати щонайменше одне обов’язкове поле, інакше надсилання буде відхилено.
Події вебхуків
Кожна зміна стану надсилає вебхук із підписаним вмістом. Події, на які інтеграція зазвичай підписується: envelope.created, envelope.sent, envelope.opened, envelope.document_signed, envelope.all_signed, envelope.completed, envelope.declined, envelope.voided, envelope.expired, envelope.recalled, envelope.reminded.
Кожна доставка має заголовок X-VG-Signature: sha256=<hex>, тобто HMAC-SHA256 необробленого тіла запиту, обчислений із секретним ключем вашої підписки. Обчисліть його знову й порівняйте перед обробкою. X-VG-Delivery-Id повторює id із тіла. За ним відсіюйте повтори, бо та сама доставка може надійти кілька разів.
Бібліотеки
API це звичайні REST і JSON, тому підійде будь-який клієнт HTTP. Написаного вручну клієнтського SDK немає, але /api/v1/openapi.json є повним описом OpenAPI 3.1, з якого більшість генераторів створить типізований клієнт вашою мовою програмування. Якщо вам потрібен клієнт, який підтримуємо ми, напишіть на info@vg-realestate.ca.
Обмеження частоти
Кожен токен простору обмежено 600 запитами на хвилину (і 600 на хвилину з однієї IP-адреси), рахунок ведеться за ковзне вікно в 60 секунд. Для надсилання нагадувань межа нижча, 60 на хвилину. Запит понад межу отримує 429 із заголовком Retry-After. Потрібна вища межа? Зв’яжіться з нами.
Обмеження
До 15 документів у комплекті (50 через POST /envelopes/from-refs), 25 МБ і 50 сторінок на PDF, 50 одержувачів і 500 розміщень полів. Файли для POST /envelopes мають бути PDF; інші формати проходять через вебзавантажувач, який спочатку їх перетворює.
Створення комплектів рахується двічі. Воно зараховується до місячного ліміту вашого плану, який після вичерпання відповідає 402 quota_exceeded, і до ліміту API у 100 комплектів на місяць на плані «Про» та 500 на плані «Команда», який відповідає 429 api_quota_exceeded. Вони розділені навмисно: другий існує для того, щоб фіксована місячна ціна залишалася фіксованою для тих, хто надсилає документи вручну. Він діє на POST /envelopes, POST /envelopes/from-refs і POST /templates/{id}/envelopes і ніколи не діє на те, що ви надсилаєте з панелі. Інтеграції, старші за цей ліміт, не обмежені, як і план «Корпоративний». Потрібно більше? Зв’яжіться з нами.