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).

Параметри колачића

kb_view_asstring
Колачић режима „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Акредитиви нису послати (ни колачић сесије ни 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, поред општих кодова сваког захтева.

Безбедни поновни покушаји

Уз сваки POST и PATCH захтев пошаљите заглавље Idempotency-Key (на пример UUID). Поновни покушај са истим кључем у року од 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)