Перейти до вмісту
Sursa Developers

GET/v1/cards

Отримати список карток

list_cards

Повертає картки з фільтрами, сортуванням і пагінацією. З preview=1 (для вигляду плиток) кожна картка має також preview (перші 200 символів тексту) і preview_tables (аркуші з кількістю рядків) — у межах вашого профілю доступу.

Автентифікація

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

Параметри запиту

  • collectionstring | null
  • folderstring | null

    <folder ID> повертає картки папки та всіх її вкладених папок. none повертає картки колекції, що не лежать у жодній папці, і потребує collection (інакше 400 cards.invalid_folder_filter). Якщо папки не існує або вона вам не видима, запит повертає 404 folders.not_found.

    length ≤ 64

  • statusstring | null

    Допустимі значення: processingreadyerrorarchivedall

  • ownerstring | null

    me, none або ID користувача.

  • owner_idinteger | null
  • verificationstring | null

    Допустимі значення: verifiedneeds_verificationstale

  • kindCardKind
  • typestring | null

    table повертає картки з таблицями фактів, text — картки без них.

    Допустимі значення: tabletext

  • tagsstring | null

    Теги через кому (картка має мати їх усі).

  • idsstring | null

    ID карток через кому.

  • searchstring | null
  • categorystring | null
  • sensitiveboolean | null
  • sortCardSort

    Типове значення: "created_at"

  • orderstring

    Допустимі значення: ascdesc

    Типове значення: "desc"

  • limitinteger

    Типове значення: 200

  • offsetinteger

    Типове значення: 0

  • previewboolean

    true додає preview (перші 200 символів) і preview_tables для вигляду плиток.

    Типове значення: false

  • updated_sincestring (date-time)

    Лише картки з updated_at у цей момент або пізніше (RFC 3339 зі зсувом), для синхронізації. Без явних sort і order список сортується за updated_at за зростанням, потім за id. Видалених карток у списку немає: про видалення повідомляють події.

  • metadatamap of string

    Фільтр за metadata: metadata[<key>]=<value> — точний збіг. До 3 умов, і всі вони мають виконуватися (?metadata[team]=support&metadata[crm_id]=A-1042). Понад 3 умови або неправильний ключ повертають 400 api.metadata_invalid.

  • collection_idinteger

    Колекція за ID. Якщо передано також collection, перевагу має collection_id. Для колекції, якої немає в організації або яку не видно, повертається 404 collections.not_found.

  • external_idstring

    Лише картка з цим external_id.

  • cursorstring

    Курсор наступної сторінки з X-Next-Cursor або next_cursor попередньої відповіді з тими самими фільтрами; він містить розмір сторінки. Разом з offset — 422 validation.failed; курсор іншого списку, з іншими фільтрами або пошкоджений — 400 api.cursor_invalid.

    length ≤ 512

  • expand[]array of string

    Пов’язані об’єкти, які слід додати до відповіді (з версії 1.62.0): шлях зі списку x-expandable операції. Параметр можна повторити до 10 разів. Шлях має до 2 сегментів, розділених крапкою (collection.default_owner). У списку шлях починається з data. і застосовується до кожного елемента сторінки (expand[]=data.owner). Розгорнутий об’єкт потрапляє в об’єкт expanded елемента, а поле з ID лишається. Об’єкт, якого той, хто викликає, не може бачити за перевірками його власної операції читання, розгортається як null. Невідомий шлях, понад 10 шляхів або шлях, глибший за 2 сегменти, повертає 400 api.expand_invalid.

    items ≤ 10

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

  • 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.

Відповіді

200Успішна відповідь

Заголовки відповіді

  • Link

    Адреса наступної сторінки, <…>; rel="next". Якщо заголовка немає, це остання сторінка.

  • X-Next-Cursor

    Курсор наступної сторінки для параметра cursor. Якщо заголовка немає, це остання сторінка.

  • 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

Об’єкт: CardList

