eFix API v2 v2.1.0

Ключ выпускается в кабинете: «API и интеграции». Доступ к API включён в тарифах «Профессиональный» и «Корпоративный».

Право ключа никогда не шире текущей роли владельца в организации: понизили роль — ключ сразу теряет лишнее. После ротации прежний ключ работает ещё 24 часа; отзыв действует сразу. Протоколы, запущенные ключом организации, принадлежат организации; фиксация списывается с владельца ключа. Каждый вызов записывается в журнал — он виден в кабинете и даёт учёт использования.

Запустить фиксацию страницы

Право ключа: protocol.create. Списывает одну фиксацию (подписка → бесплатные → баланс) и ставит задачу; протокол готов через 1–4 минуты. Состояние — по status_url или вебхуком protocol.completed / protocol.failed.

curl -X POST https://efix.kz/api/v2/capture \
  -H 'X-API-Key: efk_…' \
  -H 'Content-Type: application/json' \
  -d '{"url": "https://netology.ru/"}'

Состояние фиксации

Право ключа: protocol.view. Видны свои протоколы и протоколы организации, если роль владельца ключа это позволяет.

curl https://efix.kz/api/v2/capture/EF-20261012-A1B2C3D4 -H 'X-API-Key: efk_…'

Скачать PDF-протокол

Право ключа: protocol.view. Только готовый (completed) протокол.

curl -o protocol.pdf https://efix.kz/api/v2/capture/EF-20261012-A1B2C3D4/pdf -H 'X-API-Key: efk_…'

Скачать снимок страницы

Право ключа: protocol.view. Только готовый протокол.

curl -o page.png https://efix.kz/api/v2/capture/EF-20261012-A1B2C3D4/screenshot -H 'X-API-Key: efk_…'

Скачать видеозапись

Право ключа: protocol.view. Есть, только если фиксация запускалась с include_video и тариф включает видео.

curl -o video.mp4 https://efix.kz/api/v2/capture/EF-20261012-A1B2C3D4/video -H 'X-API-Key: efk_…'

Тарифные планы (без ключа)

curl https://efix.kz/api/v2/plans

Список протоколов

Право ключа: protocol.view. Свои протоколы и протоколы организации по роли; новые сверху.

curl 'https://efix.kz/api/v2/protocols?status=completed&per_page=50' -H 'X-API-Key: efk_…'

eFix Метка: метка времени на файл или хеш

Право ключа: protocol.create. Списывает одну фиксацию. Сервер получает квитанцию RFC 3161 службы НУЦ РК на SHA-256 объекта, OpenTimestamps и запись в реестре eFix (позиция печатается в протоколе), затем PDF «Протокол метки времени» с ЭЦП. Метка удостоверяет существование данных с этим хешем не позднее момента квитанции — не содержание и не авторство. Повтор того же объекта за 15 минут — прежняя метка (200, duplicate).

curl -X POST https://efix.kz/api/v2/stamp \
  -H 'X-API-Key: efk_…' \
  -H 'Content-Type: application/json' \
  -d '{"sha256": "<64 hex>", "filename": "договор.pdf"}'
# файл: curl -X POST https://efix.kz/api/v2/stamp -H 'X-API-Key: efk_…' -F file=@договор.pdf

Состояние метки

Право ключа: protocol.view. PDF — /capture/{protocol_id}/pdf.

curl https://efix.kz/api/v2/stamp/EF-20261015-A1B2C3D4 -H 'X-API-Key: efk_…'

Учёт вызовов и фиксаций через API

Право ключа: usage.view. Ключ организации (или ключ участника с ролью «Проверяющий»/«Администратор») видит учёт всей организации, остальные — свой. Период по умолчанию — текущий месяц (UTC). Учёт справочный: оплата по использованию не списывается.

curl 'https://efix.kz/api/v2/usage?from=2026-10-01&to=2026-10-31' -H 'X-API-Key: efk_…'

