ProofSnap ProofSnap

Документация API ProofSnap

REST API ProofSnap открывает любой URL в браузере на серверах ProofSnap и выдаёт опечатанный пакет доказательств: скриншот, HTML, метаданные, PDF-отчёт и манифест с хешами SHA-256. Манифест подписывается ключом RSA-4096, а его хеш отправляется в OpenTimestamps для привязки к Bitcoin. Базовый URL: https://api.getproofsnap.com/v1. Аутентификация: ключ API в виде Bearer-токена. Обновлено 24 октября 2026 г.

В примерах ниже базовый URL берётся из переменной окружения: export PROOFSNAP_API_BASE=https://api.getproofsnap.com/v1

Начало работы

  1. 1

    Создайте ключ API

    Войдите в панель, откройте раздел «Разработчикам», затем «Ключи API» и нажмите «+ Новый ключ». Ключ показывается только один раз, поэтому сразу сохраните его в надёжном месте. Ключи начинаются с ps_live_ или ps_test_. Открываете панель впервые? Руководство «Первые шаги в ProofSnap Dashboard» проведёт вас через регистрацию, выбор тарифа и первый снимок. Подробнее в руководствах по панели.

  2. 2

    Сделайте первый снимок

    Передайте ключ как Bearer-токен. API сразу отвечает кодом 202 и возвращает capture_id и status: "processing".

    curl -X POST "$PROOFSNAP_API_BASE/captures" \
  -H "Authorization: Bearer ps_live_..." \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'
  3. 3

    Получите результат

    Опрашивайте GET /captures/{capture_id}, пока status не примет значение completed или failed. Готовый снимок содержит package_url (предподписанную ссылку на ZIP-файл, действующую не более 24 часов) и manifest_hash. Новую ссылку можно получить, повторно запросив данные снимка. Вместо опроса можно указать в options.webhook_url эндпоинт HTTPS, который получит подписанное HMAC-SHA256 событие capture.completed или capture.failed.

    curl "$PROOFSNAP_API_BASE/captures/cap_..." \
  -H "Authorization: Bearer ps_live_..."
  4. 4

    Проверьте пакет

    POST /captures/{capture_id}/verify заново сверяет каждый указанный хеш SHA-256 с сохранёнными файлами, проверяет подпись RSA-4096 манифеста и отвечает match, modified или invalid. Кроме того, любой может офлайн запустить скрипты из папки verification/ пакета или найти хеш SHA-256 файла manifest.json в публичном реестре выпущенных пакетов через GET /ledger/{hash}. Ни для того, ни для другого ключ API не нужен.

    curl -X POST "$PROOFSNAP_API_BASE/captures/cap_.../verify" \
  -H "Authorization: Bearer ps_live_..."

Аутентификация

Передавайте ключ API (API key) в заголовке Authorization: Bearer ps_live_.... Ключи начинаются с ps_live_ или ps_test_. Рабочий ключ создаёт платные снимки, тестовый ключ создаёт полные пакеты с водяным знаком, за которые вы не платите. Если к аккаунту не подключена оплата, рабочий ключ работает как тестовый. Если ключ не передан, API отвечает 401 MISSING_API_KEY, при неизвестном или отозванном ключе 401 INVALID_API_KEY. Ключи тарифа Website Archive доступны только для чтения (403 PLAN_API_READ_ONLY). Три маршрута работают без ключа: GET /health, GET /ledger/{hash} и GET /matter-verify.

Новый аккаунт начинает работу в песочнице (sandbox) с 50 бесплатными тестовыми снимками. Тестовое использование ограничено 200 единицами на аккаунт в сутки по UTC (429 TEST_MODE_DAILY_LIMIT); на скриншоте и в PDF стоит водяной знак на языке снимка (options.language): в русскоязычном снимке «TEST - НЕ ДЛЯ ЮРИДИЧЕСКОГО ИСПОЛЬЗОВАНИЯ», без указанного языка «TEST - NOT FOR LEGAL USE»; для include_eidas нужен рабочий ключ (403 EIDAS_REQUIRES_LIVE_KEY).

Вебхуки

