API

Створено для інтеграції.

REST і JSON через HTTPS, автентифікація токеном кожного простору, вебхуки для кожної зміни стану. Це шар підписання під вашим продуктом, а не окреме місце призначення.

На цій сторінці

Короткий огляд

Автентифікація відбувається за токеном простору, який ви створюєте в налаштуваннях. Повне надсилання потребує щонайбільше трьох викликів: створити комплект із документами, одержувачами й розміщенням полів, надіслати його, а потім прочитати стан (або дочекатися вебхука). Для цього нікому не треба відкривати наш редактор.

Базова адреса

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: частина JSON metadata і по одній частині 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 і ніколи не діє на те, що ви надсилаєте з панелі. Інтеграції, старші за цей ліміт, не обмежені, як і план «Корпоративний». Потрібно більше? Зв’яжіться з нами.