POST/v1/cards/archive

Загрузить архив документов

upload_card_archive

Передайте ZIP-архив в поле file формы multipart/form-data. Каждый поддерживаемый файл внутри становится отдельным документом, как при одиночной загрузке (POST /v1/cards). Контейнеры подписи ASiC (.asice, .sce, .bdoc, .asics) тоже считаются архивами: их файлы данных становятся документами, META-INF/ пропускается, а подпись не проверяется. Поля формы те же, что при загрузке файла (коллекция, теги, владелец, категория, чувствительность), без предпросмотра.

Архив проверяется по сигнатуре (переименованный документ Office архивом не считается и возвращает 415 files.type_mismatch), действует лимит загрузки установки, а антивирусная проверка охватывает весь архив.

Оглавление проверяется синхронно. Ответ содержит план (какие файлы станут документами, какие пропущены и почему) и задание распаковки (job_id, batch_id). Задание раскрывает вложенные архивы (по умолчанию до 3 уровней), проверяет каждый документ по сигнатуре и антивирусом и ставит его в обычную очередь индексации с тем же batch_id (ход обработки документов — GET /v1/jobs?batch=). Результат доступен через GET /v1/archives/{job_id}.

Лимиты (значения установки по умолчанию): не больше 1000 файлов во всём дереве (больше — 413 cards.archive_too_many_files), не больше 2048 МБ в распакованном виде (больше — 413 cards.archive_too_large) и не больше оставшегося хранилища организации по её тарифу (402 limits.storage), лимит загрузки одного файла — для каждого файла внутри, а степень сжатия — не больше 100:1 на запись. Записи с «..», абсолютным путём или буквой диска, символические ссылки, зашифрованные записи и неподдерживаемые форматы пропускаются с указанием причины (skipped[].reason). Системные файлы ОС, каталоги и пустые файлы пропускаются молча (ignored). Имена не в UTF-8 читаются как cp866 или cp1251. Файл, который не является ZIP, возвращает 400 cards.archive_invalid, полностью зашифрованный архив — 400 cards.archive_encrypted, а архив без единого документа — 400 cards.archive_empty.

Каждый документ помнит свой архив: CardVersion.archive и Card.source_archive (карточка показывает архив своей текущей версии).

Вместо формы можно передать тело application/json (ArchiveUploadFromUpload, начиная с 1.62.0): архив — готовая загрузка по частям upload_id (назначение archive), поля те же, что в форме, а tags — список строк. Архив уже проверен на шаге complete, а лимит размера — лимит загрузки по частям, а не лимит загрузки одним запросом. Загрузка используется один раз, в той же транзакции, что ставит в очередь задание распаковки; коды ошибок загрузки те же, что у POST /v1/cards.

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

Передайте ключ API в заголовке Authorization: Authorization: Bearer <ключ>.

Параметры заголовков

Idempotency-Keystring
Ключ для безопасного повтора записи: от 1 до 255 печатных символов ASCII; рекомендуется UUID v4 на каждую логическую операцию. Повтор с тем же ключом в течение 24 часов не выполняет операцию заново: он возвращает сохранённый ответ (статус, заголовки и тело) с заголовком Idempotency-Replayed: true. Тот же ключ с другим методом, путём, Content-Type или телом — ответ 409 api.idempotency_mismatch; пока первый запрос ещё выполняется — 409 api.idempotency_in_progress с Retry-After: 1. После ответа 5xx или 429 ключ освобождается, и повтор выполняет операцию заново. Ключ действует в пределах организации и вызывающей стороны (ключ API, пользователь или ключ своего источника).
length ≥ 1, length ≤ 255
X-View-Asstring
Только для ключей API с ролью admin. Выполняет запрос от имени профиля доступа <profile>[:viewer|verifier|editor], например employee:viewer. Ключ установки этот заголовок использовать не может (403).

Параметры cookie

