Справочник по API ABSign REST: Руководство по конечным точкам v2, аутентификации и интеграции

Введение в API ABSign v2

ABSign REST API v2 — это официальный программный интерфейс для интеграции возможностей электронной подписи корпоративного уровня в ваши бизнес-системы, торговые платформы и рабочие процессы управления документами. API, построенный на принципах REST с полезной нагрузкой запросов и ответов JSON, легко подключается к любому технологическому стеку, способному выполнять HTTPS-вызовы — от приложений Python и Node.js до служб Java Spring Boot, систем PHP Laravel и приложений .NET Core. Базовая конечная точка для всех вызовов API версии 2: https://www.abroadsign.com/api/v2/, который заменяет устаревшую конечную точку версии 1 и обеспечивает повышенную безопасность, расширенный охват событий веб-перехватчиков и улучшенное ограничение скорости для крупномасштабных корпоративных интеграций.

Организации в более чем 180 странах используют API ABSign для автоматизации рабочих процессов подписания документов, охватывающих контракты на транспортно-экспедиторские услуги, аккредитивы торгового финансирования, таможенные декларации, многосторонние соглашения о цепочке поставок и документы о корпоративных закупках. В версии v2 представлена ​​встроенная поддержка операций с большими объемами документов, расширенное объединение шаблонов, привязка временных меток блокчейна и функции совместной работы в реальном времени, которые позволяют проводить одновременные церемонии с несколькими подписаниями из любого браузера или мобильного устройства, не требуя от участников установки специального программного обеспечения или создания учетных записей ABSign. Независимо от того, являетесь ли вы стартапом, создающим свой первый процесс адаптации клиентов, или предприятием, заменяющим всю инфраструктуру бумажных контрактов, API ABSign предоставляет строительные блоки для полностью автоматизированной, юридически соответствующей цифровой подписи в глобальном масштабе.

Настройка аутентификации и безопасности

Защита доступа к API имеет первостепенное значение при работе с юридически обязательными цифровыми подписями. ABSign API v2 использует аутентификацию на основе ключей API в сочетании с транспортным шифрованием TLS 1.3, гарантируя, что каждый запрос и ответ шифруются при передаче и невосприимчивы к перехвату или атакам «человек посередине». Все ключи API генерируются на панели управления ABSign в разделе «Настройки» с детальными областями разрешений, которые соответствуют принципу наименьших привилегий — каждая интеграция получает именно те разрешения, которые ей необходимы, не более того. Ключи никогда не передаются в URL-адресах, а только в заголовках HTTP, и ваши системы должны хранить их в переменных среды или на специальных платформах управления секретами, таких как AWS Secrets Manager, HashiCorp Vault или Azure Key Vault, а не встраивать их в репозитории исходного кода или файлы конфигурации, переданные в системы контроля версий.

• Заголовок токена носителя: Каждый запрос API должен включать Authorization: Bearer YOUR_API_KEY заголовок. Никогда не кодируйте ключи API в исходном коде приложения; используйте переменные среды или системы управления секретами для ввода учетных данных во время выполнения.
• Применение TLS 1.3: Все соединения API должны использовать TLS 1.3. Соединения, пытающиеся использовать более старые версии TLS, будут отклонены с ответом 400 Bad Request. Это гарантирует, что содержимое документа и данные подписи никогда не будут раскрыты по незашифрованным каналам.
• Области разрешений: Ключи API привязаны к конкретным операциям — document.read, document.write, templates.read, templates.write, Signers.manage, webhooks.admin и Organization.read. Назначайте только области, необходимые для каждого варианта использования интеграции, чтобы ограничить радиус взрыва в случае компрометации ключа.
• Политика ротации ключей: Внедрите автоматическую ротацию ключей по 90-дневному графику. Панель управления ABSign поддерживает ротацию ключей без простоев благодаря концепции первичных и вторичных ключей, что позволяет вам менять учетные данные, не нарушая рабочие процессы подписания в реальном времени.
• Белый список IP-адресов: Корпоративные учетные записи могут ограничить доступ к API определенными IP-адресами или диапазонами CIDR. Включите список разрешенных IP-адресов на странице настроек безопасности для интеграции между серверами, где вызывающие IP-адреса известны и стабильны.

“Внедрение TLS 1.3 и определения области действия ключей API свело результаты нашего аудита безопасности к нулю. API ABSign был разработан с учетом требований безопасности предприятия — он отображал каждую деталь процесса интеграции”.

— Руководитель отдела информационной безопасности, глобальная торговая фирма, занимающаяся сырьевыми товарами.

Справочник по конечным точкам основного API

