PATCH/v1/cards/{card_id}

Kartı güncelleme

update_card

Kimlik doğrulama

API anahtarını Authorization başlığında gönderin: Authorization: Bearer <anahtar>.

Yol parametreleri

card_idstringzorunlu

Başlık parametreleri

Idempotency-Keystring
Bir yazma işleminin güvenli yeniden denenmesi için idempotency anahtarı (aynı isteğin tekrarı işlemi ikinci kez çalıştırmaz): 1–255 yazdırılabilir ASCII karakteri; her mantıksal işlem için bir UUID v4 önerilir. 24 saat içinde aynı anahtarla yapılan yeniden deneme işlemi tekrar çalıştırmaz: kaydedilmiş yanıtı (durum, başlıklar ve gövde) Idempotency-Replayed: true başlığıyla döndürür. Aynı anahtar farklı bir yöntem, yol, Content-Type ya da gövdeyle kullanılırsa 409 api.idempotency_mismatch döner; ilk istek hâlâ çalışırken Retry-After: 1 ile birlikte 409 api.idempotency_in_progress döner. 5xx ya da 429 yanıtından sonra anahtar serbest bırakılır ve yeniden deneme işlemi tekrar çalıştırır. Anahtar kuruluşa ve çağırana özgüdür (API anahtarı, kullanıcı ya da özel kaynak anahtarı).
length ≥ 1, length ≤ 255
X-View-Asstring
Yalnızca admin rolündeki API anahtarları için. İsteği <profile>[:viewer|verifier|editor] veri profili adına yapar, örneğin employee:viewer. Kurulum anahtarı bu başlığı kullanamaz (403).

Çerez parametreleri

kb_view_asstring
Bir oturum için “View as” modunun (başka bir kullanıcı gibi görüntüleme) çerezi. POST /auth/view-as bu çerezi ayarlar, DELETE /auth/view-as temizler.

İstek gövdesi

application/json

Nesne: CardUpdate

