PATCH/v1/cards/{card_id}

Perbarui kartu

update_card

Autentikasi

Kirim kunci API di header Authorization: Authorization: Bearer <kunci>.

Parameter path

card_idstringwajib

Parameter header

Idempotency-Keystring
Kunci untuk percobaan ulang penulisan yang aman: 1 hingga 255 karakter ASCII yang dapat dicetak; disarankan satu UUID v4 per operasi logis. Percobaan ulang dengan kunci yang sama dalam 24 jam tidak menjalankan operasi lagi: yang dikembalikan adalah respons tersimpan (status, header, dan isi) dengan header Idempotency-Replayed: true. Kunci yang sama dengan metode, path, Content-Type, atau isi yang berbeda mengembalikan 409 api.idempotency_mismatch; selama permintaan pertama masih berjalan, 409 api.idempotency_in_progress dengan Retry-After: 1. Setelah respons 5xx atau 429, kunci dilepaskan, dan percobaan ulang menjalankan operasi lagi. Kunci berlaku dalam lingkup organisasi dan pemanggil (kunci API, pengguna, atau kunci sumber kustom).
length ≥ 1, length ≤ 255
X-View-Asstring
Hanya untuk kunci API dengan peran admin. Menjalankan permintaan sebagai profil data <profile>[:viewer|verifier|editor], misalnya employee:viewer. Kunci instalasi tidak dapat memakai header ini (403).

Parameter cookie

kb_view_asstring
Cookie mode “View as” (Lihat sebagai) untuk sesi. POST /auth/view-as menetapkannya dan DELETE /auth/view-as menghapusnya.

Isi permintaan

application/json

Objek: CardUpdate