API версии 2 организует функциональные возможности вокруг ресурсо-ориентированных конечных точек, которые естественным образом сопоставляются с объектами рабочего процесса цифровой подписи: документами, шаблонами, подписывающими лицами, подписями, веб-перехватчиками и организациями. Каждый ресурс поддерживает стандартные операции CRUD, а также действия, специфичные для ресурса, такие как отправка документов на подпись, напоминание ожидающим подписания или загрузка готовых пакетов документов со встроенными подписями и сертификатами криптографической целостности. В следующей таблице представлен полный справочник по группам конечных точек для быстрой разработки интеграции.

Группа конечных точек	Базовый путь	Ключевые операции	Общий случай использования
Документы	/documents	Создание, чтение, список, обновление, загрузка, архивирование, удаление	Инициировать подписание, получить заполненные документы
Шаблоны	/templates	Создание, чтение, обновление, удаление, клонирование, список	Стандартизированные процессы документооборота
Подписанты	/signers	Пригласить, повторно отправить приглашение, отменить, подтвердить личность	Управление подписывающими сторонами
Подписи	/signatures	Применить, проверить, проверить статус, получить контрольный журнал	Заполнение и проверка подписей
Вебхуки	/webhooks	Создать, Список, Удалить, Тестировать, Включить/Отключить	Уведомления о событиях в режиме реального времени
Организации	/organizations	Чтение, обновление, настройки, члены команды	Конфигурация администрирования и соответствия требованиям
Журналы аудита	/audit-logs	Список, фильтр, экспорт, загрузка PDF	Отчетность о соответствии и судебная экспертиза
Массовые операции	/bulk	Создать пакет, Статус, Отменить пакет	Обработка больших объемов документов

Шаблон интеграции жизненного цикла документа

Наиболее распространенный шаблон интеграции API следует за жизненным циклом документа от создания до сбора подписей и архивирования. Этот комплексный рабочий процесс демонстрирует, как ваши системы взаимодействуют с API ABSign на каждом этапе, обеспечивая полностью автоматизированные процессы подписания без ручного вмешательства или административных затрат. Понимание этого жизненного цикла необходимо для создания надежных интеграций, которые корректно обрабатывают сценарии сбоев и поддерживают согласованность данных в распределенных системах.

Шаг 1. Создание документа и заполнение шаблона

Начните с создания документа либо на основе предварительно настроенного шаблона, либо на основе необработанного содержимого HTML или PDF, отправленного непосредственно в API. При создании на основе шаблона передайте значения переменных шаблона в тексте запроса, чтобы настроить содержимое документа для каждого конкретного случая подписания, сохраняя при этом согласованность бренда и стандартизацию юридических положений. API немедленно отвечает идентификатором документа, который ваша система сохраняет для всех последующих операций с этим документом. Создание документов поддерживает пакетный режим, в котором вы можете отправлять до 500 документов за один вызов API для обработки очередей, которым необходимо инициировать десятки или сотни рабочих процессов подписи одновременно в периоды пиковой торговли.

• Использование POST /documents с template_id и template_data создать из шаблона или отправить content_html или content_pdf_base64 для сырого контента.
• Установите signing_sequence к sequential для заказанного многостороннего подписания или parallel когда все стороны могут подписать документ одновременно, чтобы минимизировать время ожидания.
• Указать expiry_days чтобы контролировать, как долго приглашение на подпись остается активным, прежде чем срок действия документа автоматически истечет и потребуется продление.
• Давать возможность block_download_until_completed чтобы предотвратить преждевременный доступ к документу, пока не завершена требуемая подпись.

Шаг 2. Настройка подписывающей стороны и отправка рабочего процесса

После создания документа добавьте необходимых подписывающих лиц, указав их адреса электронной почты, отображаемые имена и их положение в последовательности подписания. Для интеграций, требующих расширенной проверки личности, таких как транзакции торгового финансирования на крупные суммы или регулируемая импортно-экспортная документация, включите identity_verification_required флаг для обязательной проверки биометрических данных или государственного удостоверения личности перед принятием подписи. Отправьте документ всем подписывающим сторонам с помощью одного вызова API, и платформа ABSign автоматически сгенерирует приглашения по электронной почте в профессиональном формате с персонализированными ссылками на документы, уведомлениями об истечении срока действия и четкими инструкциями по подписанию на языке, предпочитаемом получателем.

• Добавьте подписантов через POST /documents/{document_id}/signers с адресом электронной почты, именем и ролью (signer, witness, или 抄送 для сс).
• Настроить reminder_schedule автоматически отправлять электронные письма с напоминаниями с интервалом в 24 и 72 часа подписывающим сторонам, которые еще не предприняли никаких действий.
• Набор redirect_url_after_signed чтобы направить подписывающих лиц на специальную страницу завершения в вашей системе после завершения подписания.
• Давать возможность signer_authentication требование проверки OTP по электронной почте или SMS в качестве дополнительного уровня подтверждения личности подписывающего лица.

