PATCH/v1/cards/{card_id}

Upraviť kartu

update_card

Autentifikácia

Odošlite kľúč API v hlavičke Authorization: Authorization: Bearer <kľúč>.

Parametre cesty

card_idstringpovinné

Parametre hlavičky

Idempotency-Keystring
Kľúč na bezpečné opakovanie zápisu: 1 až 255 tlačiteľných znakov ASCII; odporúča sa UUID v4 pre každú logickú operáciu. Opakovanie s tým istým kľúčom do 24 hodín operáciu znova nespustí: vráti uloženú odpoveď (stav, hlavičky a telo) s hlavičkou Idempotency-Replayed: true. Ten istý kľúč s inou metódou, cestou, Content-Type alebo telom vráti 409 api.idempotency_mismatch; kým prvá požiadavka ešte prebieha, vráti 409 api.idempotency_in_progress s Retry-After: 1. Po odpovedi 5xx alebo 429 sa kľúč uvoľní a opakovanie operáciu spustí znova. Kľúč platí v rámci organizácie a volajúceho (kľúč API, používateľ alebo kľúč vlastného zdroja).
length ≥ 1, length ≤ 255
X-View-Asstring
Len pre kľúče API s rolou admin. Vykoná požiadavku v mene dátového profilu <profile>[:viewer|verifier|editor], napríklad employee:viewer. Inštalačný kľúč túto hlavičku použiť nemôže (403).

Parametre cookie

kb_view_asstring
Súbor cookie režimu „View as“ pre reláciu. POST /auth/view-as ho nastaví a DELETE /auth/view-as ho odstráni.

Telo požiadavky

application/json

Objekt: CardUpdate

