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

GET/v1/cards/{card_id}

Отримати картку з версіями, коментарями, таблицями та подіями

get_card

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

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

Параметри шляху

  • card_idstringобов’язково

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

  • 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Успішна відповідь

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

  • 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

Об’єкт: 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