Укажите options.webhook_url в отдельном запросе или создайте подписки на вебхуки для всего аккаунта через POST /webhook-subscriptions. Вебхуки (webhooks) соответствуют спецификации Standard Webhooks и содержат заголовки webhook-id, webhook-timestamp и webhook-signature (v1,, за которым следует HMAC-SHA256 от идентификатора, метки времени и тела, вычисленный с помощью секрета whsec_). Типы событий: capture.completed, capture.failed, capture.anchor_confirmed, certify.completed, certify.failed, redaction.completed, redaction.failed, monitor.change_detected и schedule.paused. События capture.anchor_confirmed и schedule.paused доставляются только подпискам для всего аккаунта. Кроме того, каждое событие доступно 30 дней через GET /events. Время ожидания одной попытки доставки составляет 10 секунд, неудачные попытки повторяются через 5 минут, 30 минут, 2 часа, 8 часов и 24 часа. В течение 24 часов после создания нового секрета вебхуки подписываются и старым, и новым секретом.

Вебхуки на webhook_url из запроса подписываются секретом того ключа API, с которым был отправлен запрос. Этот секрет вебхука показывается только один раз, при создании ключа в разделе «Разработчикам» панели. У подписки на вебхуки свой секрет, который возвращается только при её создании. Проверяйте подпись по необработанному телу запроса до его разбора. Отклоняйте любой вебхук, у которого webhook-timestamp отличается от времени вашего сервера более чем на 5 минут. Обрабатывайте каждый webhook-id только один раз. Любая библиотека Standard Webhooks делает это за вас.

Лимиты и ошибки

Платные запросы (POST /captures, /captures/batch, /compare, /captures/{capture_id}/redact и /certify-hash, а также запросы на проверку, юридические удержания, задания экспорта и импорт) ограничиваются для каждого аккаунта в фиксированных окнах по 60 секунд; все ключи API аккаунта и его сеанс в панели делят одно окно. Пакетный запрос или заверение нескольких хешей расходует по одной единице на каждый URL или хеш. Единиц на окно: sandbox 10, Developer 60, Startup 120, Growth 300, Legal Solo 60, Legal Company 120, Website Archive 60, Archive only 30. Ответы этих маршрутов содержат заголовки RateLimit-Policy и RateLimit, а также устаревшие заголовки X-RateLimit-*, а ответ 429 дополнительно содержит Retry-After.

Рабочие снимки засчитываются в месячную квоту тарифа (402 QUOTA_EXCEEDED), а пока платёж по тарифу просрочен, API отвечает на запросы аккаунта кодом 402 PAYMENT_REQUIRED. Число снимков, которые аккаунт может обрабатывать одновременно, ограничено (429 CONCURRENT_CAPTURE_LIMIT). Если вы передаёте заголовок Idempotency-Key, повторный запрос в течение 24 часов вернёт исходный результат с Idempotent-Replay: true вместо второго снимка. Ошибки возвращаются как объект JSON с полями error.code, error.message и при необходимости error.details. Обращаясь в поддержку, укажите значение заголовка ответа X-Request-ID. Полный список кодов приведён в документации ниже.

Краткий обзор эндпоинтов

  • Снимки: POST /captures, POST /captures/batch (от 2 до 50 URL), GET /captures, GET /captures/hosts, GET /captures/{capture_id}, PATCH и DELETE /captures/{capture_id}, POST /captures/{capture_id}/verify
  • Зачернение, сравнение и заверение: POST /captures/{capture_id}/redact, POST /compare, POST /certify-hash (до 100 хешей)
  • Автоматизация: /scheduled-captures (снимки по расписанию с историей запусков /runs), /webhook-subscriptions, GET /webhook-events/{capture_id}, GET /events, GET /captures/events
  • Юридические функции: /matters (дела: опечатывание, экспорт, публичная ссылка для проверки), POST /legal-holds (юридические удержания), /imports, /captures/export-jobs
  • Аккаунт и публичные маршруты: GET /whoami, GET /health, GET /ledger/{hash}, GET /matter-verify

Полная документация

Все эндпоинты (endpoints) с параметрами, ответами и схемами, сгенерированные из спецификации OpenAPI 3. Спецификацию можно скачать как openapi.json (на английском, для генераторов кода) или openapi-ru.json (описания на русском). Чтобы попробовать эндпоинт без написания кода, сделайте форк коллекции API ProofSnap в Postman. Официального SDK нет: сгенерируйте клиент любым генератором OpenAPI 3 и проверяйте вебхуки библиотекой Standard Webhooks.