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 режиму «View as» для сесії. Встановлюється через 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Дію не дозволено: роль не має достатніх прав, немає доступу до колекції чи картки, запит виконується в режимі «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, крім загальних кодів будь-якого запиту.

Безпечні повтори

Надсилайте заголовок 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)