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