array of Card
  • expandedCardExpanded
  • permissionsObjectPermissionList
  • accessstring

    Допустимі значення: wholepartial

  • access_contactstring

    До кого звертатися по доступ (лише коли access=partial).

  • aclobject
    Поля
    • verifybooleanобов’язково
    • writebooleanобов’язково
  • categorystringобов’язково
  • category_confidencenumber | nullобов’язково
  • category_lockedbooleanобов’язково
  • category_reviewbooleanобов’язково
  • category_sourceCategorySource | nullобов’язково
  • collectionstringобов’язково
  • collection_idintegerобов’язково
  • collection_titlestring
  • commentsarray of CardComment
  • content_jsonContentJSON | null

    Вміст редактора останньої опублікованої версії. Поля може не бути; тоді отримайте вміст редактора з чернетки (POST /v1/drafts з card_id).

  • editing_lockEditingLock | null

    Активне блокування редагування. Поля може не бути; тоді редактор дізнається, хто тримає блокування, з 409 cards.locked на POST /v1/cards/{card_id}/lock.

  • created_atstring (date-time)обов’язково
  • days_since_verifiedintegerобов’язково
  • errorstring | nullобов’язково
  • eventsarray of CardEvent
  • feedback_negintegerобов’язково
  • feedback_posintegerобов’язково
  • foldersarray of CardFolderRef

    Лише в списку карток: папки, що містять картку (ті, які бачить користувач), зі шляхами від кореня колекції. Порожній список означає, що картка не лежить у жодній папці.

  • has_tablesboolean

    Лише в списку карток.

  • hidden_partsboolean
  • idstringобов’язково
  • jobJob | null
  • kindCardKindобов’язково
  • org_idintegerобов’язково
  • owner_activeboolean | null
  • owner_idinteger | nullобов’язково
  • owner_namestring | nullобов’язково
  • pagesinteger | nullобов’язково
  • parserstring | nullобов’язково

    Спосіб розбору документа як нейтральний код: document (повна структура: сторінки, заголовки, таблиці, скановані сторінки), pdf (текстовий шар PDF), docx, xlsx, csv, markdown, html, text. Список може розширюватися.

  • partsarray of CardPartобов’язково
  • sensitivebooleanобов’язково
  • sha256string | nullобов’язково
  • sizeintegerобов’язково
  • snoozed_atstring (date-time) | null
  • snoozed_byinteger | null
  • snoozed_untilstring | null
  • source_changedbooleanобов’язково
  • source_pathstring | nullобов’язково
  • source_urlstring | nullобов’язково
  • statusstringобов’язково

    Допустимі значення: processingreadyerrorarchived

  • tablesarray of CardTable
  • tagsarray of stringобов’язково
  • titlestringобов’язково
  • trustnumberобов’язково
  • trust_if_verifiednumber
  • trust_partsTrustPartsобов’язково
  • updated_atstring (date-time)обов’язково
  • verificationVerificationобов’язково
  • verified_atstring (date-time) | nullобов’язково
  • verified_byinteger | nullобов’язково
  • verified_by_namestring | null
  • verifier_idsarray of integerобов’язково
  • verifiersarray of object
    Поля
    • activebooleanобов’язково
    • idintegerобов’язково
    • namestringобов’язково
  • verify_interval_daysintegerобов’язково
  • versionintegerобов’язково
  • versionsarray of CardVersion
  • source_archiveArchiveSource
  • created_byinteger | null
  • manual_optionsobject

    Ручні налаштування розбору (попередній перегляд).

  • doc_kindDocKind | null

    Тип документа. null, якщо тип не визначено (наприклад, для карток, проіндексованих до появи типів документів).

  • doc_kind_confidencenumber | null

    Рівень упевненості в типі документа, від 0 до 1.

  • doc_kind_sourcestring | null

    Що визначило тип: правила (rules), користувач (manual) або автоматична класифікація. Список може розширюватися: невідоме значення вважайте автоматичною класифікацією.

    Допустимі значення: rulesmanualnull

  • invoiceDocInvoiceExtraction | null

    Поля рахунку, кредит-ноти або квитанції (лише для цих типів і лише в картці, не в списку). null, якщо у вас немає доступу до всього документа, бо поля вилучаються з усього документа.

  • warningsarray of ReviewWarning

    Попередження розбору документа (ReviewWarning; лише в картці, не в списку).

  • enrichmentCardEnrichmentStatus | null

    Стан збагачення (лише в картці, не в списку). Тип документа, поля рахунку та фінансові записи додаються у фоновому режимі після індексації й можуть бути перераховані пізніше; вони з’являються в картці, коли готові. null означає, що стан недоступний (картку проіндексовано без фонового збагачення).

  • external_idstring | null

    ID картки в системі інтегратора. Унікальний в організації серед карток, що не надходять із джерел; null — не задано. /v1/cards-by-external-id/{external_id} читає й замінює картку за ним.

    length ≤ 512

  • metadataMetadata
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

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

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

Коди помилок

Коди, які ця операція може повернути в error.code, крім загальних кодів будь-якого запиту.

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

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

← cards · Довідник API