Краткий обзор
Аутентификация происходит по токену пространства, который вы создаёте в настройках. Полная отправка требует не больше трёх вызовов: создать комплект с документами, получателями и размещением полей, отправить его, а затем прочитать состояние (или дождаться вебхука). Для этого никому не нужно открывать наш редактор.
Базовый адрес
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 и никогда не действует на то, что вы отправляете из панели. Интеграции, появившиеся раньше этого лимита, не ограничены, как и план «Корпоративный». Нужно больше? Свяжитесь с нами.