Recoverable EOC · EOC service 0.27.0

Public API для проверяемых объектов

Эта страница описывает интеграционный путь от загрузки EOC-объекта до job, object, revision, event и webhook delivery.

Base URL · https://api.recoverable.ru/v1Auth · X-EOC-API-Key или Authorization: BearerNode.js · ≥ 18

Public API v1 · Route index

Канонические маршруты

POST /v1/integration/ingestGET /v1/integration/jobs/:jobIdGET /v1/integration/objects/:objectIdGET /v1/integration/objects/:objectId/revisions/:revisionGET /v1/integration/eventsPOST /v1/integration/reverifyGET /v1/integration/webhooksGET /v1/integration/webhook-deliveries

Эти 8 method/path operations — весь публичный Integration API v1; создание и удаление webhook, target URL и секреты намеренно не публикуются.

01 · Install

Подготовленный SDK и CLI 0.7.1

SDK предназначен для типизированной интеграции, CLI — для локальной проверки и командных сценариев. Релиз 0.7.1 подготовлен; публикация в npm этим документом не подтверждается.

npm install @recoverable-eoc/eoc-sdk@0.7.1 @recoverable-eoc/eoc-cli@0.7.1
./node_modules/.bin/recoverable --help

SDK на npm ↗ · CLI на npm ↗ · Организация recoverable-eoc ↗

02 · Authentication

API key и граница доступа

Передайте ровно один credential в заголовке: X-EOC-API-Key или Authorization: Bearer <OIDC JWT>. EOC остаётся источником истины для principal, scopes, tenant и project context. В кабинете app.recoverable.ru/account доступен вход по email OTP; проект и API-ключ с нужными scopes создаются самостоятельно. Не помещайте ключ в исходный код, README, frontend bundle или журналы CI.

export EOC_API_KEY='eoc_live_...'
curl https://api.recoverable.ru/v1/adapters \
  -H "X-EOC-API-Key: $EOC_API_KEY"

Для записывающих операций используйте уникальный Idempotency-Key. Повтор идентичного запроса воспроизводит сохранённый результат, другой payload с тем же ключом получает 409, а операция в процессе не создаётся повторно.

Ключ должен храниться в secret manager или в защищённом файле с правами 0600. Права доступа дополнительно ограничиваются scopes, tenant и project context.

03 · Ingest

Загрузить объект

Ingest создаёт асинхронный job и связывает его с object и исходной revision. Для повторяемых записывающих операций используйте уникальный idempotency key.

curl -X POST https://api.recoverable.ru/v1/integration/ingest \
  -H "X-EOC-API-Key: $EOC_API_KEY" \
  -H "Idempotency-Key: project-a-r1" \
  -F "file=@object.eoc" \
  -F "projectId=project-a"

jobасинхронная операция обработки

objectидентичность цифрового объекта

revisionсогласованный набор состояния

04 · Read state

Получить job, object и revision

Сначала отслеживайте job, затем читайте проекцию объекта и конкретной ревизии.

curl https://api.recoverable.ru/v1/integration/jobs/:jobId \
  -H "X-EOC-API-Key: $EOC_API_KEY"

curl https://api.recoverable.ru/v1/integration/objects/:objectId \
  -H "X-EOC-API-Key: $EOC_API_KEY"

curl https://api.recoverable.ru/v1/integration/objects/:objectId/revisions/:revision \
  -H "X-EOC-API-Key: $EOC_API_KEY"

Job отражает состояние операции; object — устойчивую идентичность; revision — конкретный проверяемый набор FP, ED и revision data.

05 · Events

Просмотреть event ledger

Events фиксируют последовательность переходов: ingest, verification, evidence, storage и итоговое решение.

curl "https://api.recoverable.ru/v1/integration/events?objectId=:objectId" \
  -H "X-EOC-API-Key: $EOC_API_KEY"

06 · Webhooks и events

Подписки и доставки

Event ledger сообщает о переходах ingest, verification, evidence, storage и policy decision. Webhook сообщает внешней системе о событии; отдельный ресурс deliveries позволяет контролировать попытки доставки и повторную обработку. Семантика доставки — at least once: проверяйте подпись, сохраняйте event id и делайте обработчик идемпотентным.

curl https://api.recoverable.ru/v1/integration/webhooks \
  -H "X-EOC-API-Key: $EOC_API_KEY"

curl "https://api.recoverable.ru/v1/integration/webhook-deliveries?webhookId=:webhookId" \
  -H "X-EOC-API-Key: $EOC_API_KEY"

Endpoint получателя должен проверять подпись, сохранять event id и отвечать быстро. Повторная доставка не должна приводить к повторному применению операции.

07 · Limits and statuses

Ограничения и стабильные статусы

64 MiBмаксимальный размер ingest payload

60 requests/minuteбазовый лимит запросов на principal

4 concurrent · queue 64одновременные операции и глубина очереди

Превышение rate limit возвращает 429; заполненная очередь — 503; слишком большой payload — 413.
Scopes, tenant и project context проверяются до выполнения операции.
Решения: ALLOW, WARN, REJECT, QUARANTINE. Job/revision statuses: COMPLETED и FAILED; deliveries: DELIVERED и FAILED.
Ключи нельзя передавать в URL, браузерный frontend или git.
Chunked upload/download не входят в этот публичный v1-контракт; storage descriptors содержат opaque URI, а не browser download URL.

Связанные материалы

Что такое Recoverable EOC →

История релизов →

Страница npm и статус публикации →