PATCH/v1/cards/{card_id}

Actualizează o fișă

update_card

Autentificare

Trimiteți o cheie API în antetul Authorization: Authorization: Bearer <cheie>.

Parametri de cale

card_idstringobligatoriu

Parametri de antet

Idempotency-Keystring
Cheie pentru reîncercarea sigură a unei scrieri: 1–255 de caractere ASCII imprimabile; se recomandă un UUID v4 pentru fiecare operație logică. O reîncercare cu aceeași cheie în decurs de 24 de ore nu execută din nou operația: returnează răspunsul salvat (status, antete și corp) cu antetul Idempotency-Replayed: true. Aceeași cheie cu altă metodă, altă cale, alt Content-Type sau alt corp returnează 409 api.idempotency_mismatch; cât timp prima cerere încă rulează – 409 api.idempotency_in_progress cu Retry-After: 1. După un răspuns 5xx sau 429, cheia este eliberată, iar o reîncercare execută din nou operația. Cheia este valabilă în cadrul organizației și al apelantului (cheie API, utilizator sau cheie de sursă personalizată).
length ≥ 1, length ≤ 255
X-View-Asstring
Doar pentru cheile API cu rolul admin. Execută cererea cu profilul de date <profile>[:viewer|verifier|editor], de exemplu employee:viewer. Cheia de instalare nu poate folosi acest antet (403).

Parametri cookie

kb_view_asstring
Cookie-ul modului „View as” (vizualizare ca alt utilizator) pentru o sesiune. POST /auth/view-as îl setează, iar DELETE /auth/view-as îl șterge.

Corpul cererii

application/json

Obiect: CardUpdate