Владелец ключа, тариф и сам ключ

Без отдельного права: любой действующий ключ.

curl https://efix.kz/api/v2/user -H 'X-API-Key: efk_…'

Проверка подлинности протокола (без ключа)

То же, что страница проверки по QR-коду, в машинном виде.

curl https://efix.kz/api/v2/verify/EF-20261012-A1B2C3D4

Включаются администратором eFix. Пока вебхуки выключены, подписку завести нельзя, а состояние протокола опрашивается по status_url. Подписка заводится в кабинете («API и интеграции»): адрес https://, события и секрет подписи (показывается один раз). У организации подписки общие, их ведёт администратор организации.

Запрос

POST /ваш/адрес HTTP/1.1
Content-Type: application/json; charset=utf-8
User-Agent: eFix-Webhooks/1.0
X-EFix-Event: protocol.completed
X-EFix-Delivery: 3f0c…
X-EFix-Signature: t=1791800000,v1=5d41402abc4b2a76b9719d911017c592…

{"id": "3f0c…", "event": "protocol.completed", "created_at": "2026-10-12T09:30:00Z",
 "data": {"protocol_id": "EF-20261012-A1B2C3D4", "status": "completed",
          "url": "https://netology.ru/", "domain": "netology.ru", "sha256": "…",
          "links": {"status": "https://efix.kz/api/v2/capture/EF-20261012-A1B2C3D4",
                    "verify": "…/verify/EF-20261012-A1B2C3D4"}}}

Проверка подписи

Подпись — HMAC-SHA256 секретом подписки от строки <t>.<тело запроса как пришло, байт в байт>. Отклоняйте запрос, если подпись не совпала или t старше 5 минут; повторную доставку того же события узнавайте по id.

# Python
import hashlib, hmac, time

def подпись_верна(секрет: str, тело: bytes, заголовок: str) -> bool:
    части = dict(ч.split("=", 1) for ч in заголовок.split(","))
    t = int(части["t"])
    if abs(time.time() - t) > 300:
        return False
    ожидаемо = hmac.new(секрет.encode(), f"{t}.".encode() + тело, hashlib.sha256).hexdigest()
    return hmac.compare_digest(ожидаемо, части.get("v1", ""))

// Node.js
const crypto = require("crypto");
function signatureOk(secret, rawBody, header) {
  const p = Object.fromEntries(header.split(",").map(x => x.split("=")));
  if (Math.abs(Date.now() / 1000 - Number(p.t)) > 300) return false;
  const want = crypto.createHmac("sha256", secret).update(`${p.t}.`).update(rawBody).digest("hex");
  return want.length === (p.v1 || "").length &&
         crypto.timingSafeEqual(Buffer.from(want), Buffer.from(p.v1));
}

Доставка и повторы

Ответ 2xx в течение 10 секунд — доставлено. Иначе повтор через 1 мин, 5 мин, 30 мин, 2 ч и 6 ч (всего 6 попыток), затем «не доставлено»; журнал доставок виден в кабинете. Редиректы не выполняются. После 10 неудач подряд подписка выключается — включите её снова в кабинете.

Какие адреса принимаются

Только https:// на портах 443 и 8443, без логина и пароля в адресе. Имя должно вести только на публичные адреса: локальные (127.0.0.0/8, ::1), частные (10/8, 172.16/12, 192.168/16, fc00::/7), link-local и служба метаданных (169.254.0.0/16, fe80::/10), служебные и multicast — запрещены, в том числе внутри IPv6 (::ffff:…, 6to4, NAT64). Адрес проверяется при заведении подписки и перед каждой доставкой, и соединение открывается на проверенный адрес: смена DNS между проверкой и запросом не помогает.

Ошибка — JSON {"error": "код", "message": "пояснение"}; код стабилен, текст может меняться. Не больше 60 запросов в минуту на ключ: заголовки X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset; при превышении — 429 и Retry-After.