Перейти к содержанию
Sursa для разработчиков

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 режима «Смотреть как» для сессии. 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Действие запрещено: недостаточно прав роли, нет доступа к коллекции или карточке, запрос выполняется в режиме «Смотреть как» либо организация приостановлена или удалена (`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