PATCH/v1/cards/{card_id}

Kaardi muutmine

update_card

Autentimine

Saatke API-võti päises Authorization: Authorization: Bearer <võti>.

Teeparameetrid

card_idstringkohustuslik

Päiseparameetrid

Idempotency-Keystring
Võti kirjutamistoimingu turvaliseks kordamiseks: 1–255 prinditavat ASCII-märki; soovitatav on UUID v4 iga loogilise toimingu kohta. Kordus sama võtmega 24 tunni jooksul ei käivita toimingut uuesti: tagastatakse salvestatud vastus (olek, päised ja keha) päisega Idempotency-Replayed: true. Sama võti teise meetodi, tee, Content-Type või kehaga tagastab 409 api.idempotency_mismatch; kuni esimene päring veel töötab, tagastatakse 409 api.idempotency_in_progress koos päisega Retry-After: 1. Pärast vastust 5xx või 429 võti vabastatakse ja kordus käivitab toimingu uuesti. Võti kehtib organisatsiooni ja päringu tegija piires (API-võti, kasutaja või kohandatud allika võti).
length ≥ 1, length ≤ 255
X-View-Asstring
Ainult rolliga admin API-võtmetele. Teeb päringu andmeprofiili <profile>[:viewer|verifier|editor] nimel, näiteks employee:viewer. Paigaldusvõti seda päist kasutada ei saa (403).

Küpsiseparameetrid

kb_view_asstring
Seansi režiimi „View as“ küpsis. POST /auth/view-as määrab selle ja DELETE /auth/view-as kustutab selle.

Päringu keha

application/json

Objekt: CardUpdate

