PATCH/v1/cards/{card_id}

Изменить карточку

update_card

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

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

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

card_idstringобязательно

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

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 режима «Смотреть как» для сессии. POST /auth/view-as устанавливает её, DELETE /auth/view-as — сбрасывает.

Тело запроса

application/json

Объект: CardUpdate

external_idstring | null
Задаёт или меняет external_id карточки; "" или null удаляет его. Если его использует другая карточка организации, запрос возвращает 409 cards.external_id_taken. external_id карточки источника не меняется (409 cards.managed_by_source).
length ≤ 512
metadataMetadataPatch
titlestring | null
owner_idinteger | null
verifier_idsarray of integer | null
verify_interval_daysinteger | null
≥ 1, ≤ 3650
tagsarray of string | null
statusstring | null
source_urlstring | null
categorystring | null
sensitiveboolean | null
table_categoriesmap of object | null

Ответы

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

Объект: 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, помимо общих кодов любого запроса.

Безопасные повторы

Передавайте заголовок 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 PATCH 'https://api.sursa.com/v1/cards/CARD_ID' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"external_id":"crm-1042","metadata":{"key":"string"},"title":"Refund policy"}' \
  -H "Authorization: Bearer $SURSA_API_KEY"

Попробовать

Ключ API

Ключ хранится только в памяти этой вкладки и отправляется только на https://api.sursa.com.

Запросы работают с настоящими данными вашей организации.

Idempotency-Key header

X-View-As header

card_id path *

Idempotency-Key

Если поле пустое, для каждого запроса создаётся новый ключ.

Тело запроса (JSON)