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

GET/v1/cards-by-external-id/{external_id}

Получить карточку по внешнему ID

get_card_by_external_id

Возвращает ту же карточку с теми же проверками доступа, что и GET /v1/cards/{card_id}, но по external_id интегратора. Если в организации нет карточки с этим external_id или карточка не видна вызывающему, запрос возвращает 404 cards.not_found.

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

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

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

  • external_idstringобязательно

    external_id карточки: строка длиной от 1 до 512 символов, уникальная в пределах организации.

    length ≥ 1, 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Успешный ответ

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

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