kb_view_asstring
Cookie режима «Смотреть как» для сессии. POST /auth/view-as устанавливает её, DELETE /auth/view-as — сбрасывает.

Тело запроса

multipart/form-data

Объект: ArchiveUploadForm

filestring (application/zip)обязательно
collectionstring
По умолчанию: "default"
tagsstring
По умолчанию: ""
forceboolean
По умолчанию: false
owner_idinteger | null
verify_interval_daysinteger | null
categorystring | null
sensitiveboolean | null
folder_idstring | null
Папка коллекции collection, в которую положить все документы архива. Папка другой коллекции возвращает 400 folders.card_collection_mismatch, отсутствующая папка — 404 folders.not_found, а без права COLLECTION_EDIT_CARDS на папку — 403 authz.forbidden. Проверка выполняется до сохранения архива. Дубли уже загруженных файлов в папку не переносятся.
length ≤ 64
collection_idinteger | null
Коллекция по ID. Если передан и collection, приоритет у collection_id. Если коллекции нет в организации или она не видна, ответ — 404 collections.not_found.

application/json

Объект: ArchiveUploadFromUpload

upload_idstringобязательно
Готовая загрузка (ready) с назначением archive; используется один раз.
collectionstring
По умолчанию: "default"
collection_idinteger | null
Коллекция по ID. Если передано и collection, приоритет у collection_id. Коллекция, которой нет в организации, которая не видна или находится вне коллекций ключа, возвращает 404 collections.not_found.
tagsarray of string
items ≤ 30
forceboolean
По умолчанию: false
owner_idinteger | null
verify_interval_daysinteger | null
categorystring | null
sensitiveboolean | null
folder_idstring | null
length ≤ 64

Ответы

200План распаковки и задание

Заголовки ответа

RateLimit-Policy
Действующие лимиты в формате черновика IETF draft-ietf-httpapi-ratelimit-headers: элементы через запятую "<name>";q=<quota>;w=<window in seconds>. key — частота запросов ключа API (квота — допустимый всплеск, окно — время до полного восстановления; для сессии это user, без учётных данных — ip); minute, day и month — квоты организации на календарную минуту, день и месяц по UTC.
RateLimit
Сколько осталось по каждому лимиту из RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Лимит самой строгой записи в RateLimit-Policy (той, где осталось меньше всего запросов).
X-RateLimit-Remaining
Сколько запросов осталось в пределах самого строгого лимита.
X-RateLimit-Reset
Через сколько секунд сбросится самый строгий лимит.
Idempotency-Replayed
true — ответ воспроизведён из сохранённого для этого Idempotency-Key: операция повторно не выполнялась.

application/json

Объект: ArchiveUploadResult

job_idintegerобязательно
batch_idstringобязательно
Пакет заданий индексации для документов архива (GET /v1/jobs?batch=).
statusstringобязательно
Допустимые значения: queued
archiveArchiveInfoобязательно
plannedarray of stringобязательно
Пути файлов на всех уровнях, которые станут документами, включая файлы во вложенных архивах (b.zip/c.pdf).
documentsintegerобязательно
Число документов на всех уровнях, включая файлы во вложенных архивах. Результат распаковки в сумме даёт то же число: созданные + дубли + отклонённые проверкой содержимого (ArchiveJob).
nested_archivesintegerобязательно
skippedarray of ArchiveSkipобязательно
ignoredintegerобязательно
Системные записи (файлы ОС, каталоги, пустые файлы, подписи контейнеров).

400Запрос неверен: значение параметра или состояние объекта не позволяет выполнить действие (`detail` — сообщение).

Заголовки ответа

RateLimit-Policy
Действующие лимиты в формате черновика IETF draft-ietf-httpapi-ratelimit-headers: элементы через запятую "<name>";q=<quota>;w=<window in seconds>. key — частота запросов ключа API (квота — допустимый всплеск, окно — время до полного восстановления; для сессии это user, без учётных данных — ip); minute, day и month — квоты организации на календарную минуту, день и месяц по UTC.
RateLimit
Сколько осталось по каждому лимиту из RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Лимит самой строгой записи в RateLimit-Policy (той, где осталось меньше всего запросов).
X-RateLimit-Remaining
Сколько запросов осталось в пределах самого строгого лимита.
X-RateLimit-Reset
Через сколько секунд сбросится самый строгий лимит.