external_idstring | null
Setează sau modifică external_id al fișei; "" sau null îl elimină. Dacă îl folosește o altă fișă a organizației, cererea returnează 409 cards.external_id_taken. external_id al unei fișe dintr-o sursă nu se modifică (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

Răspunsuri

200Răspuns reușit

Antetele răspunsului

RateLimit-Policy
Limitele în vigoare, în formatul proiectului IETF draft-ietf-httpapi-ratelimit-headers: elemente separate prin virgulă "<name>";q=<quota>;w=<window in seconds>. key este frecvența cererilor cheii API (cota este rafala, fereastra este timpul în care rafala se reface complet; pentru o sesiune este user, fără date de autentificare ip); minute, day și month sunt cotele organizației pentru minutul, ziua și luna calendaristice în UTC.
RateLimit
Cât a rămas din fiecare limită din RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limita celei mai stricte intrări din RateLimit-Policy (cea cu cele mai puține cereri rămase).
X-RateLimit-Remaining
Cereri rămase în cadrul celei mai stricte limite.
X-RateLimit-Reset
Secunde până la resetarea celei mai stricte limite.
Idempotency-Replayed
true înseamnă că răspunsul a fost redat din cel salvat pentru această cheie Idempotency-Key: operația nu a rulat din nou.

application/json

Obiect: Card

expandedCardExpanded
permissionsObjectPermissionList
accessstring
Valori permise: wholepartial
access_contactstring
Persoana de contactat pentru acces (doar când access=partial).
aclobject
Câmpuri
- verifybooleanobligatoriu
- writebooleanobligatoriu
categorystringobligatoriu
category_confidencenumber | nullobligatoriu
category_lockedbooleanobligatoriu
category_reviewbooleanobligatoriu
category_sourceCategorySource | nullobligatoriu
collectionstringobligatoriu
collection_idintegerobligatoriu
collection_titlestring
commentsarray of CardComment
content_jsonContentJSON | null
Conținutul din editor al ultimei versiuni publicate. Câmpul poate lipsi; în acest caz, obțineți conținutul din editor dintr-o schiță (POST /v1/drafts cu card_id).
editing_lockEditingLock | null
Blocarea activă pentru editare. Câmpul poate lipsi; în acest caz, editorul află cine deține blocarea din 409 cards.locked la POST /v1/cards/{card_id}/lock.
created_atstring (date-time)obligatoriu
days_since_verifiedintegerobligatoriu
errorstring | nullobligatoriu
eventsarray of CardEvent
feedback_negintegerobligatoriu
feedback_posintegerobligatoriu
foldersarray of CardFolderRef
Doar în lista fișelor: dosarele care conțin fișa (cele vizibile utilizatorului), cu căile lor de la rădăcina colecției. O listă goală înseamnă că fișa nu se află în niciun dosar.
has_tablesboolean
Doar în lista fișelor.
hidden_partsboolean
idstringobligatoriu
jobJob | null
kindCardKindobligatoriu
org_idintegerobligatoriu
owner_activeboolean | null
owner_idinteger | nullobligatoriu
owner_namestring | nullobligatoriu
pagesinteger | nullobligatoriu
parserstring | nullobligatoriu
Analizorul documentului, ca un cod neutru: document (structură completă: pagini, titluri, tabele, pagini scanate), pdf (stratul de text al PDF-ului), docx, xlsx, csv, markdown, html, text. Lista se poate extinde.
partsarray of CardPartobligatoriu
sensitivebooleanobligatoriu
sha256string | nullobligatoriu
sizeintegerobligatoriu
snoozed_atstring (date-time) | null
snoozed_byinteger | null
snoozed_untilstring | null
source_changedbooleanobligatoriu
source_pathstring | nullobligatoriu
source_urlstring | nullobligatoriu
statusstringobligatoriu
Valori permise: processingreadyerrorarchived
tablesarray of CardTable
tagsarray of stringobligatoriu
titlestringobligatoriu
trustnumberobligatoriu
trust_if_verifiednumber
trust_partsTrustPartsobligatoriu
updated_atstring (date-time)obligatoriu
verificationVerificationobligatoriu
verified_atstring (date-time) | nullobligatoriu
verified_byinteger | nullobligatoriu
verified_by_namestring | null
verifier_idsarray of integerobligatoriu
verifiersarray of object
Câmpuri
- activebooleanobligatoriu
- idintegerobligatoriu
- namestringobligatoriu
verify_interval_daysintegerobligatoriu
versionintegerobligatoriu
versionsarray of CardVersion
source_archiveArchiveSource
created_byinteger | null
manual_optionsobject
Setările manuale de analiză a documentului (previzualizare).
doc_kindDocKind | null
Tipul documentului. null dacă tipul nu este determinat (de exemplu, pentru fișele indexate înainte de introducerea tipurilor de documente).
doc_kind_confidencenumber | null
Gradul de certitudine al tipului documentului, de la 0 la 1.
doc_kind_sourcestring | null
Ce a determinat tipul: regulile (rules), un utilizator (manual) sau clasificarea automată. Lista se poate extinde: tratați o valoare necunoscută drept clasificare automată.
Valori permise: rulesmanualnull
invoiceDocInvoiceExtraction | null
Câmpurile unei facturi, ale unei note de credit sau ale unei chitanțe (doar pentru aceste tipuri și doar în fișă, nu în listă). null dacă nu aveți acces la întregul document, deoarece câmpurile se extrag din întregul document.
warningsarray of ReviewWarning
Avertismentele analizei documentului (ReviewWarning; doar în fișă, nu în listă).
enrichmentCardEnrichmentStatus | null
Starea îmbogățirii (doar în fișă, nu în listă). Tipul documentului, câmpurile facturii și înregistrările financiare se adaugă în fundal după indexare și pot fi recalculate ulterior; apar în fișă când sunt gata. null înseamnă că nu există nicio stare (fișa a fost indexată fără îmbogățire în fundal).
external_idstring | null
ID-ul fișei în sistemul integratorului. Este unic în organizație printre fișele care nu provin din surse; null înseamnă că nu este setat. /v1/cards-by-external-id/{external_id} citește și înlocuiește fișa după el.
length ≤ 512
metadataMetadata

400Cererea este invalidă: valoarea unui parametru sau starea obiectului nu permite acțiunea (`detail` este un mesaj).

Antetele răspunsului

RateLimit-Policy
Limitele în vigoare, în formatul proiectului IETF draft-ietf-httpapi-ratelimit-headers: elemente separate prin virgulă "<name>";q=<quota>;w=<window in seconds>. key este frecvența cererilor cheii API (cota este rafala, fereastra este timpul în care rafala se reface complet; pentru o sesiune este user, fără date de autentificare ip); minute, day și month sunt cotele organizației pentru minutul, ziua și luna calendaristice în UTC.
RateLimit
Cât a rămas din fiecare limită din RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limita celei mai stricte intrări din RateLimit-Policy (cea cu cele mai puține cereri rămase).
X-RateLimit-Remaining
Cereri rămase în cadrul celei mai stricte limite.
X-RateLimit-Reset
Secunde până la resetarea celei mai stricte limite.

application/json

Obiect: Error

401Nu au fost trimise date de autentificare (nici cookie de sesiune, nici cheie API) sau cheia nu a fost găsită.

Antetele răspunsului

RateLimit-Policy
Limitele în vigoare, în formatul proiectului IETF draft-ietf-httpapi-ratelimit-headers: elemente separate prin virgulă "<name>";q=<quota>;w=<window in seconds>. key este frecvența cererilor cheii API (cota este rafala, fereastra este timpul în care rafala se reface complet; pentru o sesiune este user, fără date de autentificare ip); minute, day și month sunt cotele organizației pentru minutul, ziua și luna calendaristice în UTC.
RateLimit
Cât a rămas din fiecare limită din RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limita celei mai stricte intrări din RateLimit-Policy (cea cu cele mai puține cereri rămase).
X-RateLimit-Remaining
Cereri rămase în cadrul celei mai stricte limite.
X-RateLimit-Reset
Secunde până la resetarea celei mai stricte limite.

application/json

Obiect: Error

403Acțiunea nu este permisă: rolul este insuficient, nu există acces la colecție sau la fișă, cererea rulează în modul „View as” (vizualizare ca alt utilizator) sau organizația este suspendată ori ștearsă (`detail` este un obiect cu `code: org_suspended | org_deleted`).

Antetele răspunsului

RateLimit-Policy
Limitele în vigoare, în formatul proiectului IETF draft-ietf-httpapi-ratelimit-headers: elemente separate prin virgulă "<name>";q=<quota>;w=<window in seconds>. key este frecvența cererilor cheii API (cota este rafala, fereastra este timpul în care rafala se reface complet; pentru o sesiune este user, fără date de autentificare ip); minute, day și month sunt cotele organizației pentru minutul, ziua și luna calendaristice în UTC.
RateLimit
Cât a rămas din fiecare limită din RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limita celei mai stricte intrări din RateLimit-Policy (cea cu cele mai puține cereri rămase).
X-RateLimit-Remaining
Cereri rămase în cadrul celei mai stricte limite.
X-RateLimit-Reset
Secunde până la resetarea celei mai stricte limite.

application/json

Obiect: Error

404Obiectul nu există sau nu vă este disponibil. API-ul nu confirmă existența unui obiect restricționat.

Antetele răspunsului

RateLimit-Policy
Limitele în vigoare, în formatul proiectului IETF draft-ietf-httpapi-ratelimit-headers: elemente separate prin virgulă "<name>";q=<quota>;w=<window in seconds>. key este frecvența cererilor cheii API (cota este rafala, fereastra este timpul în care rafala se reface complet; pentru o sesiune este user, fără date de autentificare ip); minute, day și month sunt cotele organizației pentru minutul, ziua și luna calendaristice în UTC.
RateLimit
Cât a rămas din fiecare limită din RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limita celei mai stricte intrări din RateLimit-Policy (cea cu cele mai puține cereri rămase).
X-RateLimit-Remaining
Cereri rămase în cadrul celei mai stricte limite.
X-RateLimit-Reset
Secunde până la resetarea celei mai stricte limite.

application/json

Obiect: Error

422Eroare de validare: corpul sau parametrii nu corespund schemei (`detail` este o listă de erori de validare) ori valoarea unui parametru este în afara intervalului permis (`detail` este un mesaj).

Antetele răspunsului

RateLimit-Policy
Limitele în vigoare, în formatul proiectului IETF draft-ietf-httpapi-ratelimit-headers: elemente separate prin virgulă "<name>";q=<quota>;w=<window in seconds>. key este frecvența cererilor cheii API (cota este rafala, fereastra este timpul în care rafala se reface complet; pentru o sesiune este user, fără date de autentificare ip); minute, day și month sunt cotele organizației pentru minutul, ziua și luna calendaristice în UTC.
RateLimit
Cât a rămas din fiecare limită din RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limita celei mai stricte intrări din RateLimit-Policy (cea cu cele mai puține cereri rămase).
X-RateLimit-Remaining
Cereri rămase în cadrul celei mai stricte limite.
X-RateLimit-Reset
Secunde până la resetarea celei mai stricte limite.

application/json

Obiect: Error

429Prea multe cereri (`api.rate_limited`), cota organizației pentru minut, zi sau lună este epuizată (`api.quota_exceeded`; `error.details` conține `quota`, `limit` și `reset_at`), limita organizației este atinsă sau serviciul de răspunsuri este ocupat (`answers.engine_busy`). Așteptați timpul indicat în antetul `Retry-After`.

Antetele răspunsului

Retry-After
Numărul de secunde de așteptat înainte de a reîncerca cererea.
RateLimit-Policy
Limitele în vigoare, în formatul proiectului IETF draft-ietf-httpapi-ratelimit-headers: elemente separate prin virgulă "<name>";q=<quota>;w=<window in seconds>. key este frecvența cererilor cheii API (cota este rafala, fereastra este timpul în care rafala se reface complet; pentru o sesiune este user, fără date de autentificare ip); minute, day și month sunt cotele organizației pentru minutul, ziua și luna calendaristice în UTC.
RateLimit
Cât a rămas din fiecare limită din RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limita celei mai stricte intrări din RateLimit-Policy (cea cu cele mai puține cereri rămase).
X-RateLimit-Remaining
Cereri rămase în cadrul celei mai stricte limite.
X-RateLimit-Reset
Secunde până la resetarea celei mai stricte limite.

application/json

Obiect: Error

Coduri de eroare

Codurile pe care acest endpoint le poate returna în error.code, pe lângă codurile generale ale oricărei cereri.

Reîncercări sigure

Trimiteți un antet Idempotency-Key (de exemplu, un UUID) cu fiecare POST și PATCH. O reîncercare cu aceeași cheie în decurs de 24 de ore returnează răspunsul salvat, fără să execute din nou cererea.

Limite de frecvență

Răspunsurile conțin antetele RateLimit și RateLimit-Policy, precum și antetele anterioare X-RateLimit-Limit, X-RateLimit-Remaining și X-RateLimit-Reset. Un răspuns 429 conține Retry-After în secunde: așteptați și reîncercați.

← cards · Referința 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"

Încercați

Cheie API

Cheia rămâne în memoria acestei file a browserului și este trimisă doar către https://api.sursa.com.

Cererile se execută pe datele reale ale organizației.

Idempotency-Key header

X-View-As header

card_id path *

Idempotency-Key

Dacă acest câmp este gol, pentru fiecare cerere se generează o cheie nouă.

Corpul cererii (JSON)