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

Създаване или замяна на карта по външен идентификатор

upsert_card_by_external_id

Създава или заменя карта по external_id на интегратора. Изпратете текст като application/json (CardTextUpsert) или файл като multipart/form-data (CardFileUpsertForm, със същите проверки на файла като в POST /v1/cards). Ако в организацията няма карта с този external_id, картата се създава в колекцията и папката от тялото (201). Иначе съдържанието се заменя с нова версия и се индексира отново по същия начин като нова версия на файл, а данните на картата (заглавие, етикети, отговорник, категория, metadata) получават подадените стойности (200). Непромененото съдържание не създава нова версия (status: skipped, reason: unchanged), затова повтарянето на заявката е безопасно дори без Idempotency-Key. Когато е подадено metadata, то заменя целия обект. Достъпът се проверява както при качване, когато картата се създава, и както при актуализиране на карта, когато се заменя. Съдържанието на карта, която е само частично видима за извикващия, не се заменя (403 cards.content_whole_access). Картите от източници не се презаписват по този начин: ако external_id принадлежи на документ от собствен източник или намерената карта се поддържа от източник, заявката връща 409 cards.managed_by_source. Промяната на съдържанието премахва проверката на картата, както всяка нова версия (причина update).

Удостоверяване

Изпратете API ключ в заглавката Authorization: Authorization: Bearer <ключ>.

Параметри на пътя

external_idstringзадължително
external_id на картата: низ от 1–512 знака, уникален в организацията.
length ≥ 1, length ≤ 512

Параметри в заглавката

X-View-Asstring
Само за API ключове с ролята admin. Изпълнява заявката от името на профила за достъп <profile>[:viewer|verifier|editor], например employee:viewer. Ключът на инсталацията не може да използва тази заглавка (403).

Параметри в бисквитка

kb_view_asstring
Бисквитка на режима „View as“ за сесия. POST /auth/view-as я задава, а DELETE /auth/view-as я изчиства.

Тяло на заявката

application/json

Обект: CardTextUpsert

titlestring
length ≥ 1, length ≤ 200
bodystringзадължително
Текст на картата във формата content_type.
length ≥ 1, length ≤ 500000
content_typeCardTextContentType
collectionstring
Колекция по име при създаване на картата. По подразбиране – колекцията по подразбиране на инсталацията.
collection_idinteger | null
Колекция по ID при създаване на картата. Ако е подадено и collection, предимство има collection_id.
folder_idstring | null
Папка на колекцията за новата карта, със същите проверки като folder_id при качване на файл.
length ≤ 64
tagsarray of string | null
items ≤ 30
categorystring | null
length ≤ 60
sensitiveboolean | null
owner_idinteger | null
verify_interval_daysinteger | null
≥ 1, ≤ 3650
metadataMetadataPatch
asyncboolean
true връща отговор веднага и индексира картата в опашката; false връща отговор след индексирането.
По подразбиране: false

multipart/form-data

Обект: CardFileUpsertForm

filestring (application/octet-stream)задължително
titlestring | null
Заглавие на картата. Ако не е подадено, новата карта получава името на файла, а съществуващата запазва заглавието си.
length ≤ 200
collectionstring
collection_idinteger | null
folder_idstring | null
length ≤ 64
tagsstring
Етикети, разделени със запетаи.
owner_idinteger | null
verify_interval_daysinteger | null
categorystring | null
sensitiveboolean | null
metadatastring | null
metadata: JSON обект като стойност на полето от формата. Правилата са тези на MetadataPatch.
asyncboolean
По подразбиране: false

Отговори

200Картата вече е съществувала. Съдържанието ѝ е заменено (`queued`, `ready`, `error`) или не се е променило (`skipped`).

Заглавки на отговора

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

Обект: UploadResult

statusstringзадължително
Допустими стойности: queuedskippedreadyerror
job_idinteger
jobJob
cardCard | null
duplicatetrue
card_idstring | null
reasonstring
unchanged или an identical file is already indexed.
tablesinteger
timingsobject
Полета
- total_snumber
errorstring

201Картата е създадена (`queued` при асинхронна заявка, `ready` или `error` при синхронна).

Заглавки на отговора

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

Обект: UploadResult

statusstringзадължително
Допустими стойности: queuedskippedreadyerror
job_idinteger
jobJob
cardCard | null
duplicatetrue
card_idstring | null
reasonstring
unchanged или an identical file is already indexed.
tablesinteger
timingsobject
Полета
- total_snumber
errorstring

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Не са изпратени идентификационни данни (нито бисквитка на сесията, нито 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

402Организацията е достигнала лимит на плана (карти, хранилище или потребители). `error.details` съдържа `kind`, `limit` и `used`.

Заглавки на отговора

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

409Състоянието на обекта не позволява действието, например дубликат, индексиране в ход или задание, което вече е обработено.

Заглавки на отговора

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

413Тялото на заявката надвишава допустимия размер.

Заглавки на отговора

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

415Форматът на файла не се поддържа.

Заглавки на отговора

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

503Услуга, от която зависи тази заявка, временно не е достъпна. Опитайте отново по-късно.

Заглавки на отговора

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

curl -X PUT 'https://api.sursa.com/v1/cards-by-external-id/EXTERNAL_ID' \
  -H "Content-Type: application/json" \
  -d '{"title":"Refund policy","body":"# Refund policy\n\nRefunds are processed within 14 days.","collection":"support"}' \
  -H "Authorization: Bearer $SURSA_API_KEY"

Изпробвайте

API ключ

Ключът остава само в паметта на този раздел на браузъра и се изпраща единствено до https://api.sursa.com.

Заявките работят с реалните данни на организацията ви.

X-View-As header

external_id path *

Тяло на заявката (JSON)