Шаг 3. Завершение на основе веб-перехватчика и последующая обработка

Система веб-перехватчиков ABSign доставляет уведомления о событиях в режиме реального времени на настроенную конечную точку HTTPS всякий раз, когда подписывающая сторона предпринимает какие-либо действия или изменяется состояние жизненного цикла документа. Вместо многократного опроса API для проверки статуса документа (что расходует вашу квоту ограничения скорости и увеличивает задержку) настройте веб-перехватчики для получения push-уведомлений, которые автоматически запускают последующие процессы. После получения document.completed В этом случае ваша система получает готовый пакет документов, включая подписанный PDF-файл, криптографический хеш-сертификат, привязку временной метки блокчейна и полный документ контрольного журнала, который служит основным доказательством в юридических спорах или проверках соответствия.

---

Справочник по событиям веб-перехватчика и уведомлениям в реальном времени

Веб-перехватчики являются основой автоматизированных интеграционных архитектур. ABSign API v2 поддерживает комплексный охват событий на протяжении всего жизненного цикла документа, позволяя вашим системам немедленно реагировать на изменения состояния, а не полагаться на интервалы опроса, которые тратят квоту API и вносят ненужные задержки в ваши рабочие процессы. Каждая доставка веб-перехватчика включает в себя полезную нагрузку JSON с данными, специфичными для события, и заголовок подписи HMAC-SHA256, который ваша конечная точка должна проверить перед обработкой уведомления, чтобы предотвратить запуск поддельных событий несанкционированных действий в ваших системах.

Тип события	Условие триггера	Ключевые поля полезной нагрузки	Интеграционный ответ
document.created	Новый документ добавлен на платформу	document_id, название, создано_в, создано_кем	Зарегистрируйтесь во внутренней системе отслеживания
document.sent	Документ отправлен подписавшим сторонам	document_id, подписывающие[], expires_at, тема	Обновить статус информационной панели рабочего процесса
signer.viewed	Подписывающая сторона открывает ссылку на документ	document_id, Signer_id, просмотренный_at, ip_address	Записывать взаимодействие и запускать таймер
signer.completed	Подписавший передает свою подпись	document_id, Signer_id, Signed_at, Signature_hash	Проверить завершение, уведомить нижестоящих
document.completed	Все необходимые подписи получены.	document_id, Completed_at, Download_url, Audit_trail_url	Запустить следующий шаг рабочего процесса
document.expired	Срок подписания истек	document_id, expired_at, подписывающие_ожидающие[]	Инициировать продление или предупредить оперативную группу
document.declined	Подписавшаяся сторона явно отказывается подписывать	document_id, подписывающего_id, отклонено_at, причина	Операции оповещения и эскалация
document Voided	Документ отменен создателем	document_id, voided_by, voided_at, причина	Закрыть внутренние записи и уведомить

Ограничения скорости, квоты и оптимизация производительности

ABSign API v2 применяет ограничения скорости, чтобы обеспечить стабильность платформы и справедливое распределение ресурсов среди всех потребителей API. Учетные записи уровня Standard ограничены 1000 запросами в минуту на ключ API, тогда как учетные записи Enterprise получают повышенные лимиты, согласованные на основе документированных требований интеграции и ожидаемых объемов транзакций. Статус ограничения скорости передается в каждом ответе API через X-RateLimit-Remaining и X-RateLimit-Reset заголовки ответов, что позволяет вашей интеграции реализовать упреждающее регулирование, а не ждать, пока 429 ответов вызовут поведение отсрочки. Для пакетных операций большого объема, обрабатывающих тысячи документов, используйте специальный /bulk конечные точки, специально разработанные для массовой пропускной способности с более высокими поминутными квотами и сниженными накладными расходами на каждый документ.

• Монитор X-RateLimit-Remaining заголовок каждого ответа и приостанавливать запросы при приближении к нулю, чтобы избежать получения ответов 429 Too Many Requests, которые останавливают обработку окна сброса.
• Используйте Retry-After значение заголовка, чтобы дождаться точной продолжительности перед возобновлением запросов, а не реализовывать произвольные интервалы ожидания, которые могут быть слишком короткими или излишне длинными.
• Для массовой обработки документов предпочитайте POST /bulk конечные точки над отдельными POST /documents вызовы — массовые операции обеспечивают увеличение пропускной способности до 10 раз для больших объемов рабочих процессов.
• Внедрите экспоненциальную отсрочку с джиттером для всей логики повторов, чтобы обрабатывать временные ошибки на стороне сервера, не перегружая платформу во время периодов восстановления.
• Использование Conditional Requests с If-Modified-Since или ETag заголовки при получении статуса документа, чтобы избежать ненужной передачи данных и уменьшить задержку при проверке статуса.

