İçeriğe geç
Sursa Developers

GET/v1/cards

Kartları listeleme

list_cards

Kartları filtreler, sıralama ve sayfalamayla döndürür. preview=1 ile (kutucuk görünümü için) her kartta ayrıca preview (metnin ilk 200 karakteri) ve preview_tables (satır sayılarıyla çalışma sayfaları) bulunur; veri profilinizin sınırları içinde.

Kimlik doğrulama

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

Sorgu parametreleri

  • collectionstring | null
  • folderstring | null

    <folder ID> klasörün ve tüm alt klasörlerinin kartlarını döndürür. none, koleksiyonun hiçbir klasörde olmayan kartlarını döndürür ve collection gerektirir (aksi hâlde 400 cards.invalid_folder_filter). Klasör yoksa ya da size görünmüyorsa istek 404 folders.not_found döndürür.

    length ≤ 64

  • statusstring | null

    Geçerli değerler: processingreadyerrorarchivedall

  • ownerstring | null

    me, none ya da bir kullanıcı kimliği.

  • owner_idinteger | null
  • verificationstring | null

    Geçerli değerler: verifiedneeds_verificationstale

  • kindCardKind
  • typestring | null

    table olgu tabloları olan kartları, text olgu tablosu olmayan kartları döndürür.

    Geçerli değerler: tabletext

  • tagsstring | null

    Virgülle ayrılmış etiketler (kartta hepsi bulunmalıdır).

  • idsstring | null

    Virgülle ayrılmış kart kimlikleri.

  • searchstring | null
  • categorystring | null
  • sensitiveboolean | null
  • sortCardSort

    Varsayılan: "created_at"

  • orderstring

    Geçerli değerler: ascdesc

    Varsayılan: "desc"

  • limitinteger

    Varsayılan: 200

  • offsetinteger

    Varsayılan: 0

  • previewboolean

    true, kutucuk görünümü için preview (ilk 200 karakter) ve preview_tables ekler.

    Varsayılan: false

  • updated_sincestring (date-time)

    Senkronizasyon için yalnızca updated_at değeri bu andan itibaren olan kartlar (UTC farkı içeren RFC 3339). Açık sort ve order verilmezse liste updated_at değerine göre artan, ardından id değerine göre sıralanır. Silinen kartlar listelenmez: silinenler olay olarak gelir.

  • metadatamap of string

    metadata alanına göre filtre: metadata[<key>]=<value> tam eşleşme arar. En fazla 3 koşul verilebilir ve hepsi eşleşmelidir (?metadata[team]=support&metadata[crm_id]=A-1042). 3’ten fazla koşul ya da geçersiz bir anahtar 400 api.metadata_invalid döndürür.

  • collection_idinteger

    Kimliğe göre koleksiyon. collection de verilirse collection_id önceliklidir. Kuruluşta bulunmayan ya da görünmeyen bir koleksiyon 404 collections.not_found döndürür.

  • external_idstring

    Yalnızca bu external_id değerine sahip kart.

  • cursorstring

    Sonraki sayfanın imleci: aynı filtrelerle alınan önceki yanıtın X-Next-Cursor başlığından ya da next_cursor alanından alınır; sayfa boyutunu da taşır. offset ile birlikte: 422 validation.failed; başka bir listeye ya da başka filtrelere ait veya bozuk bir imleç: 400 api.cursor_invalid.

    length ≤ 512

  • expand[]array of string

    Yanıta eklenecek ilgili nesneler (1.62.0 sürümünden beri): işlemin x-expandable listesindeki bir yol. Parametreyi en fazla 10 kez tekrarlayın. Bir yol, noktayla ayrılmış en fazla 2 bölümden oluşur (collection.default_owner). Listede yol data. ile başlar ve sayfadaki her öğeye uygulanır (expand[]=data.owner). Genişletilmiş nesne öğenin expanded nesnesine girer, kimlik alanı yerinde kalır. Çağıranın, kendi okuma işleminin denetimlerine göre erişemeyeceği bir nesne null olarak genişletilir. Bilinmeyen bir yol, 10’dan fazla yol ya da 2 bölümden derin bir yol 400 api.expand_invalid döndürür.

    items ≤ 10

Başlık parametreleri

  • 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.

Yanıtlar

200Başarılı yanıt

Yanıt başlıkları

  • Link

    Sonraki sayfanın adresi, <…>; rel="next". Başlık yoksa bu son sayfadır.

  • X-Next-Cursor

    cursor parametresi için sonraki sayfanın imleci. Başlık yoksa bu son sayfadır.

  • 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: CardList

array of 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.

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