application/json

Объект: Error

401Учётные данные не переданы (нет ни cookie сессии, ни ключа API) или ключ не найден.

Заголовки ответа

RateLimit-Policy
Действующие лимиты в формате черновика IETF draft-ietf-httpapi-ratelimit-headers: элементы через запятую "<name>";q=<quota>;w=<window in seconds>. key — частота запросов ключа API (квота — допустимый всплеск, окно — время до полного восстановления; для сессии это user, без учётных данных — ip); minute, day и month — квоты организации на календарную минуту, день и месяц по UTC.
RateLimit
Сколько осталось по каждому лимиту из RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Лимит самой строгой записи в RateLimit-Policy (той, где осталось меньше всего запросов).
X-RateLimit-Remaining
Сколько запросов осталось в пределах самого строгого лимита.
X-RateLimit-Reset
Через сколько секунд сбросится самый строгий лимит.

application/json

Объект: Error

402Организация достигла лимита тарифа (карточки, хранилище или пользователи). В `error.details` — `kind`, `limit` и `used`.

Заголовки ответа

RateLimit-Policy
Действующие лимиты в формате черновика IETF draft-ietf-httpapi-ratelimit-headers: элементы через запятую "<name>";q=<quota>;w=<window in seconds>. key — частота запросов ключа API (квота — допустимый всплеск, окно — время до полного восстановления; для сессии это user, без учётных данных — ip); minute, day и month — квоты организации на календарную минуту, день и месяц по UTC.
RateLimit
Сколько осталось по каждому лимиту из RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Лимит самой строгой записи в RateLimit-Policy (той, где осталось меньше всего запросов).
X-RateLimit-Remaining
Сколько запросов осталось в пределах самого строгого лимита.
X-RateLimit-Reset
Через сколько секунд сбросится самый строгий лимит.

application/json

Объект: Error

403Действие запрещено: недостаточно прав роли, нет доступа к коллекции или карточке, запрос выполняется в режиме «Смотреть как» либо организация приостановлена или удалена (`detail` — объект с `code: org_suspended | org_deleted`).

Заголовки ответа

RateLimit-Policy
Действующие лимиты в формате черновика IETF draft-ietf-httpapi-ratelimit-headers: элементы через запятую "<name>";q=<quota>;w=<window in seconds>. key — частота запросов ключа API (квота — допустимый всплеск, окно — время до полного восстановления; для сессии это user, без учётных данных — ip); minute, day и month — квоты организации на календарную минуту, день и месяц по UTC.
RateLimit
Сколько осталось по каждому лимиту из RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Лимит самой строгой записи в RateLimit-Policy (той, где осталось меньше всего запросов).
X-RateLimit-Remaining
Сколько запросов осталось в пределах самого строгого лимита.
X-RateLimit-Reset
Через сколько секунд сбросится самый строгий лимит.

application/json

Объект: Error

404Объект не существует или вам недоступен. API не подтверждает существование объекта с ограниченным доступом.

Заголовки ответа

RateLimit-Policy
Действующие лимиты в формате черновика IETF draft-ietf-httpapi-ratelimit-headers: элементы через запятую "<name>";q=<quota>;w=<window in seconds>. key — частота запросов ключа API (квота — допустимый всплеск, окно — время до полного восстановления; для сессии это user, без учётных данных — ip); minute, day и month — квоты организации на календарную минуту, день и месяц по UTC.
RateLimit
Сколько осталось по каждому лимиту из RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Лимит самой строгой записи в RateLimit-Policy (той, где осталось меньше всего запросов).
X-RateLimit-Remaining
Сколько запросов осталось в пределах самого строгого лимита.
X-RateLimit-Reset
Через сколько секунд сбросится самый строгий лимит.

