PATCH/v1/cards/{card_id}

Atnaujinti kortelę

update_card

Autentifikavimas

Siųskite API raktą antraštėje Authorization: Authorization: Bearer <raktas>.

Kelio parametrai

card_idstringprivalomas

Antraštės parametrai

Idempotency-Keystring
Raktas saugiam rašymo operacijos pakartojimui: nuo 1 iki 255 spausdinamų ASCII simbolių; rekomenduojamas atskiras UUID v4 kiekvienai loginei operacijai. Pakartojus užklausą su tuo pačiu raktu per 24 valandas, operacija iš naujo nevykdoma: grąžinamas išsaugotas atsakas (būsena, antraštės ir turinys) su antrašte Idempotency-Replayed: true. Tas pats raktas su kitu metodu, keliu, Content-Type ar turiniu grąžina 409 api.idempotency_mismatch; kol pirmoji užklausa dar vykdoma – 409 api.idempotency_in_progress su Retry-After: 1. Po 5xx ar 429 atsako raktas atlaisvinamas, ir pakartojimas operaciją vykdo iš naujo. Raktas galioja organizacijos ir iškvietėjo (API rakto, naudotojo arba pasirinktinio šaltinio rakto) ribose.
length ≥ 1, length ≤ 255
X-View-Asstring
Tik API raktams su vaidmeniu admin. Užklausa vykdoma duomenų profilio <profile>[:viewer|verifier|editor] vardu, pvz., employee:viewer. Diegimo raktas šios antraštės naudoti negali (403).

Slapuko parametrai

kb_view_asstring
Režimo „View as“ (žiūrėti kaip) sesijos slapukas. POST /auth/view-as jį nustato, o DELETE /auth/view-as išvalo.

Užklausos turinys

application/json

Objektas: CardUpdate