external_idstring | null
Menetapkan atau mengubah external_id kartu; "" atau null menghapusnya. Jika kartu lain di organisasi memakainya, permintaan mengembalikan 409 cards.external_id_taken. external_id kartu dari sumber tidak berubah (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

Respons

200Respons berhasil

Header respons

RateLimit-Policy
Batas yang berlaku, dalam format draf IETF draft-ietf-httpapi-ratelimit-headers: item yang dipisahkan koma "<name>";q=<quota>;w=<window in seconds>. key adalah laju permintaan kunci API (kuotanya adalah lonjakan, jendela waktunya adalah waktu untuk mengisinya kembali sepenuhnya; untuk sesi nilainya user, tanpa kredensial ip); minute, day, dan month adalah kuota organisasi untuk menit, hari, dan bulan kalender dalam UTC.
RateLimit
Sisa setiap batas di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Batas dari entri paling ketat di RateLimit-Policy (entri dengan sisa permintaan paling sedikit).
X-RateLimit-Remaining
Sisa permintaan dalam batas paling ketat.
X-RateLimit-Reset
Detik hingga batas paling ketat direset.
Idempotency-Replayed
true berarti respons ini dikirim ulang dari respons tersimpan untuk Idempotency-Key ini: operasi tidak dijalankan lagi.

application/json

Objek: Card

expandedCardExpanded
permissionsObjectPermissionList
accessstring
Nilai yang diizinkan: wholepartial
access_contactstring
Siapa yang dihubungi untuk akses (hanya jika access=partial).
aclobject
Field
- verifybooleanwajib
- writebooleanwajib
categorystringwajib
category_confidencenumber | nullwajib
category_lockedbooleanwajib
category_reviewbooleanwajib
category_sourceCategorySource | nullwajib
collectionstringwajib
collection_idintegerwajib
collection_titlestring
commentsarray of CardComment
content_jsonContentJSON | null
Konten editor dari versi terbitan terbaru. Field ini bisa tidak ada; dalam hal itu, ambil konten editor dari draf (POST /v1/drafts dengan card_id).
editing_lockEditingLock | null
Kunci penyuntingan yang aktif. Field ini bisa tidak ada; dalam hal itu, editor mengetahui siapa yang memegang kunci dari 409 cards.locked pada POST /v1/cards/{card_id}/lock.
created_atstring (date-time)wajib
days_since_verifiedintegerwajib
errorstring | nullwajib
eventsarray of CardEvent
feedback_negintegerwajib
feedback_posintegerwajib
foldersarray of CardFolderRef
Hanya di daftar kartu: folder yang berisi kartu (yang terlihat oleh pengguna), dengan path-nya dari akar koleksi. Daftar kosong berarti kartu tidak berada di folder mana pun.
has_tablesboolean
Hanya di daftar kartu.
hidden_partsboolean
idstringwajib
jobJob | null
kindCardKindwajib
org_idintegerwajib
owner_activeboolean | null
owner_idinteger | nullwajib
owner_namestring | nullwajib
pagesinteger | nullwajib
parserstring | nullwajib
Pengurai dokumen sebagai kode netral: document (struktur lengkap: halaman, judul, tabel, halaman hasil pindaian), pdf (lapisan teks PDF), docx, xlsx, csv, markdown, html, text. Daftar dapat bertambah.
partsarray of CardPartwajib
sensitivebooleanwajib
sha256string | nullwajib
sizeintegerwajib
snoozed_atstring (date-time) | null
snoozed_byinteger | null
snoozed_untilstring | null
source_changedbooleanwajib
source_pathstring | nullwajib
source_urlstring | nullwajib
statusstringwajib
Nilai yang diizinkan: processingreadyerrorarchived
tablesarray of CardTable
tagsarray of stringwajib
titlestringwajib
trustnumberwajib
trust_if_verifiednumber
trust_partsTrustPartswajib
updated_atstring (date-time)wajib
verificationVerificationwajib
verified_atstring (date-time) | nullwajib
verified_byinteger | nullwajib
verified_by_namestring | null
verifier_idsarray of integerwajib
verifiersarray of object
Field
- activebooleanwajib
- idintegerwajib
- namestringwajib
verify_interval_daysintegerwajib
versionintegerwajib
versionsarray of CardVersion
source_archiveArchiveSource
created_byinteger | null
manual_optionsobject
Pengaturan penguraian manual (pratinjau).
doc_kindDocKind | null
Jenis dokumen. null jika jenisnya belum ditentukan (misalnya untuk kartu yang diindeks sebelum jenis dokumen diperkenalkan).
doc_kind_confidencenumber | null
Tingkat keyakinan atas jenis dokumen, dari 0 hingga 1.
doc_kind_sourcestring | null
Apa yang menentukan jenisnya: aturan (rules), pengguna (manual), atau klasifikasi otomatis. Daftar dapat bertambah: perlakukan nilai yang tidak dikenal sebagai klasifikasi otomatis.
Nilai yang diizinkan: rulesmanualnull
invoiceDocInvoiceExtraction | null
Field faktur, nota kredit, atau kuitansi (hanya untuk jenis ini, dan hanya di kartu, tidak di daftar). null jika Anda tidak memiliki akses ke seluruh dokumen, karena field-nya diekstrak dari seluruh dokumen.
warningsarray of ReviewWarning
Peringatan penguraian dokumen (ReviewWarning; hanya di kartu, tidak di daftar).
enrichmentCardEnrichmentStatus | null
Status pengayaan (hanya di kartu, tidak di daftar). Jenis dokumen, field faktur, dan catatan keuangan ditambahkan di latar belakang setelah pengindeksan dan dapat dihitung ulang nanti; semuanya muncul di kartu setelah siap. null berarti status tidak tersedia (kartu diindeks tanpa pengayaan latar belakang).
external_idstring | null
ID kartu di sistem integrator. Unik di organisasi di antara kartu yang tidak berasal dari sumber; null berarti tidak ditetapkan. /v1/cards-by-external-id/{external_id} membaca dan mengganti kartu berdasarkan ID ini.
length ≤ 512
metadataMetadata

400Permintaan tidak valid: nilai parameter atau status objek tidak memungkinkan tindakan ini (`detail` berisi pesan).

Header respons

RateLimit-Policy
Batas yang berlaku, dalam format draf IETF draft-ietf-httpapi-ratelimit-headers: item yang dipisahkan koma "<name>";q=<quota>;w=<window in seconds>. key adalah laju permintaan kunci API (kuotanya adalah lonjakan, jendela waktunya adalah waktu untuk mengisinya kembali sepenuhnya; untuk sesi nilainya user, tanpa kredensial ip); minute, day, dan month adalah kuota organisasi untuk menit, hari, dan bulan kalender dalam UTC.
RateLimit
Sisa setiap batas di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Batas dari entri paling ketat di RateLimit-Policy (entri dengan sisa permintaan paling sedikit).
X-RateLimit-Remaining
Sisa permintaan dalam batas paling ketat.
X-RateLimit-Reset
Detik hingga batas paling ketat direset.

application/json

Objek: Error

401Kredensial tidak dikirim (baik cookie sesi maupun kunci API), atau kunci tidak ditemukan.

Header respons

RateLimit-Policy
Batas yang berlaku, dalam format draf IETF draft-ietf-httpapi-ratelimit-headers: item yang dipisahkan koma "<name>";q=<quota>;w=<window in seconds>. key adalah laju permintaan kunci API (kuotanya adalah lonjakan, jendela waktunya adalah waktu untuk mengisinya kembali sepenuhnya; untuk sesi nilainya user, tanpa kredensial ip); minute, day, dan month adalah kuota organisasi untuk menit, hari, dan bulan kalender dalam UTC.
RateLimit
Sisa setiap batas di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Batas dari entri paling ketat di RateLimit-Policy (entri dengan sisa permintaan paling sedikit).
X-RateLimit-Remaining
Sisa permintaan dalam batas paling ketat.
X-RateLimit-Reset
Detik hingga batas paling ketat direset.

application/json

Objek: Error

403Tindakan tidak diizinkan: peran tidak memadai, tidak ada akses ke koleksi atau kartu, permintaan berjalan dalam mode “View as”, atau organisasi ditangguhkan atau dihapus (`detail` adalah objek dengan `code: org_suspended | org_deleted`).

Header respons

RateLimit-Policy
Batas yang berlaku, dalam format draf IETF draft-ietf-httpapi-ratelimit-headers: item yang dipisahkan koma "<name>";q=<quota>;w=<window in seconds>. key adalah laju permintaan kunci API (kuotanya adalah lonjakan, jendela waktunya adalah waktu untuk mengisinya kembali sepenuhnya; untuk sesi nilainya user, tanpa kredensial ip); minute, day, dan month adalah kuota organisasi untuk menit, hari, dan bulan kalender dalam UTC.
RateLimit
Sisa setiap batas di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Batas dari entri paling ketat di RateLimit-Policy (entri dengan sisa permintaan paling sedikit).
X-RateLimit-Remaining
Sisa permintaan dalam batas paling ketat.
X-RateLimit-Reset
Detik hingga batas paling ketat direset.

application/json

Objek: Error

404Objek tidak ada atau tidak tersedia bagi Anda. API tidak mengonfirmasi keberadaan objek yang dibatasi.

Header respons

RateLimit-Policy
Batas yang berlaku, dalam format draf IETF draft-ietf-httpapi-ratelimit-headers: item yang dipisahkan koma "<name>";q=<quota>;w=<window in seconds>. key adalah laju permintaan kunci API (kuotanya adalah lonjakan, jendela waktunya adalah waktu untuk mengisinya kembali sepenuhnya; untuk sesi nilainya user, tanpa kredensial ip); minute, day, dan month adalah kuota organisasi untuk menit, hari, dan bulan kalender dalam UTC.
RateLimit
Sisa setiap batas di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Batas dari entri paling ketat di RateLimit-Policy (entri dengan sisa permintaan paling sedikit).
X-RateLimit-Remaining
Sisa permintaan dalam batas paling ketat.
X-RateLimit-Reset
Detik hingga batas paling ketat direset.

application/json

Objek: Error

422Error validasi: isi atau parameter tidak sesuai dengan skema (`detail` berisi daftar error validasi), atau nilai parameter berada di luar rentang (`detail` berisi pesan).

Header respons

RateLimit-Policy
Batas yang berlaku, dalam format draf IETF draft-ietf-httpapi-ratelimit-headers: item yang dipisahkan koma "<name>";q=<quota>;w=<window in seconds>. key adalah laju permintaan kunci API (kuotanya adalah lonjakan, jendela waktunya adalah waktu untuk mengisinya kembali sepenuhnya; untuk sesi nilainya user, tanpa kredensial ip); minute, day, dan month adalah kuota organisasi untuk menit, hari, dan bulan kalender dalam UTC.
RateLimit
Sisa setiap batas di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Batas dari entri paling ketat di RateLimit-Policy (entri dengan sisa permintaan paling sedikit).
X-RateLimit-Remaining
Sisa permintaan dalam batas paling ketat.
X-RateLimit-Reset
Detik hingga batas paling ketat direset.

application/json

Objek: Error

429Terlalu banyak permintaan (`api.rate_limited`), kuota organisasi untuk menit, hari, atau bulan sudah habis (`api.quota_exceeded`; `error.details` berisi `quota`, `limit`, dan `reset_at`), batas organisasi tercapai, atau layanan jawaban sedang sibuk (`answers.engine_busy`). Tunggu selama waktu di header `Retry-After`.

Header respons

Retry-After
Jumlah detik yang perlu ditunggu sebelum Anda mencoba ulang permintaan.
RateLimit-Policy
Batas yang berlaku, dalam format draf IETF draft-ietf-httpapi-ratelimit-headers: item yang dipisahkan koma "<name>";q=<quota>;w=<window in seconds>. key adalah laju permintaan kunci API (kuotanya adalah lonjakan, jendela waktunya adalah waktu untuk mengisinya kembali sepenuhnya; untuk sesi nilainya user, tanpa kredensial ip); minute, day, dan month adalah kuota organisasi untuk menit, hari, dan bulan kalender dalam UTC.
RateLimit
Sisa setiap batas di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Batas dari entri paling ketat di RateLimit-Policy (entri dengan sisa permintaan paling sedikit).
X-RateLimit-Remaining
Sisa permintaan dalam batas paling ketat.
X-RateLimit-Reset
Detik hingga batas paling ketat direset.

application/json

Objek: Error

Kode error

Kode yang dapat dikembalikan endpoint ini di error.code, selain kode umum yang berlaku untuk setiap permintaan.

Percobaan ulang yang aman

Kirim header Idempotency-Key (misalnya UUID) bersama setiap POST dan PATCH. Percobaan ulang dengan kunci yang sama dalam 24 jam mengembalikan respons yang tersimpan alih-alih menjalankan permintaan lagi.

Batas laju

Respons berisi header RateLimit dan RateLimit-Policy serta header lama X-RateLimit-Limit, X-RateLimit-Remaining, dan X-RateLimit-Reset. Respons 429 berisi Retry-After dalam detik: tunggu, lalu coba lagi.

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

Coba

Kunci API

Kunci hanya disimpan di memori tab ini dan hanya dikirim ke https://api.sursa.com.

Permintaan bekerja pada data asli organisasi Anda.

Idempotency-Key header

X-View-As header

card_id path *

Idempotency-Key

Jika kosong, kunci baru dibuat untuk setiap permintaan.

Isi permintaan (JSON)