external_idstring | null
Kartın external_id değerini ayarlar ya da değiştirir; "" ya da null değeri kaldırır. Kuruluşun başka bir kartı bu değeri kullanıyorsa istek 409 cards.external_id_taken döndürür. Kaynak kartının external_id değeri değişmez (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

Yanıtlar

200Başarılı yanıt

Yanıt başlıkları

RateLimit-Policy
Geçerli limitler, IETF taslağı draft-ietf-httpapi-ratelimit-headers biçiminde: virgülle ayrılmış "<name>";q=<quota>;w=<window in seconds> öğeleri. key, API anahtarının istek hızıdır (kota ani artış payıdır, zaman penceresi bu payın tamamen dolma süresidir; oturum için user, kimlik bilgisi olmadan ip); minute, day ve month, kuruluşun UTC’ye göre takvim dakikası, günü ve ayı için kotalarıdır.
RateLimit
RateLimit-Policy içindeki her limitten kalan: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
RateLimit-Policy içindeki en sıkı girdinin limiti (en az istek hakkı kalan girdi).
X-RateLimit-Remaining
En sıkı limitte kalan istek sayısı.
X-RateLimit-Reset
En sıkı limitin sıfırlanmasına kalan saniye.
Idempotency-Replayed
true: yanıt bu Idempotency-Key için kaydedilmiş yanıttan yeniden verildi; işlem tekrar çalışmadı.

application/json

Nesne: Card

expandedCardExpanded
permissionsObjectPermissionList
accessstring
Geçerli değerler: wholepartial
access_contactstring
Erişim için kime başvurulacağı (yalnızca access=partial olduğunda).
aclobject
Alanlar
- verifybooleanzorunlu
- writebooleanzorunlu
categorystringzorunlu
category_confidencenumber | nullzorunlu
category_lockedbooleanzorunlu
category_reviewbooleanzorunlu
category_sourceCategorySource | nullzorunlu
collectionstringzorunlu
collection_idintegerzorunlu
collection_titlestring
commentsarray of CardComment
content_jsonContentJSON | null
Son yayımlanmış sürümün düzenleyici içeriği. Alan bulunmayabilir; bu durumda düzenleyici içeriğini bir taslaktan alın (card_id ile POST /v1/drafts).
editing_lockEditingLock | null
Etkin düzenleme kilidi. Alan bulunmayabilir; bu durumda düzenleyici, kilidin kimde olduğunu POST /v1/cards/{card_id}/lock isteğine dönen 409 cards.locked yanıtından öğrenir.
created_atstring (date-time)zorunlu
days_since_verifiedintegerzorunlu
errorstring | nullzorunlu
eventsarray of CardEvent
feedback_negintegerzorunlu
feedback_posintegerzorunlu
foldersarray of CardFolderRef
Yalnızca kart listesinde: kartı içeren klasörler (kullanıcının görebildikleri), koleksiyon kökünden yollarıyla birlikte. Boş liste, kartın hiçbir klasörde olmadığı anlamına gelir.
has_tablesboolean
Yalnızca kart listesinde.
hidden_partsboolean
idstringzorunlu
jobJob | null
kindCardKindzorunlu
org_idintegerzorunlu
owner_activeboolean | null
owner_idinteger | nullzorunlu
owner_namestring | nullzorunlu
pagesinteger | nullzorunlu
parserstring | nullzorunlu
Nötr kod olarak belge ayrıştırıcısı: document (tam yapı: sayfalar, başlıklar, tablolar, taranmış sayfalar), pdf (PDF’in metin katmanı), docx, xlsx, csv, markdown, html, text. Liste genişleyebilir.
partsarray of CardPartzorunlu
sensitivebooleanzorunlu
sha256string | nullzorunlu
sizeintegerzorunlu
snoozed_atstring (date-time) | null
snoozed_byinteger | null
snoozed_untilstring | null
source_changedbooleanzorunlu
source_pathstring | nullzorunlu
source_urlstring | nullzorunlu
statusstringzorunlu
Geçerli değerler: processingreadyerrorarchived
tablesarray of CardTable
tagsarray of stringzorunlu
titlestringzorunlu
trustnumberzorunlu
trust_if_verifiednumber
trust_partsTrustPartszorunlu
updated_atstring (date-time)zorunlu
verificationVerificationzorunlu
verified_atstring (date-time) | nullzorunlu
verified_byinteger | nullzorunlu
verified_by_namestring | null
verifier_idsarray of integerzorunlu
verifiersarray of object
Alanlar
- activebooleanzorunlu
- idintegerzorunlu
- namestringzorunlu
verify_interval_daysintegerzorunlu
versionintegerzorunlu
versionsarray of CardVersion
source_archiveArchiveSource
created_byinteger | null
manual_optionsobject
Elle ayrıştırma ayarları (önizleme).
doc_kindDocKind | null
Belge türü. Tür belirlenmediyse null (örneğin belge türleri kullanılmaya başlanmadan önce dizinlenmiş kartlarda).
doc_kind_confidencenumber | null
Belge türünün kesinlik düzeyi, 0 ile 1 arasında.
doc_kind_sourcestring | null
Türü neyin belirlediği: kurallar (rules), bir kullanıcı (manual) ya da otomatik sınıflandırma. Liste genişleyebilir: bilinmeyen bir değeri otomatik sınıflandırma olarak değerlendirin.
Geçerli değerler: rulesmanualnull
invoiceDocInvoiceExtraction | null
Fatura, iade faturası ya da makbuz alanları (yalnızca bu türlerde ve yalnızca kartta, listede değil). Alanlar belgenin tamamından çıkarıldığı için belgenin tamamına erişiminiz yoksa null.
warningsarray of ReviewWarning
Belge ayrıştırma uyarıları (ReviewWarning; yalnızca kartta, listede değil).
enrichmentCardEnrichmentStatus | null
Zenginleştirme durumu (yalnızca kartta, listede değil). Belge türü, fatura alanları ve finansal kayıtlar dizinlemeden sonra arka planda eklenir ve daha sonra yeniden hesaplanabilir; hazır olduklarında kartta görünürler. null, durum bilgisi olmadığı anlamına gelir (kart, arka plan zenginleştirmesi olmadan dizinlendi).
external_idstring | null
Kartın entegratörün sistemindeki kimliği. Kaynaklardan gelmeyen kartlar arasında kuruluş içinde benzersizdir; null, ayarlanmadığı anlamına gelir. /v1/cards-by-external-id/{external_id} kartı bu değere göre okur ve değiştirir.
length ≤ 512
metadataMetadata

400İstek geçersiz: bir parametre değeri ya da nesnenin durumu işleme izin vermiyor (`detail` bir iletidir).

Yanıt başlıkları

RateLimit-Policy
Geçerli limitler, IETF taslağı draft-ietf-httpapi-ratelimit-headers biçiminde: virgülle ayrılmış "<name>";q=<quota>;w=<window in seconds> öğeleri. key, API anahtarının istek hızıdır (kota ani artış payıdır, zaman penceresi bu payın tamamen dolma süresidir; oturum için user, kimlik bilgisi olmadan ip); minute, day ve month, kuruluşun UTC’ye göre takvim dakikası, günü ve ayı için kotalarıdır.
RateLimit
RateLimit-Policy içindeki her limitten kalan: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
RateLimit-Policy içindeki en sıkı girdinin limiti (en az istek hakkı kalan girdi).
X-RateLimit-Remaining
En sıkı limitte kalan istek sayısı.
X-RateLimit-Reset
En sıkı limitin sıfırlanmasına kalan saniye.

application/json

Nesne: Error

401Kimlik bilgisi gönderilmedi (ne oturum çerezi ne de API anahtarı) ya da anahtar bulunamadı.

Yanıt başlıkları

RateLimit-Policy
Geçerli limitler, IETF taslağı draft-ietf-httpapi-ratelimit-headers biçiminde: virgülle ayrılmış "<name>";q=<quota>;w=<window in seconds> öğeleri. key, API anahtarının istek hızıdır (kota ani artış payıdır, zaman penceresi bu payın tamamen dolma süresidir; oturum için user, kimlik bilgisi olmadan ip); minute, day ve month, kuruluşun UTC’ye göre takvim dakikası, günü ve ayı için kotalarıdır.
RateLimit
RateLimit-Policy içindeki her limitten kalan: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
RateLimit-Policy içindeki en sıkı girdinin limiti (en az istek hakkı kalan girdi).
X-RateLimit-Remaining
En sıkı limitte kalan istek sayısı.
X-RateLimit-Reset
En sıkı limitin sıfırlanmasına kalan saniye.

application/json

Nesne: Error

403İşleme izin verilmiyor: rol yetersiz, koleksiyona ya da karta erişim yok, istek “View as” modunda çalışıyor ya da kuruluş askıya alınmış veya silinmiş (`detail`, `code: org_suspended | org_deleted` içeren bir nesnedir).

Yanıt başlıkları

RateLimit-Policy
Geçerli limitler, IETF taslağı draft-ietf-httpapi-ratelimit-headers biçiminde: virgülle ayrılmış "<name>";q=<quota>;w=<window in seconds> öğeleri. key, API anahtarının istek hızıdır (kota ani artış payıdır, zaman penceresi bu payın tamamen dolma süresidir; oturum için user, kimlik bilgisi olmadan ip); minute, day ve month, kuruluşun UTC’ye göre takvim dakikası, günü ve ayı için kotalarıdır.
RateLimit
RateLimit-Policy içindeki her limitten kalan: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
RateLimit-Policy içindeki en sıkı girdinin limiti (en az istek hakkı kalan girdi).
X-RateLimit-Remaining
En sıkı limitte kalan istek sayısı.
X-RateLimit-Reset
En sıkı limitin sıfırlanmasına kalan saniye.

application/json

Nesne: Error

404Nesne yok ya da size açık değil. API, erişimi kısıtlı bir nesnenin var olduğunu belli etmez.

Yanıt başlıkları

RateLimit-Policy
Geçerli limitler, IETF taslağı draft-ietf-httpapi-ratelimit-headers biçiminde: virgülle ayrılmış "<name>";q=<quota>;w=<window in seconds> öğeleri. key, API anahtarının istek hızıdır (kota ani artış payıdır, zaman penceresi bu payın tamamen dolma süresidir; oturum için user, kimlik bilgisi olmadan ip); minute, day ve month, kuruluşun UTC’ye göre takvim dakikası, günü ve ayı için kotalarıdır.
RateLimit
RateLimit-Policy içindeki her limitten kalan: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
RateLimit-Policy içindeki en sıkı girdinin limiti (en az istek hakkı kalan girdi).
X-RateLimit-Remaining
En sıkı limitte kalan istek sayısı.
X-RateLimit-Reset
En sıkı limitin sıfırlanmasına kalan saniye.

application/json

Nesne: Error

422Geçerlilik hatası: gövde ya da parametreler şemaya uymuyor (`detail` geçerlilik hatalarının listesidir) ya da bir parametre değeri aralığın dışında (`detail` bir iletidir).

Yanıt başlıkları

RateLimit-Policy
Geçerli limitler, IETF taslağı draft-ietf-httpapi-ratelimit-headers biçiminde: virgülle ayrılmış "<name>";q=<quota>;w=<window in seconds> öğeleri. key, API anahtarının istek hızıdır (kota ani artış payıdır, zaman penceresi bu payın tamamen dolma süresidir; oturum için user, kimlik bilgisi olmadan ip); minute, day ve month, kuruluşun UTC’ye göre takvim dakikası, günü ve ayı için kotalarıdır.
RateLimit
RateLimit-Policy içindeki her limitten kalan: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
RateLimit-Policy içindeki en sıkı girdinin limiti (en az istek hakkı kalan girdi).
X-RateLimit-Remaining
En sıkı limitte kalan istek sayısı.
X-RateLimit-Reset
En sıkı limitin sıfırlanmasına kalan saniye.

application/json

Nesne: Error

429Çok fazla istek (`api.rate_limited`), kuruluşun dakika, gün ya da ay kotası doldu (`api.quota_exceeded`; `error.details` alanında `quota`, `limit` ve `reset_at` bulunur), kuruluşun limitine ulaşıldı ya da yanıt hizmeti meşgul (`answers.engine_busy`). `Retry-After` başlığındaki süre kadar bekleyin.

Yanıt başlıkları

Retry-After
İsteği yeniden denemeden önce beklenmesi gereken saniye sayısı.
RateLimit-Policy
Geçerli limitler, IETF taslağı draft-ietf-httpapi-ratelimit-headers biçiminde: virgülle ayrılmış "<name>";q=<quota>;w=<window in seconds> öğeleri. key, API anahtarının istek hızıdır (kota ani artış payıdır, zaman penceresi bu payın tamamen dolma süresidir; oturum için user, kimlik bilgisi olmadan ip); minute, day ve month, kuruluşun UTC’ye göre takvim dakikası, günü ve ayı için kotalarıdır.
RateLimit
RateLimit-Policy içindeki her limitten kalan: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
RateLimit-Policy içindeki en sıkı girdinin limiti (en az istek hakkı kalan girdi).
X-RateLimit-Remaining
En sıkı limitte kalan istek sayısı.
X-RateLimit-Reset
En sıkı limitin sıfırlanmasına kalan saniye.

application/json

Nesne: Error

Hata kodları

Bu uç noktanın, her isteğin genel kodlarının yanı sıra error.code alanında döndürebileceği kodlar.

Güvenli yeniden denemeler

Her POST ve PATCH isteğiyle bir Idempotency-Key başlığı (örneğin bir UUID) gönderin. Aynı anahtarla 24 saat içinde yapılan yeniden deneme, isteği yeniden çalıştırmak yerine kaydedilmiş yanıtı döndürür.

Hız sınırları

Yanıtlarda RateLimit ve RateLimit-Policy başlıklarıyla birlikte daha eski X-RateLimit-Limit, X-RateLimit-Remaining ve X-RateLimit-Reset başlıkları bulunur. 429 yanıtında saniye cinsinden Retry-After başlığı vardır: bekleyin ve yeniden deneyin.

← cards · API başvurusu

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"

Dene

API anahtarı

Anahtar bu sekmenin belleğinde kalır ve yalnızca https://api.sursa.com adresine gönderilir.

İstekler kuruluşunuzun gerçek verileri üzerinde çalışır.

Idempotency-Key header

X-View-As header

card_id path *

Idempotency-Key

Bu alan boş bırakılırsa her istek için yeni bir anahtar oluşturulur.

İstek gövdesi (JSON)