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 режиму «View as» для сесії. Встановлюється через 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Дію не дозволено: роль не має достатніх прав, немає доступу до колекції чи картки, запит виконується в режимі «View as» або організацію призупинено чи видалено (`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)