external_idstring | null
Nustato arba pakeičia kortelės external_id; "" arba null jį pašalina. Jei jį naudoja kita organizacijos kortelė, užklausa grąžina 409 cards.external_id_taken. Šaltinio kortelės external_id nesikeičia (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

Atsakai

200Sėkmingas atsakas

Atsako antraštės

RateLimit-Policy
Galiojantys limitai IETF juodraščio draft-ietf-httpapi-ratelimit-headers formatu: kableliais atskirti elementai "<name>";q=<quota>;w=<window in seconds>. key – API rakto užklausų dažnis (kvota – pliūpsnis, laiko langas – laikas, per kurį kvota visiškai atsistato; sesijai tai user, be prisijungimo duomenų – ip); minute, day ir month – organizacijos kvotos kalendorinei minutei, dienai ir mėnesiui pagal UTC.
RateLimit
Kiek liko kiekvieno RateLimit-Policy limito: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Griežčiausio RateLimit-Policy įrašo (kuriame liko mažiausiai užklausų) limitas.
X-RateLimit-Remaining
Likusių užklausų skaičius pagal griežčiausią limitą.
X-RateLimit-Reset
Sekundės iki griežčiausio limito atsistatymo.
Idempotency-Replayed
true – atsakas pakartotas iš šiam Idempotency-Key išsaugoto atsako: operacija iš naujo nevykdyta.

application/json

Objektas: Card

expandedCardExpanded
permissionsObjectPermissionList
accessstring
Leidžiamos reikšmės: wholepartial
access_contactstring
Į ką kreiptis dėl prieigos (tik kai access=partial).
aclobject
Laukai
- verifybooleanprivalomas
- writebooleanprivalomas
categorystringprivalomas
category_confidencenumber | nullprivalomas
category_lockedbooleanprivalomas
category_reviewbooleanprivalomas
category_sourceCategorySource | nullprivalomas
collectionstringprivalomas
collection_idintegerprivalomas
collection_titlestring
commentsarray of CardComment
content_jsonContentJSON | null
Naujausios paskelbtos versijos redaktoriaus turinys. Lauko gali nebūti; tada redaktoriaus turinį gaukite iš juodraščio (POST /v1/drafts su card_id).
editing_lockEditingLock | null
Aktyvus redagavimo užraktas. Lauko gali nebūti; tada redaktorius sužino, kas laiko užraktą, iš atsako 409 cards.locked į POST /v1/cards/{card_id}/lock.
created_atstring (date-time)privalomas
days_since_verifiedintegerprivalomas
errorstring | nullprivalomas
eventsarray of CardEvent
feedback_negintegerprivalomas
feedback_posintegerprivalomas
foldersarray of CardFolderRef
Tik kortelių sąraše: aplankai, kuriuose yra kortelė (tie, kuriuos mato naudotojas), su keliais nuo rinkinio šaknies. Tuščias sąrašas reiškia, kad kortelės nėra jokiame aplanke.
has_tablesboolean
Tik kortelių sąraše.
hidden_partsboolean
idstringprivalomas
jobJob | null
kindCardKindprivalomas
org_idintegerprivalomas
owner_activeboolean | null
owner_idinteger | nullprivalomas
owner_namestring | nullprivalomas
pagesinteger | nullprivalomas
parserstring | nullprivalomas
Dokumento nuskaitymo priemonė kaip neutralus kodas: document (visa struktūra: puslapiai, antraštės, lentelės, nuskenuoti puslapiai), pdf (PDF teksto sluoksnis), docx, xlsx, csv, markdown, html, text. Sąrašas gali būti papildytas.
partsarray of CardPartprivalomas
sensitivebooleanprivalomas
sha256string | nullprivalomas
sizeintegerprivalomas
snoozed_atstring (date-time) | null
snoozed_byinteger | null
snoozed_untilstring | null
source_changedbooleanprivalomas
source_pathstring | nullprivalomas
source_urlstring | nullprivalomas
statusstringprivalomas
Leidžiamos reikšmės: processingreadyerrorarchived
tablesarray of CardTable
tagsarray of stringprivalomas
titlestringprivalomas
trustnumberprivalomas
trust_if_verifiednumber
trust_partsTrustPartsprivalomas
updated_atstring (date-time)privalomas
verificationVerificationprivalomas
verified_atstring (date-time) | nullprivalomas
verified_byinteger | nullprivalomas
verified_by_namestring | null
verifier_idsarray of integerprivalomas
verifiersarray of object
Laukai
- activebooleanprivalomas
- idintegerprivalomas
- namestringprivalomas
verify_interval_daysintegerprivalomas
versionintegerprivalomas
versionsarray of CardVersion
source_archiveArchiveSource
created_byinteger | null
manual_optionsobject
Rankiniai nuskaitymo nustatymai (peržiūra).
doc_kindDocKind | null
Dokumento tipas. null, jei tipas nenustatytas (pavyzdžiui, kortelėms, indeksuotoms dar prieš atsirandant dokumentų tipams).
doc_kind_confidencenumber | null
Dokumento tipo užtikrintumas, nuo 0 iki 1.
doc_kind_sourcestring | null
Kas nustatė tipą: taisyklės (rules), naudotojas (manual) ar automatinis klasifikavimas. Sąrašas gali būti papildytas: nežinomą reikšmę laikykite automatiniu klasifikavimu.
Leidžiamos reikšmės: rulesmanualnull
invoiceDocInvoiceExtraction | null
Sąskaitos faktūros, kreditinės sąskaitos faktūros arba kvito laukai (tik šiems tipams ir tik kortelėje, ne sąraše). null, jei neturite prieigos prie viso dokumento, nes laukai išgaunami iš viso dokumento.
warningsarray of ReviewWarning
Dokumento nuskaitymo įspėjimai (ReviewWarning; tik kortelėje, ne sąraše).
enrichmentCardEnrichmentStatus | null
Papildymo būsena (tik kortelėje, ne sąraše). Dokumento tipas, sąskaitos faktūros laukai ir finansiniai įrašai pridedami fone po indeksavimo ir vėliau gali būti perskaičiuoti; kortelėje jie atsiranda, kai yra paruošti. null reiškia, kad būsenos nėra (kortelė indeksuota be papildymo fone).
external_idstring | null
Kortelės ID integratoriaus sistemoje. Jis unikalus organizacijoje tarp kortelių, kurios nėra iš šaltinių; null reiškia, kad jis nenustatytas. /v1/cards-by-external-id/{external_id} pagal jį skaito ir pakeičia kortelę.
length ≤ 512
metadataMetadata

400Užklausa netinkama: parametro reikšmė arba objekto būsena neleidžia atlikti veiksmo (`detail` – pranešimas).

Atsako antraštės

RateLimit-Policy
Galiojantys limitai IETF juodraščio draft-ietf-httpapi-ratelimit-headers formatu: kableliais atskirti elementai "<name>";q=<quota>;w=<window in seconds>. key – API rakto užklausų dažnis (kvota – pliūpsnis, laiko langas – laikas, per kurį kvota visiškai atsistato; sesijai tai user, be prisijungimo duomenų – ip); minute, day ir month – organizacijos kvotos kalendorinei minutei, dienai ir mėnesiui pagal UTC.
RateLimit
Kiek liko kiekvieno RateLimit-Policy limito: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Griežčiausio RateLimit-Policy įrašo (kuriame liko mažiausiai užklausų) limitas.
X-RateLimit-Remaining
Likusių užklausų skaičius pagal griežčiausią limitą.
X-RateLimit-Reset
Sekundės iki griežčiausio limito atsistatymo.

application/json

Objektas: Error

401Prisijungimo duomenys neišsiųsti (nei sesijos slapukas, nei API raktas) arba raktas nerastas.

Atsako antraštės

RateLimit-Policy
Galiojantys limitai IETF juodraščio draft-ietf-httpapi-ratelimit-headers formatu: kableliais atskirti elementai "<name>";q=<quota>;w=<window in seconds>. key – API rakto užklausų dažnis (kvota – pliūpsnis, laiko langas – laikas, per kurį kvota visiškai atsistato; sesijai tai user, be prisijungimo duomenų – ip); minute, day ir month – organizacijos kvotos kalendorinei minutei, dienai ir mėnesiui pagal UTC.
RateLimit
Kiek liko kiekvieno RateLimit-Policy limito: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Griežčiausio RateLimit-Policy įrašo (kuriame liko mažiausiai užklausų) limitas.
X-RateLimit-Remaining
Likusių užklausų skaičius pagal griežčiausią limitą.
X-RateLimit-Reset
Sekundės iki griežčiausio limito atsistatymo.

application/json

Objektas: Error

403Veiksmas neleidžiamas: vaidmuo nesuteikia reikiamų teisių, nėra prieigos prie rinkinio ar kortelės, užklausa vykdoma režimu „View as“ arba organizacijos veikla sustabdyta ar organizacija ištrinta (`detail` – objektas su `code: org_suspended | org_deleted`).

Atsako antraštės

RateLimit-Policy
Galiojantys limitai IETF juodraščio draft-ietf-httpapi-ratelimit-headers formatu: kableliais atskirti elementai "<name>";q=<quota>;w=<window in seconds>. key – API rakto užklausų dažnis (kvota – pliūpsnis, laiko langas – laikas, per kurį kvota visiškai atsistato; sesijai tai user, be prisijungimo duomenų – ip); minute, day ir month – organizacijos kvotos kalendorinei minutei, dienai ir mėnesiui pagal UTC.
RateLimit
Kiek liko kiekvieno RateLimit-Policy limito: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Griežčiausio RateLimit-Policy įrašo (kuriame liko mažiausiai užklausų) limitas.
X-RateLimit-Remaining
Likusių užklausų skaičius pagal griežčiausią limitą.
X-RateLimit-Reset
Sekundės iki griežčiausio limito atsistatymo.

application/json

Objektas: Error

404Objekto nėra arba jis jums nepasiekiamas. API nepatvirtina, kad ribotos prieigos objektas egzistuoja.

Atsako antraštės

RateLimit-Policy
Galiojantys limitai IETF juodraščio draft-ietf-httpapi-ratelimit-headers formatu: kableliais atskirti elementai "<name>";q=<quota>;w=<window in seconds>. key – API rakto užklausų dažnis (kvota – pliūpsnis, laiko langas – laikas, per kurį kvota visiškai atsistato; sesijai tai user, be prisijungimo duomenų – ip); minute, day ir month – organizacijos kvotos kalendorinei minutei, dienai ir mėnesiui pagal UTC.
RateLimit
Kiek liko kiekvieno RateLimit-Policy limito: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Griežčiausio RateLimit-Policy įrašo (kuriame liko mažiausiai užklausų) limitas.
X-RateLimit-Remaining
Likusių užklausų skaičius pagal griežčiausią limitą.
X-RateLimit-Reset
Sekundės iki griežčiausio limito atsistatymo.

application/json

Objektas: Error

422Validavimo klaida: turinys ar parametrai neatitinka schemos (`detail` – validavimo klaidų sąrašas) arba parametro reikšmė nepatenka į leistiną intervalą (`detail` – pranešimas).

Atsako antraštės

RateLimit-Policy
Galiojantys limitai IETF juodraščio draft-ietf-httpapi-ratelimit-headers formatu: kableliais atskirti elementai "<name>";q=<quota>;w=<window in seconds>. key – API rakto užklausų dažnis (kvota – pliūpsnis, laiko langas – laikas, per kurį kvota visiškai atsistato; sesijai tai user, be prisijungimo duomenų – ip); minute, day ir month – organizacijos kvotos kalendorinei minutei, dienai ir mėnesiui pagal UTC.
RateLimit
Kiek liko kiekvieno RateLimit-Policy limito: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Griežčiausio RateLimit-Policy įrašo (kuriame liko mažiausiai užklausų) limitas.
X-RateLimit-Remaining
Likusių užklausų skaičius pagal griežčiausią limitą.
X-RateLimit-Reset
Sekundės iki griežčiausio limito atsistatymo.

application/json

Objektas: Error

429Per daug užklausų (`api.rate_limited`), išnaudota organizacijos minutės, dienos ar mėnesio kvota (`api.quota_exceeded`; `error.details` pateikia `quota`, `limit` ir `reset_at`), pasiektas organizacijos limitas arba atsakymų paslauga užimta (`answers.engine_busy`). Palaukite tiek, kiek nurodyta antraštėje `Retry-After`.

Atsako antraštės

Retry-After
Kiek sekundžių palaukti prieš kartojant užklausą.
RateLimit-Policy
Galiojantys limitai IETF juodraščio draft-ietf-httpapi-ratelimit-headers formatu: kableliais atskirti elementai "<name>";q=<quota>;w=<window in seconds>. key – API rakto užklausų dažnis (kvota – pliūpsnis, laiko langas – laikas, per kurį kvota visiškai atsistato; sesijai tai user, be prisijungimo duomenų – ip); minute, day ir month – organizacijos kvotos kalendorinei minutei, dienai ir mėnesiui pagal UTC.
RateLimit
Kiek liko kiekvieno RateLimit-Policy limito: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Griežčiausio RateLimit-Policy įrašo (kuriame liko mažiausiai užklausų) limitas.
X-RateLimit-Remaining
Likusių užklausų skaičius pagal griežčiausią limitą.
X-RateLimit-Reset
Sekundės iki griežčiausio limito atsistatymo.

application/json

Objektas: Error

Klaidų kodai

Kodai, kuriuos ši operacija gali grąžinti lauke error.code, be bendrųjų kodų, galimų bet kuriai užklausai.

Saugūs pakartojimai

Su kiekviena POST ir PATCH užklausa siųskite antraštę Idempotency-Key (pavyzdžiui, UUID). Pakartojus užklausą su tuo pačiu raktu per 24 valandas, grąžinamas išsaugotas atsakas, o užklausa iš naujo nevykdoma.

Užklausų dažnio limitai

Atsakuose yra antraštės RateLimit ir RateLimit-Policy bei ankstesnės X-RateLimit-Limit, X-RateLimit-Remaining ir X-RateLimit-Reset. Atsake 429 yra antraštė Retry-After sekundėmis: palaukite ir pakartokite užklausą.

← cards · API žinynas

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"

Išbandyti

API raktas

Raktas laikomas tik šio skirtuko atmintyje ir siunčiamas tik į https://api.sursa.com.

Užklausos vykdomos su tikrais jūsų organizacijos duomenimis.

Idempotency-Key header

X-View-As header

card_id path *

Idempotency-Key

Jei laukas tuščias, kiekvienai užklausai sugeneruojamas naujas raktas.

Užklausos turinys (JSON)