application/json

Объект: Error

409Состояние объекта не позволяет выполнить действие: например, дубль, идёт индексация или задание уже обработано.

Заголовки ответа

RateLimit-Policy
Действующие лимиты в формате черновика IETF draft-ietf-httpapi-ratelimit-headers: элементы через запятую "<name>";q=<quota>;w=<window in seconds>. key — частота запросов ключа API (квота — допустимый всплеск, окно — время до полного восстановления; для сессии это user, без учётных данных — ip); minute, day и month — квоты организации на календарную минуту, день и месяц по UTC.
RateLimit
Сколько осталось по каждому лимиту из RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Лимит самой строгой записи в RateLimit-Policy (той, где осталось меньше всего запросов).
X-RateLimit-Remaining
Сколько запросов осталось в пределах самого строгого лимита.
X-RateLimit-Reset
Через сколько секунд сбросится самый строгий лимит.

application/json

Объект: Error

410Объект существовал, но больше недоступен: ссылка использована или истекла либо файл удалён по окончании срока хранения.

Заголовки ответа

RateLimit-Policy
Действующие лимиты в формате черновика IETF draft-ietf-httpapi-ratelimit-headers: элементы через запятую "<name>";q=<quota>;w=<window in seconds>. key — частота запросов ключа API (квота — допустимый всплеск, окно — время до полного восстановления; для сессии это user, без учётных данных — ip); minute, day и month — квоты организации на календарную минуту, день и месяц по UTC.
RateLimit
Сколько осталось по каждому лимиту из RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Лимит самой строгой записи в RateLimit-Policy (той, где осталось меньше всего запросов).
X-RateLimit-Remaining
Сколько запросов осталось в пределах самого строгого лимита.
X-RateLimit-Reset
Через сколько секунд сбросится самый строгий лимит.

application/json

Объект: Error

413Тело запроса больше допустимого размера.

Заголовки ответа

RateLimit-Policy
Действующие лимиты в формате черновика IETF draft-ietf-httpapi-ratelimit-headers: элементы через запятую "<name>";q=<quota>;w=<window in seconds>. key — частота запросов ключа API (квота — допустимый всплеск, окно — время до полного восстановления; для сессии это user, без учётных данных — ip); minute, day и month — квоты организации на календарную минуту, день и месяц по UTC.
RateLimit
Сколько осталось по каждому лимиту из RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Лимит самой строгой записи в RateLimit-Policy (той, где осталось меньше всего запросов).
X-RateLimit-Remaining
Сколько запросов осталось в пределах самого строгого лимита.
X-RateLimit-Reset
Через сколько секунд сбросится самый строгий лимит.

application/json

Объект: Error

415Формат файла не поддерживается.

Заголовки ответа

RateLimit-Policy
Действующие лимиты в формате черновика IETF draft-ietf-httpapi-ratelimit-headers: элементы через запятую "<name>";q=<quota>;w=<window in seconds>. key — частота запросов ключа API (квота — допустимый всплеск, окно — время до полного восстановления; для сессии это user, без учётных данных — ip); minute, day и month — квоты организации на календарную минуту, день и месяц по UTC.
RateLimit
Сколько осталось по каждому лимиту из RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Лимит самой строгой записи в RateLimit-Policy (той, где осталось меньше всего запросов).
X-RateLimit-Remaining
Сколько запросов осталось в пределах самого строгого лимита.
X-RateLimit-Reset
Через сколько секунд сбросится самый строгий лимит.

application/json

Объект: Error

422Ошибка проверки: тело или параметры не соответствуют схеме (`detail` — список ошибок проверки) либо значение параметра вне допустимого диапазона (`detail` — сообщение).

Заголовки ответа

