Salt la conținut
Sursa Developers

GET/v1/cards

Listează fișele

list_cards

Returnează fișele cu filtre, sortare și paginare. Cu preview=1 (pentru vizualizarea în dale), fiecare fișă are și preview (primele 200 de caractere ale textului) și preview_tables (foile, cu numărul de rânduri al fiecăreia), în limitele profilului de date.

Autentificare

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

Parametri de interogare

  • collectionstring | null
  • folderstring | null

    <folder ID> returnează fișele dosarului și ale tuturor subdosarelor lui. none returnează fișele colecției care nu se află în niciun dosar și necesită collection (altfel 400 cards.invalid_folder_filter). Dacă dosarul nu există sau nu vă este vizibil, cererea returnează 404 folders.not_found.

    length ≤ 64

  • statusstring | null

    Valori permise: processingreadyerrorarchivedall

  • ownerstring | null

    me, none sau ID-ul unui utilizator.

  • owner_idinteger | null
  • verificationstring | null

    Valori permise: verifiedneeds_verificationstale

  • kindCardKind
  • typestring | null

    table returnează fișele cu tabele de fapte, text – fișele fără ele.

    Valori permise: tabletext

  • tagsstring | null

    Etichete separate prin virgulă (fișa trebuie să le aibă pe toate).

  • idsstring | null

    ID-uri de fișe separate prin virgulă.

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

    Implicit: "created_at"

  • orderstring

    Valori permise: ascdesc

    Implicit: "desc"

  • limitinteger

    Implicit: 200

  • offsetinteger

    Implicit: 0

  • previewboolean

    true adaugă preview (primele 200 de caractere) și preview_tables pentru vizualizarea în dale.

    Implicit: false

  • updated_sincestring (date-time)

    Doar fișele cu updated_at egal cu acest moment sau ulterior lui (RFC 3339 cu decalajul fusului orar), pentru sincronizare. Fără sort și order explicite, lista este sortată după updated_at crescător, apoi după id. Fișele șterse nu apar în listă: ștergerile sosesc ca evenimente.

  • metadatamap of string

    Filtru după metadata: metadata[<key>]=<value> caută potrivirea exactă. Cel mult 3 condiții, care trebuie îndeplinite toate (?metadata[team]=support&metadata[crm_id]=A-1042). Mai mult de 3 condiții sau o cheie invalidă returnează 400 api.metadata_invalid.

  • collection_idinteger

    Colecția după ID. Dacă se transmite și collection, are prioritate collection_id. O colecție care nu există în organizație sau nu este vizibilă returnează 404 collections.not_found.

  • external_idstring

    Doar fișa cu acest external_id.

  • cursorstring

    Cursorul paginii următoare din X-Next-Cursor sau next_cursor al răspunsului anterior, cu aceleași filtre; el conține dimensiunea paginii. Împreună cu offset: 422 validation.failed; un cursor al altei liste, cu alte filtre sau malformat: 400 api.cursor_invalid.

    length ≤ 512

  • expand[]array of string

    Obiectele asociate de inclus în răspuns (din 1.62.0): o cale din lista x-expandable a operației. Repetați parametrul de cel mult 10 ori. O cale are cel mult 2 segmente separate prin punct (collection.default_owner). Într-o listă, calea începe cu data. și se aplică fiecărui element al paginii (expand[]=data.owner). Un obiect extins intră în obiectul expanded al elementului, iar câmpul cu ID-ul rămâne. Un obiect pe care apelantul nu are voie să-l vadă conform verificărilor operației proprii de citire este extins ca null. O cale necunoscută, mai mult de 10 căi sau o cale mai adâncă de 2 segmente returnează 400 api.expand_invalid.

    items ≤ 10

Parametri de antet

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

Răspunsuri

200Răspuns reușit

Antetele răspunsului

  • Link

    Adresa paginii următoare, <…>; rel="next". Lipsa antetului înseamnă că aceasta este ultima pagină.

  • X-Next-Cursor

    Cursorul paginii următoare pentru parametrul cursor. Lipsa antetului înseamnă că aceasta este ultima pagină.

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

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

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