external_idstring | null
Nastaví alebo zmení external_id karty; "" alebo null ho odstráni. Ak ho používa iná karta organizácie, požiadavka vráti 409 cards.external_id_taken. external_id karty zo zdroja sa nemení (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

Odpovede

200Úspešná odpoveď

Hlavičky odpovede

RateLimit-Policy
Platné limity vo formáte návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddelené čiarkami "<name>";q=<quota>;w=<window in seconds>. key je frekvencia požiadaviek kľúča API (kvóta je nárazová špička, okno je čas na jej úplné doplnenie; pre reláciu je to user, bez prihlasovacích údajov ip); minute, day a month sú kvóty organizácie na kalendárnu minútu, deň a mesiac v UTC.
RateLimit
Čo zostáva z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limit najprísnejšej položky v RateLimit-Policy (tej, ktorej zostáva najmenej požiadaviek).
X-RateLimit-Remaining
Počet požiadaviek, ktoré zostávajú v rámci najprísnejšieho limitu.
X-RateLimit-Reset
Počet sekúnd do obnovenia najprísnejšieho limitu.
Idempotency-Replayed
true znamená, že odpoveď bola zopakovaná z uloženej odpovede pre tento Idempotency-Key: operácia sa znova nespustila.

application/json

Objekt: Card

expandedCardExpanded
permissionsObjectPermissionList
accessstring
Povolené hodnoty: wholepartial
access_contactstring
Na koho sa obrátiť kvôli prístupu (len pri access=partial).
aclobject
Polia
- verifybooleanpovinné
- writebooleanpovinné
categorystringpovinné
category_confidencenumber | nullpovinné
category_lockedbooleanpovinné
category_reviewbooleanpovinné
category_sourceCategorySource | nullpovinné
collectionstringpovinné
collection_idintegerpovinné
collection_titlestring
commentsarray of CardComment
content_jsonContentJSON | null
Obsah editora poslednej publikovanej verzie. Pole môže chýbať; vtedy získajte obsah editora z návrhu (POST /v1/drafts s card_id).
editing_lockEditingLock | null
Aktívny zámok úprav. Pole môže chýbať; vtedy sa editor dozvie, kto má zámok, z 409 cards.locked pri POST /v1/cards/{card_id}/lock.
created_atstring (date-time)povinné
days_since_verifiedintegerpovinné
errorstring | nullpovinné
eventsarray of CardEvent
feedback_negintegerpovinné
feedback_posintegerpovinné
foldersarray of CardFolderRef
Len v zozname kariet: priečinky, ktoré kartu obsahujú (tie, ktoré používateľ vidí), s ich cestami od koreňa kolekcie. Prázdny zoznam znamená, že karta nie je v žiadnom priečinku.
has_tablesboolean
Len v zozname kariet.
hidden_partsboolean
idstringpovinné
jobJob | null
kindCardKindpovinné
org_idintegerpovinné
owner_activeboolean | null
owner_idinteger | nullpovinné
owner_namestring | nullpovinné
pagesinteger | nullpovinné
parserstring | nullpovinné
Parser dokumentu ako neutrálny kód: document (úplná štruktúra: strany, nadpisy, tabuľky, naskenované strany), pdf (textová vrstva PDF), docx, xlsx, csv, markdown, html, text. Zoznam sa môže rozširovať.
partsarray of CardPartpovinné
sensitivebooleanpovinné
sha256string | nullpovinné
sizeintegerpovinné
snoozed_atstring (date-time) | null
snoozed_byinteger | null
snoozed_untilstring | null
source_changedbooleanpovinné
source_pathstring | nullpovinné
source_urlstring | nullpovinné
statusstringpovinné
Povolené hodnoty: processingreadyerrorarchived
tablesarray of CardTable
tagsarray of stringpovinné
titlestringpovinné
trustnumberpovinné
trust_if_verifiednumber
trust_partsTrustPartspovinné
updated_atstring (date-time)povinné
verificationVerificationpovinné
verified_atstring (date-time) | nullpovinné
verified_byinteger | nullpovinné
verified_by_namestring | null
verifier_idsarray of integerpovinné
verifiersarray of object
Polia
- activebooleanpovinné
- idintegerpovinné
- namestringpovinné
verify_interval_daysintegerpovinné
versionintegerpovinné
versionsarray of CardVersion
source_archiveArchiveSource
created_byinteger | null
manual_optionsobject
Ručné nastavenia parsovania (náhľad).
doc_kindDocKind | null
Typ dokumentu. null, ak typ nie je určený (napríklad pri kartách zaindexovaných pred zavedením typov dokumentov).
doc_kind_confidencenumber | null
Miera istoty pri type dokumentu, od 0 do 1.
doc_kind_sourcestring | null
Čo určilo typ: pravidlá (rules), používateľ (manual) alebo automatická klasifikácia. Zoznam sa môže rozširovať: neznámu hodnotu považujte za automatickú klasifikáciu.
Povolené hodnoty: rulesmanualnull
invoiceDocInvoiceExtraction | null
Polia faktúry, dobropisu alebo pokladničného dokladu (len pri týchto typoch a len v karte, nie v zozname). null, ak nemáte prístup k celému dokumentu, pretože polia sa vyťažujú z celého dokumentu.
warningsarray of ReviewWarning
Upozornenia z parsovania dokumentu (ReviewWarning; len v karte, nie v zozname).
enrichmentCardEnrichmentStatus | null
Stav obohatenia (len v karte, nie v zozname). Typ dokumentu, polia faktúry a finančné záznamy sa dopĺňajú na pozadí po indexovaní a neskôr ich možno prepočítať; v karte sa objavia, keď sú pripravené. null znamená, že stav nie je k dispozícii (karta bola zaindexovaná bez obohatenia na pozadí).
external_idstring | null
ID karty v systéme integrátora. Je jedinečné v organizácii medzi kartami, ktoré nepochádzajú zo zdrojov; null znamená, že nie je nastavené. /v1/cards-by-external-id/{external_id} podľa neho kartu číta a nahrádza.
length ≤ 512
metadataMetadata

400Požiadavka je neplatná: hodnota parametra alebo stav objektu akciu nedovoľuje (`detail` je správa).

Hlavičky odpovede

RateLimit-Policy
Platné limity vo formáte návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddelené čiarkami "<name>";q=<quota>;w=<window in seconds>. key je frekvencia požiadaviek kľúča API (kvóta je nárazová špička, okno je čas na jej úplné doplnenie; pre reláciu je to user, bez prihlasovacích údajov ip); minute, day a month sú kvóty organizácie na kalendárnu minútu, deň a mesiac v UTC.
RateLimit
Čo zostáva z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limit najprísnejšej položky v RateLimit-Policy (tej, ktorej zostáva najmenej požiadaviek).
X-RateLimit-Remaining
Počet požiadaviek, ktoré zostávajú v rámci najprísnejšieho limitu.
X-RateLimit-Reset
Počet sekúnd do obnovenia najprísnejšieho limitu.

application/json

Objekt: Error

401Neboli odoslané žiadne prihlasovacie údaje (ani cookie relácie, ani kľúč API) alebo sa kľúč nenašiel.

Hlavičky odpovede

RateLimit-Policy
Platné limity vo formáte návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddelené čiarkami "<name>";q=<quota>;w=<window in seconds>. key je frekvencia požiadaviek kľúča API (kvóta je nárazová špička, okno je čas na jej úplné doplnenie; pre reláciu je to user, bez prihlasovacích údajov ip); minute, day a month sú kvóty organizácie na kalendárnu minútu, deň a mesiac v UTC.
RateLimit
Čo zostáva z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limit najprísnejšej položky v RateLimit-Policy (tej, ktorej zostáva najmenej požiadaviek).
X-RateLimit-Remaining
Počet požiadaviek, ktoré zostávajú v rámci najprísnejšieho limitu.
X-RateLimit-Reset
Počet sekúnd do obnovenia najprísnejšieho limitu.

application/json

Objekt: Error

403Akcia nie je povolená: rola nestačí, chýba prístup ku kolekcii alebo karte, požiadavka beží v režime „View as“ alebo je organizácia pozastavená či odstránená (`detail` je objekt s `code: org_suspended | org_deleted`).

Hlavičky odpovede

RateLimit-Policy
Platné limity vo formáte návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddelené čiarkami "<name>";q=<quota>;w=<window in seconds>. key je frekvencia požiadaviek kľúča API (kvóta je nárazová špička, okno je čas na jej úplné doplnenie; pre reláciu je to user, bez prihlasovacích údajov ip); minute, day a month sú kvóty organizácie na kalendárnu minútu, deň a mesiac v UTC.
RateLimit
Čo zostáva z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limit najprísnejšej položky v RateLimit-Policy (tej, ktorej zostáva najmenej požiadaviek).
X-RateLimit-Remaining
Počet požiadaviek, ktoré zostávajú v rámci najprísnejšieho limitu.
X-RateLimit-Reset
Počet sekúnd do obnovenia najprísnejšieho limitu.

application/json

Objekt: Error

404Objekt neexistuje alebo vám nie je dostupný. API nepotvrdzuje, že objekt s obmedzeným prístupom existuje.

Hlavičky odpovede

RateLimit-Policy
Platné limity vo formáte návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddelené čiarkami "<name>";q=<quota>;w=<window in seconds>. key je frekvencia požiadaviek kľúča API (kvóta je nárazová špička, okno je čas na jej úplné doplnenie; pre reláciu je to user, bez prihlasovacích údajov ip); minute, day a month sú kvóty organizácie na kalendárnu minútu, deň a mesiac v UTC.
RateLimit
Čo zostáva z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limit najprísnejšej položky v RateLimit-Policy (tej, ktorej zostáva najmenej požiadaviek).
X-RateLimit-Remaining
Počet požiadaviek, ktoré zostávajú v rámci najprísnejšieho limitu.
X-RateLimit-Reset
Počet sekúnd do obnovenia najprísnejšieho limitu.

application/json

Objekt: Error

422Chyba validácie: telo alebo parametre nezodpovedajú schéme (`detail` je zoznam chýb validácie) alebo je hodnota parametra mimo rozsahu (`detail` je správa).

Hlavičky odpovede

RateLimit-Policy
Platné limity vo formáte návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddelené čiarkami "<name>";q=<quota>;w=<window in seconds>. key je frekvencia požiadaviek kľúča API (kvóta je nárazová špička, okno je čas na jej úplné doplnenie; pre reláciu je to user, bez prihlasovacích údajov ip); minute, day a month sú kvóty organizácie na kalendárnu minútu, deň a mesiac v UTC.
RateLimit
Čo zostáva z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limit najprísnejšej položky v RateLimit-Policy (tej, ktorej zostáva najmenej požiadaviek).
X-RateLimit-Remaining
Počet požiadaviek, ktoré zostávajú v rámci najprísnejšieho limitu.
X-RateLimit-Reset
Počet sekúnd do obnovenia najprísnejšieho limitu.

application/json

Objekt: Error

429Príliš veľa požiadaviek (`api.rate_limited`), vyčerpaná kvóta organizácie na minútu, deň alebo mesiac (`api.quota_exceeded`; `error.details` obsahuje `quota`, `limit` a `reset_at`), dosiahnutý limit organizácie alebo zaneprázdnená služba odpovedí (`answers.engine_busy`). Počkajte čas uvedený v hlavičke `Retry-After`.

Hlavičky odpovede

Retry-After
Počet sekúnd, ktoré treba počkať pred opakovaním požiadavky.
RateLimit-Policy
Platné limity vo formáte návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddelené čiarkami "<name>";q=<quota>;w=<window in seconds>. key je frekvencia požiadaviek kľúča API (kvóta je nárazová špička, okno je čas na jej úplné doplnenie; pre reláciu je to user, bez prihlasovacích údajov ip); minute, day a month sú kvóty organizácie na kalendárnu minútu, deň a mesiac v UTC.
RateLimit
Čo zostáva z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limit najprísnejšej položky v RateLimit-Policy (tej, ktorej zostáva najmenej požiadaviek).
X-RateLimit-Remaining
Počet požiadaviek, ktoré zostávajú v rámci najprísnejšieho limitu.
X-RateLimit-Reset
Počet sekúnd do obnovenia najprísnejšieho limitu.

application/json

Objekt: Error

Chybové kódy

Kódy, ktoré táto operácia môže vrátiť v error.code, okrem všeobecných kódov každej požiadavky.

Bezpečné opakovanie

S každou požiadavkou POST a PATCH odošlite hlavičku Idempotency-Key (napríklad UUID). Opakovaná požiadavka s rovnakým kľúčom do 24 hodín vráti uloženú odpoveď namiesto toho, aby sa požiadavka vykonala znova.

Limity frekvencie

Odpovede obsahujú hlavičky RateLimit a RateLimit-Policy a staršie X-RateLimit-Limit, X-RateLimit-Remaining a X-RateLimit-Reset. Odpoveď 429 má hlavičku Retry-After v sekundách: počkajte a požiadavku zopakujte.

← cards · Referencia 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"

Vyskúšať

Kľúč API

Kľúč zostáva v pamäti tejto karty prehliadača a odosiela sa len na https://api.sursa.com.

Požiadavky pracujú so skutočnými údajmi vašej organizácie.

Idempotency-Key header

X-View-As header

card_id path *

Idempotency-Key

Ak je pole prázdne, pre každú požiadavku sa vygeneruje nový kľúč.

Telo požiadavky (JSON)