external_idstring | null
Määrab või muudab kaardi external_id; "" või null eemaldab selle. Kui seda kasutab organisatsiooni teine kaart, tagastab päring vastuse 409 cards.external_id_taken. Allikakaardi external_id ei muutu (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

Vastused

200Edukas vastus

Vastuse päised

RateLimit-Policy
Kehtivad piirangud IETF-i mustandi draft-ietf-httpapi-ratelimit-headers vormingus: komadega eraldatud elemendid "<name>";q=<quota>;w=<window in seconds>. key on API-võtme päringusagedus (kvoot on tipuvaru, ajaaken on aeg selle täielikuks taastumiseks; seansi puhul on see user, ilma autentimisandmeteta ip); minute, day ja month on organisatsiooni kvoodid kalendriminutile, -päevale ja -kuule UTC järgi.
RateLimit
Iga päises RateLimit-Policy oleva piirangu jääk: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Päises RateLimit-Policy oleva rangeima kirje limiit (selle, millel on kõige vähem päringuid järel).
X-RateLimit-Remaining
Rangeima piirangu järgi järelejäänud päringud.
X-RateLimit-Reset
Sekundid rangeima piirangu lähtestumiseni.
Idempotency-Replayed
true tähendab, et vastus esitati uuesti selle Idempotency-Key jaoks salvestatud vastusest: toimingut uuesti ei käivitatud.

application/json

Objekt: Card

expandedCardExpanded
permissionsObjectPermissionList
accessstring
Lubatud väärtused: wholepartial
access_contactstring
Kelle poole juurdepääsu saamiseks pöörduda (ainult kui access=partial).
aclobject
Väljad
- verifybooleankohustuslik
- writebooleankohustuslik
categorystringkohustuslik
category_confidencenumber | nullkohustuslik
category_lockedbooleankohustuslik
category_reviewbooleankohustuslik
category_sourceCategorySource | nullkohustuslik
collectionstringkohustuslik
collection_idintegerkohustuslik
collection_titlestring
commentsarray of CardComment
content_jsonContentJSON | null
Viimase avaldatud versiooni redaktori sisu. Väli võib puududa; sel juhul saate redaktori sisu mustandist (POST /v1/drafts koos väljaga card_id).
editing_lockEditingLock | null
Aktiivne redigeerimislukk. Väli võib puududa; sel juhul saab redaktor teada, kellel lukk on, vastusest 409 cards.locked toimingule POST /v1/cards/{card_id}/lock.
created_atstring (date-time)kohustuslik
days_since_verifiedintegerkohustuslik
errorstring | nullkohustuslik
eventsarray of CardEvent
feedback_negintegerkohustuslik
feedback_posintegerkohustuslik
foldersarray of CardFolderRef
Ainult kaartide loendis: kaustad, mis kaarti sisaldavad (kasutajale nähtavad), koos nende teedega kogu juurest. Tühi loend tähendab, et kaart ei ole üheski kaustas.
has_tablesboolean
Ainult kaartide loendis.
hidden_partsboolean
idstringkohustuslik
jobJob | null
kindCardKindkohustuslik
org_idintegerkohustuslik
owner_activeboolean | null
owner_idinteger | nullkohustuslik
owner_namestring | nullkohustuslik
pagesinteger | nullkohustuslik
parserstring | nullkohustuslik
Dokumendi parser neutraalse koodina: document (täielik struktuur: lehed, pealkirjad, tabelid, skannitud lehed), pdf (PDF-i tekstikiht), docx, xlsx, csv, markdown, html, text. Loend võib täieneda.
partsarray of CardPartkohustuslik
sensitivebooleankohustuslik
sha256string | nullkohustuslik
sizeintegerkohustuslik
snoozed_atstring (date-time) | null
snoozed_byinteger | null
snoozed_untilstring | null
source_changedbooleankohustuslik
source_pathstring | nullkohustuslik
source_urlstring | nullkohustuslik
statusstringkohustuslik
Lubatud väärtused: processingreadyerrorarchived
tablesarray of CardTable
tagsarray of stringkohustuslik
titlestringkohustuslik
trustnumberkohustuslik
trust_if_verifiednumber
trust_partsTrustPartskohustuslik
updated_atstring (date-time)kohustuslik
verificationVerificationkohustuslik
verified_atstring (date-time) | nullkohustuslik
verified_byinteger | nullkohustuslik
verified_by_namestring | null
verifier_idsarray of integerkohustuslik
verifiersarray of object
Väljad
- activebooleankohustuslik
- idintegerkohustuslik
- namestringkohustuslik
verify_interval_daysintegerkohustuslik
versionintegerkohustuslik
versionsarray of CardVersion
source_archiveArchiveSource
created_byinteger | null
manual_optionsobject
Parsimise käsitsi seaded (eelvaade).
doc_kindDocKind | null
Dokumendi tüüp. null, kui tüüp ei ole määratud (näiteks kaartidel, mis indekseeriti enne dokumenditüüpide kasutuselevõttu).
doc_kind_confidencenumber | null
Dokumendi tüübi kindlusaste vahemikus 0 kuni 1.
doc_kind_sourcestring | null
Mis tüübi määras: reeglid (rules), kasutaja (manual) või automaatne liigitamine. Loend võib täieneda: käsitlege tundmatut väärtust automaatse liigitamisena.
Lubatud väärtused: rulesmanualnull
invoiceDocInvoiceExtraction | null
Arve, kreeditarve või kviitungi väljad (ainult nende tüüpide puhul ja ainult kaardil, mitte loendis). null, kui teil puudub juurdepääs kogu dokumendile, sest väljad eraldatakse kogu dokumendist.
warningsarray of ReviewWarning
Dokumendi parsimise hoiatused (ReviewWarning; ainult kaardil, mitte loendis).
enrichmentCardEnrichmentStatus | null
Rikastamise olek (ainult kaardil, mitte loendis). Dokumendi tüüp, arve väljad ja finantskirjed lisatakse taustal pärast indekseerimist ning neid võidakse hiljem uuesti arvutada; need ilmuvad kaardile, kui on valmis. null tähendab, et olek ei ole saadaval (kaart indekseeriti ilma taustal rikastamiseta).
external_idstring | null
Kaardi ID integraatori süsteemis. See on organisatsioonis unikaalne kaartide seas, mis ei pärine allikatest; null tähendab, et see ei ole määratud. /v1/cards-by-external-id/{external_id} loeb ja asendab kaardi selle järgi.
length ≤ 512
metadataMetadata

400Päring on vigane: parameetri väärtus või objekti olek ei võimalda toimingut (`detail` on teade).

Vastuse päised

RateLimit-Policy
Kehtivad piirangud IETF-i mustandi draft-ietf-httpapi-ratelimit-headers vormingus: komadega eraldatud elemendid "<name>";q=<quota>;w=<window in seconds>. key on API-võtme päringusagedus (kvoot on tipuvaru, ajaaken on aeg selle täielikuks taastumiseks; seansi puhul on see user, ilma autentimisandmeteta ip); minute, day ja month on organisatsiooni kvoodid kalendriminutile, -päevale ja -kuule UTC järgi.
RateLimit
Iga päises RateLimit-Policy oleva piirangu jääk: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Päises RateLimit-Policy oleva rangeima kirje limiit (selle, millel on kõige vähem päringuid järel).
X-RateLimit-Remaining
Rangeima piirangu järgi järelejäänud päringud.
X-RateLimit-Reset
Sekundid rangeima piirangu lähtestumiseni.

application/json

Objekt: Error

401Autentimisandmeid ei saadetud (ei seansiküpsist ega API-võtit) või võtit ei leitud.

Vastuse päised

RateLimit-Policy
Kehtivad piirangud IETF-i mustandi draft-ietf-httpapi-ratelimit-headers vormingus: komadega eraldatud elemendid "<name>";q=<quota>;w=<window in seconds>. key on API-võtme päringusagedus (kvoot on tipuvaru, ajaaken on aeg selle täielikuks taastumiseks; seansi puhul on see user, ilma autentimisandmeteta ip); minute, day ja month on organisatsiooni kvoodid kalendriminutile, -päevale ja -kuule UTC järgi.
RateLimit
Iga päises RateLimit-Policy oleva piirangu jääk: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Päises RateLimit-Policy oleva rangeima kirje limiit (selle, millel on kõige vähem päringuid järel).
X-RateLimit-Remaining
Rangeima piirangu järgi järelejäänud päringud.
X-RateLimit-Reset
Sekundid rangeima piirangu lähtestumiseni.

application/json

Objekt: Error

403Toiming ei ole lubatud: rollist ei piisa, puudub juurdepääs kogule või kaardile, päring töötab režiimis „View as“ või organisatsioon on peatatud või kustutatud (`detail` on objekt väärtusega `code: org_suspended | org_deleted`).

Vastuse päised

RateLimit-Policy
Kehtivad piirangud IETF-i mustandi draft-ietf-httpapi-ratelimit-headers vormingus: komadega eraldatud elemendid "<name>";q=<quota>;w=<window in seconds>. key on API-võtme päringusagedus (kvoot on tipuvaru, ajaaken on aeg selle täielikuks taastumiseks; seansi puhul on see user, ilma autentimisandmeteta ip); minute, day ja month on organisatsiooni kvoodid kalendriminutile, -päevale ja -kuule UTC järgi.
RateLimit
Iga päises RateLimit-Policy oleva piirangu jääk: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Päises RateLimit-Policy oleva rangeima kirje limiit (selle, millel on kõige vähem päringuid järel).
X-RateLimit-Remaining
Rangeima piirangu järgi järelejäänud päringud.
X-RateLimit-Reset
Sekundid rangeima piirangu lähtestumiseni.

application/json

Objekt: Error

404Objekti ei ole olemas või see ei ole teile kättesaadav. API ei kinnita piiratud juurdepääsuga objekti olemasolu.

Vastuse päised

RateLimit-Policy
Kehtivad piirangud IETF-i mustandi draft-ietf-httpapi-ratelimit-headers vormingus: komadega eraldatud elemendid "<name>";q=<quota>;w=<window in seconds>. key on API-võtme päringusagedus (kvoot on tipuvaru, ajaaken on aeg selle täielikuks taastumiseks; seansi puhul on see user, ilma autentimisandmeteta ip); minute, day ja month on organisatsiooni kvoodid kalendriminutile, -päevale ja -kuule UTC järgi.
RateLimit
Iga päises RateLimit-Policy oleva piirangu jääk: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Päises RateLimit-Policy oleva rangeima kirje limiit (selle, millel on kõige vähem päringuid järel).
X-RateLimit-Remaining
Rangeima piirangu järgi järelejäänud päringud.
X-RateLimit-Reset
Sekundid rangeima piirangu lähtestumiseni.

application/json

Objekt: Error

422Valideerimisviga: keha või parameetrid ei vasta skeemile (`detail` on valideerimisvigade loend) või parameetri väärtus on lubatud vahemikust väljas (`detail` on teade).

Vastuse päised

RateLimit-Policy
Kehtivad piirangud IETF-i mustandi draft-ietf-httpapi-ratelimit-headers vormingus: komadega eraldatud elemendid "<name>";q=<quota>;w=<window in seconds>. key on API-võtme päringusagedus (kvoot on tipuvaru, ajaaken on aeg selle täielikuks taastumiseks; seansi puhul on see user, ilma autentimisandmeteta ip); minute, day ja month on organisatsiooni kvoodid kalendriminutile, -päevale ja -kuule UTC järgi.
RateLimit
Iga päises RateLimit-Policy oleva piirangu jääk: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Päises RateLimit-Policy oleva rangeima kirje limiit (selle, millel on kõige vähem päringuid järel).
X-RateLimit-Remaining
Rangeima piirangu järgi järelejäänud päringud.
X-RateLimit-Reset
Sekundid rangeima piirangu lähtestumiseni.

application/json

Objekt: Error

429Liiga palju päringuid (`api.rate_limited`), organisatsiooni minuti-, päeva- või kuukvoot on ära kasutatud (`api.quota_exceeded`; `error.details` sisaldab välju `quota`, `limit` ja `reset_at`), organisatsiooni limiit on täis või vastuseteenus on hõivatud (`answers.engine_busy`). Oodake päises `Retry-After` antud aeg.

Vastuse päised

Retry-After
Sekundite arv, mida oodata enne päringu kordamist.
RateLimit-Policy
Kehtivad piirangud IETF-i mustandi draft-ietf-httpapi-ratelimit-headers vormingus: komadega eraldatud elemendid "<name>";q=<quota>;w=<window in seconds>. key on API-võtme päringusagedus (kvoot on tipuvaru, ajaaken on aeg selle täielikuks taastumiseks; seansi puhul on see user, ilma autentimisandmeteta ip); minute, day ja month on organisatsiooni kvoodid kalendriminutile, -päevale ja -kuule UTC järgi.
RateLimit
Iga päises RateLimit-Policy oleva piirangu jääk: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Päises RateLimit-Policy oleva rangeima kirje limiit (selle, millel on kõige vähem päringuid järel).
X-RateLimit-Remaining
Rangeima piirangu järgi järelejäänud päringud.
X-RateLimit-Reset
Sekundid rangeima piirangu lähtestumiseni.

application/json

Objekt: Error

Veakoodid

Koodid, mida see lõpp-punkt võib lisaks iga päringu üldistele koodidele tagastada väljal error.code.

Turvalised korduskatsed

Saatke iga POST- ja PATCH-päringuga päis Idempotency-Key (näiteks UUID). Sama võtmega korduskatse 24 tunni jooksul tagastab salvestatud vastuse ega käivita päringut uuesti.

Sageduspiirangud

Vastustes on päised RateLimit ja RateLimit-Policy ning varasemad X-RateLimit-Limit, X-RateLimit-Remaining ja X-RateLimit-Reset. Vastuses 429 on päis Retry-After sekundites: oodake ja proovige uuesti.

← cards · API teatmik

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"

Proovi

API-võti

Võti jääb ainult selle vahekaardi mällu ja see saadetakse üksnes aadressile https://api.sursa.com.

Päringud muudavad teie organisatsiooni päris andmeid.

Idempotency-Key header

X-View-As header

card_id path *

Idempotency-Key

Kui väli on tühi, luuakse iga päringu jaoks uus võti.

Päringu keha (JSON)