“Мы обрабатываем более 50 000 грузовых документов в месяц через ABSign API. Конечная точка массовых операций в сочетании с правильной обработкой веб-перехватчиков означает, что весь наш рабочий процесс подписания выполняется с задержкой менее минуты – полностью автоматически после первоначального вызова API”.

— Ведущий инженер платформы, глобальная транспортно-экспедиторская сеть

Официальные пакеты SDK и быстрый старт

ABSign поддерживает официальные пакеты SDK для наиболее широко распространенных языков программирования и платформ, каждый из которых предоставляет структуры данных на родном языке, автоматическую логику повторов с экспоненциальной отсрочкой для временных сбоев, комплексные определения типов для безопасности во время компиляции и предварительно настроенные настройки HTTP-клиента, соответствующие требованиям безопасности API. Пакеты SDK имеют открытый исходный код и доступны на GitHub, где вклад сообщества в отношении дополнительных языков приветствуется и проверяется командой инженеров ABSign. Все официальные SDK разрабатываются синхронно с API, чтобы гарантировать, что сигнатуры и поведение методов SDK остаются согласованными с базовыми конечными точками REST.

• SDK Python: Установить через pip install abroadsign-api. Полная поддержка асинхронности/ожидания для современных приложений Python с помощниками автоматической интеграции для систем фоновых задач на основе Django, FastAPI и Celery. Включены полные подсказки типов и поддержка автозаполнения IDE.
• Node.js/TypeScript SDK: Установить через npm install abroadsign-api. Полностью типизированный пакет TypeScript с полными определениями типов для всех объектов запросов и ответов. Включает встроенную поддержку промежуточного программного обеспечения для маршрутов API Express.js, Next.js и бессерверных функций в AWS Lambda и Vercel.
• Java/Spring Boot SDK: Координаты Maven доступны на Maven Central. Совместимость со Spring Boot 2.x и 3.x, поддержка автоматической настройки и подробная документация Javadoc для корпоративных групп разработчиков Java.
• PHP SDK: PSR-совместимый пакет, совместимый с Laravel, Symfony и автономными приложениями PHP 8.1+. Включает поставщика услуг Laravel для плавной настройки внедрения зависимостей через контейнер служб Laravel.
• .NET/С# SDK: Совместимость с .NET Standard 2.0, поддерживающая .NET Framework, .NET Core и .NET 5+ в Windows, Linux и macOS. Включает интеграцию внедрения зависимостей ASP.NET Core с шаблоном HttpClientFactory.

---

Начало работы: ваша первая интеграция API

Начните интеграцию с доступа к изолированной среде API ABSign, которая предоставляет полнофункциональное зеркало API с изолированными тестовыми данными, которые не влияют на хранилища производственных документов и не учитываются в производственных квотах. Создайте свои учетные данные API песочницы на панели мониторинга в разделе «Настройки» и немедленно начните выполнять вызовы API, чтобы изучить создание документов, настройку подписывающей стороны и доставку веб-перехватчика в безопасной среде. «Песочница» автоматически имитирует церемонии подписания, поэтому вы можете тестировать комплексные рабочие процессы, не дожидаясь, пока реальные подписывающие стороны предпримут какие-либо действия во время циклов разработки и контроля качества. Наш интерактивный портал документации API предоставляет действующий обозреватель API, с помощью которого вы можете выполнять запросы непосредственно в браузере, проверять полезные данные запросов и ответов, а также генерировать готовые фрагменты кода для любой конечной точки на любом из поддерживаемых языков SDK.

Чтобы узнать о расширенных шаблонах интеграции, включая пакетную обработку больших объемов, многопользовательские реализации «white-label» и настраиваемые архитектуры надежности веб-перехватчиков, изучите наш Руководство по автоматизации документооборота который охватывает настройку производительности, стратегии обработки ошибок и лучшие практики корпоративного развертывания. Наша команда инженеров по интеграции также предлагает бесплатные сеансы анализа технической архитектуры для корпоративных клиентов, чтобы проверить ваш проект интеграции, прежде чем переходить к объемам производственного трафика.

Готовы построить свою интеграцию? Посетите портал документации API полные ссылки на конечные точки, загрузки SDK и примеры рабочего кода. По вопросам о требованиях к корпоративным API, индивидуальной архитектуре интеграции или масштабировании производства обращайтесь свяжитесь с нашей командой технической интеграции запланировать бесплатную сессию обзора архитектуры с одним из наших старших инженеров API.