RateLimit-Policy
Действующие лимиты в формате черновика IETF draft-ietf-httpapi-ratelimit-headers: элементы через запятую "<name>";q=<quota>;w=<window in seconds>. key — частота запросов ключа API (квота — допустимый всплеск, окно — время до полного восстановления; для сессии это user, без учётных данных — ip); minute, day и month — квоты организации на календарную минуту, день и месяц по UTC.
RateLimit
Сколько осталось по каждому лимиту из RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Лимит самой строгой записи в RateLimit-Policy (той, где осталось меньше всего запросов).
X-RateLimit-Remaining
Сколько запросов осталось в пределах самого строгого лимита.
X-RateLimit-Reset
Через сколько секунд сбросится самый строгий лимит.

application/json

Объект: Error

429Слишком много запросов (`api.rate_limited`), квота организации на минуту, день или месяц исчерпана (`api.quota_exceeded`; в `error.details` — `quota`, `limit` и `reset_at`), достигнут лимит организации или сервис ответов занят (`answers.engine_busy`). Подождите время, указанное в заголовке `Retry-After`.

Заголовки ответа

Retry-After
Сколько секунд подождать перед повтором запроса.
RateLimit-Policy
Действующие лимиты в формате черновика IETF draft-ietf-httpapi-ratelimit-headers: элементы через запятую "<name>";q=<quota>;w=<window in seconds>. key — частота запросов ключа API (квота — допустимый всплеск, окно — время до полного восстановления; для сессии это user, без учётных данных — ip); minute, day и month — квоты организации на календарную минуту, день и месяц по UTC.
RateLimit
Сколько осталось по каждому лимиту из RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Лимит самой строгой записи в RateLimit-Policy (той, где осталось меньше всего запросов).
X-RateLimit-Remaining
Сколько запросов осталось в пределах самого строгого лимита.
X-RateLimit-Reset
Через сколько секунд сбросится самый строгий лимит.

application/json

Объект: Error

503Сервис, от которого зависит этот запрос, временно недоступен. Повторите позже.

Заголовки ответа

RateLimit-Policy
Действующие лимиты в формате черновика IETF draft-ietf-httpapi-ratelimit-headers: элементы через запятую "<name>";q=<quota>;w=<window in seconds>. key — частота запросов ключа API (квота — допустимый всплеск, окно — время до полного восстановления; для сессии это user, без учётных данных — ip); minute, day и month — квоты организации на календарную минуту, день и месяц по UTC.
RateLimit
Сколько осталось по каждому лимиту из RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Лимит самой строгой записи в RateLimit-Policy (той, где осталось меньше всего запросов).
X-RateLimit-Remaining
Сколько запросов осталось в пределах самого строгого лимита.
X-RateLimit-Reset
Через сколько секунд сбросится самый строгий лимит.

application/json

Объект: Error

Коды ошибок

Коды, которые эта операция может вернуть в error.code, помимо общих кодов любого запроса.

Безопасные повторы

Передавайте заголовок Idempotency-Key (например, UUID) с каждым POST и PATCH. Повтор с тем же ключом в течение 24 часов возвращает сохранённый ответ, а не выполняет запрос снова.

Лимиты частоты

В ответах есть заголовки RateLimit и RateLimit-Policy, а также прежние X-RateLimit-Limit, X-RateLimit-Remaining и X-RateLimit-Reset. В ответе 429 есть Retry-After в секундах: подождите и повторите запрос.

← cards · Справочник API

curl -X POST 'https://api.sursa.com/v1/cards/archive' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"upload_id":"upl_0123456789abcdef0123456789abcdef"}' \
  -H "Authorization: Bearer $SURSA_API_KEY"

Попробовать

Ключ API

Ключ хранится только в памяти этой вкладки и отправляется только на https://api.sursa.com.

Запросы работают с настоящими данными вашей организации.

Idempotency-Key header

X-View-As header

Idempotency-Key

Если поле пустое, для каждого запроса создаётся новый ключ.

Тело запроса (JSON)