Pereiti prie turinio
Sursa Developers

GET/v1/cards

Gauti kortelių sąrašą

list_cards

Grąžina korteles su filtrais, rikiavimu ir puslapiavimu. Su preview=1 (plytelių rodiniui) kiekviena kortelė turi ir preview (pirmieji 200 teksto simbolių) bei preview_tables (lapai su jų eilučių skaičiais) – jūsų duomenų profilio ribose.

Autentifikavimas

Siųskite API raktą antraštėje Authorization: Authorization: Bearer <raktas>.

Užklausos parametrai

  • collectionstring | null
  • folderstring | null

    <folder ID> grąžina aplanko ir visų jo poaplankių korteles. none grąžina rinkinio korteles, kurios nėra jokiame aplanke, ir reikalauja collection (kitaip 400 cards.invalid_folder_filter). Jei aplanko nėra arba jis jums nematomas, užklausa grąžina 404 folders.not_found.

    length ≤ 64

  • statusstring | null

    Leidžiamos reikšmės: processingreadyerrorarchivedall

  • ownerstring | null

    me, none arba naudotojo ID.

  • owner_idinteger | null
  • verificationstring | null

    Leidžiamos reikšmės: verifiedneeds_verificationstale

  • kindCardKind
  • typestring | null

    table grąžina korteles su faktų lentelėmis, text – korteles be jų.

    Leidžiamos reikšmės: tabletext

  • tagsstring | null

    Kableliais atskirtos žymos (kortelė turi turėti jas visas).

  • idsstring | null

    Kableliais atskirti kortelių ID.

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

    Numatytoji reikšmė: "created_at"

  • orderstring

    Leidžiamos reikšmės: ascdesc

    Numatytoji reikšmė: "desc"

  • limitinteger

    Numatytoji reikšmė: 200

  • offsetinteger

    Numatytoji reikšmė: 0

  • previewboolean

    true prideda preview (pirmieji 200 simbolių) ir preview_tables plytelių rodiniui.

    Numatytoji reikšmė: false

  • updated_sincestring (date-time)

    Tik kortelės, kurių updated_at ne ankstesnis už šį momentą (RFC 3339 su laiko juostos poslinkiu); skirta sinchronizacijai. Be aiškiai nurodytų sort ir order sąrašas rikiuojamas pagal updated_at didėjančia tvarka, paskui pagal id. Ištrintos kortelės sąraše nepateikiamos: apie ištrynimus pranešama įvykiais.

  • metadatamap of string

    Filtras pagal metadata: metadata[<key>]=<value> tikrina tikslų atitikimą. Iki 3 sąlygų, ir visos jos turi būti tenkinamos (?metadata[team]=support&metadata[crm_id]=A-1042). Jei sąlygų daugiau nei 3 arba raktas netinkamas, grąžinama 400 api.metadata_invalid.

  • collection_idinteger

    Rinkinys pagal ID. Jei perduodamas ir collection, pirmenybė teikiama collection_id. Jei rinkinio organizacijoje nėra arba jis nematomas, grąžinama 404 collections.not_found.

  • external_idstring

    Tik kortelė su šiuo external_id.

  • cursorstring

    Kito puslapio žymeklis iš X-Next-Cursor arba iš ankstesnio atsako su tais pačiais filtrais lauko next_cursor; jame užkoduotas ir puslapio dydis. Kartu su offset: 422 validation.failed; kito sąrašo, kitų filtrų ar sugadintas žymeklis: 400 api.cursor_invalid.

    length ≤ 512

  • expand[]array of string

    Susiję objektai, kuriuos reikia įtraukti į atsaką (nuo 1.62.0): kelias iš operacijos sąrašo x-expandable. Parametrą kartokite iki 10 kartų. Kelią sudaro iki 2 segmentų, atskirtų tašku (collection.default_owner). Sąraše kelias prasideda data. ir taikomas kiekvienam puslapio elementui (expand[]=data.owner). Išplėstas objektas patenka į elemento objektą expanded, o ID laukas lieka. Objektas, kurio iškvietėjas negali matyti pagal jo paties skaitymo operacijos patikras, išplečiamas kaip null. Nežinomas kelias, daugiau nei 10 kelių arba gilesnis nei 2 segmentų kelias grąžina 400 api.expand_invalid.

    items ≤ 10

Antraštės parametrai

  • X-View-Asstring

    Tik API raktams su vaidmeniu admin. Užklausa vykdoma duomenų profilio <profile>[:viewer|verifier|editor] vardu, pvz., employee:viewer. Diegimo raktas šios antraštės naudoti negali (403).

Slapuko parametrai

  • kb_view_asstring

    Režimo „View as“ (žiūrėti kaip) sesijos slapukas. POST /auth/view-as jį nustato, o DELETE /auth/view-as išvalo.

Atsakai

200Sėkmingas atsakas

Atsako antraštės

  • Link

    Kito puslapio adresas, <…>; rel="next". Jei antraštės nėra, tai paskutinis puslapis.

  • X-Next-Cursor

    Kito puslapio žymeklis parametrui cursor. Jei antraštės nėra, tai paskutinis puslapis.

  • RateLimit-Policy

    Galiojantys limitai IETF juodraščio draft-ietf-httpapi-ratelimit-headers formatu: kableliais atskirti elementai "<name>";q=<quota>;w=<window in seconds>. key – API rakto užklausų dažnis (kvota – pliūpsnis, laiko langas – laikas, per kurį kvota visiškai atsistato; sesijai tai user, be prisijungimo duomenų – ip); minute, day ir month – organizacijos kvotos kalendorinei minutei, dienai ir mėnesiui pagal UTC.

  • RateLimit

    Kiek liko kiekvieno RateLimit-Policy limito: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Griežčiausio RateLimit-Policy įrašo (kuriame liko mažiausiai užklausų) limitas.

  • X-RateLimit-Remaining

    Likusių užklausų skaičius pagal griežčiausią limitą.

  • X-RateLimit-Reset

    Sekundės iki griežčiausio limito atsistatymo.

application/json

Objektas: CardList

array of Card
  • expandedCardExpanded
  • permissionsObjectPermissionList
  • accessstring

    Leidžiamos reikšmės: wholepartial

  • access_contactstring

    Į ką kreiptis dėl prieigos (tik kai access=partial).

  • aclobject
    Laukai
    • verifybooleanprivalomas
    • writebooleanprivalomas
  • categorystringprivalomas
  • category_confidencenumber | nullprivalomas
  • category_lockedbooleanprivalomas
  • category_reviewbooleanprivalomas
  • category_sourceCategorySource | nullprivalomas
  • collectionstringprivalomas
  • collection_idintegerprivalomas
  • collection_titlestring
  • commentsarray of CardComment
  • content_jsonContentJSON | null

    Naujausios paskelbtos versijos redaktoriaus turinys. Lauko gali nebūti; tada redaktoriaus turinį gaukite iš juodraščio (POST /v1/drafts su card_id).

  • editing_lockEditingLock | null

    Aktyvus redagavimo užraktas. Lauko gali nebūti; tada redaktorius sužino, kas laiko užraktą, iš atsako 409 cards.locked į POST /v1/cards/{card_id}/lock.

  • created_atstring (date-time)privalomas
  • days_since_verifiedintegerprivalomas
  • errorstring | nullprivalomas
  • eventsarray of CardEvent
  • feedback_negintegerprivalomas
  • feedback_posintegerprivalomas
  • foldersarray of CardFolderRef

    Tik kortelių sąraše: aplankai, kuriuose yra kortelė (tie, kuriuos mato naudotojas), su keliais nuo rinkinio šaknies. Tuščias sąrašas reiškia, kad kortelės nėra jokiame aplanke.

  • has_tablesboolean

    Tik kortelių sąraše.

  • hidden_partsboolean
  • idstringprivalomas
  • jobJob | null
  • kindCardKindprivalomas
  • org_idintegerprivalomas
  • owner_activeboolean | null
  • owner_idinteger | nullprivalomas
  • owner_namestring | nullprivalomas
  • pagesinteger | nullprivalomas
  • parserstring | nullprivalomas

    Dokumento nuskaitymo priemonė kaip neutralus kodas: document (visa struktūra: puslapiai, antraštės, lentelės, nuskenuoti puslapiai), pdf (PDF teksto sluoksnis), docx, xlsx, csv, markdown, html, text. Sąrašas gali būti papildytas.

  • partsarray of CardPartprivalomas
  • sensitivebooleanprivalomas
  • sha256string | nullprivalomas
  • sizeintegerprivalomas
  • snoozed_atstring (date-time) | null
  • snoozed_byinteger | null
  • snoozed_untilstring | null
  • source_changedbooleanprivalomas
  • source_pathstring | nullprivalomas
  • source_urlstring | nullprivalomas
  • statusstringprivalomas

    Leidžiamos reikšmės: processingreadyerrorarchived

  • tablesarray of CardTable
  • tagsarray of stringprivalomas
  • titlestringprivalomas
  • trustnumberprivalomas
  • trust_if_verifiednumber
  • trust_partsTrustPartsprivalomas
  • updated_atstring (date-time)privalomas
  • verificationVerificationprivalomas
  • verified_atstring (date-time) | nullprivalomas
  • verified_byinteger | nullprivalomas
  • verified_by_namestring | null
  • verifier_idsarray of integerprivalomas
  • verifiersarray of object
    Laukai
    • activebooleanprivalomas
    • idintegerprivalomas
    • namestringprivalomas
  • verify_interval_daysintegerprivalomas
  • versionintegerprivalomas
  • versionsarray of CardVersion
  • source_archiveArchiveSource
  • created_byinteger | null
  • manual_optionsobject

    Rankiniai nuskaitymo nustatymai (peržiūra).

  • doc_kindDocKind | null

    Dokumento tipas. null, jei tipas nenustatytas (pavyzdžiui, kortelėms, indeksuotoms dar prieš atsirandant dokumentų tipams).

  • doc_kind_confidencenumber | null

    Dokumento tipo užtikrintumas, nuo 0 iki 1.

  • doc_kind_sourcestring | null

    Kas nustatė tipą: taisyklės (rules), naudotojas (manual) ar automatinis klasifikavimas. Sąrašas gali būti papildytas: nežinomą reikšmę laikykite automatiniu klasifikavimu.

    Leidžiamos reikšmės: rulesmanualnull

  • invoiceDocInvoiceExtraction | null

    Sąskaitos faktūros, kreditinės sąskaitos faktūros arba kvito laukai (tik šiems tipams ir tik kortelėje, ne sąraše). null, jei neturite prieigos prie viso dokumento, nes laukai išgaunami iš viso dokumento.

  • warningsarray of ReviewWarning

    Dokumento nuskaitymo įspėjimai (ReviewWarning; tik kortelėje, ne sąraše).

  • enrichmentCardEnrichmentStatus | null

    Papildymo būsena (tik kortelėje, ne sąraše). Dokumento tipas, sąskaitos faktūros laukai ir finansiniai įrašai pridedami fone po indeksavimo ir vėliau gali būti perskaičiuoti; kortelėje jie atsiranda, kai yra paruošti. null reiškia, kad būsenos nėra (kortelė indeksuota be papildymo fone).

  • external_idstring | null

    Kortelės ID integratoriaus sistemoje. Jis unikalus organizacijoje tarp kortelių, kurios nėra iš šaltinių; null reiškia, kad jis nenustatytas. /v1/cards-by-external-id/{external_id} pagal jį skaito ir pakeičia kortelę.

    length ≤ 512

  • metadataMetadata
400Užklausa netinkama: parametro reikšmė arba objekto būsena neleidžia atlikti veiksmo (`detail` – pranešimas).

Atsako antraštės

  • RateLimit-Policy

    Galiojantys limitai IETF juodraščio draft-ietf-httpapi-ratelimit-headers formatu: kableliais atskirti elementai "<name>";q=<quota>;w=<window in seconds>. key – API rakto užklausų dažnis (kvota – pliūpsnis, laiko langas – laikas, per kurį kvota visiškai atsistato; sesijai tai user, be prisijungimo duomenų – ip); minute, day ir month – organizacijos kvotos kalendorinei minutei, dienai ir mėnesiui pagal UTC.

  • RateLimit

    Kiek liko kiekvieno RateLimit-Policy limito: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Griežčiausio RateLimit-Policy įrašo (kuriame liko mažiausiai užklausų) limitas.

  • X-RateLimit-Remaining

    Likusių užklausų skaičius pagal griežčiausią limitą.

  • X-RateLimit-Reset

    Sekundės iki griežčiausio limito atsistatymo.

application/json

Objektas: Error

401Prisijungimo duomenys neišsiųsti (nei sesijos slapukas, nei API raktas) arba raktas nerastas.

Atsako antraštės

  • RateLimit-Policy

    Galiojantys limitai IETF juodraščio draft-ietf-httpapi-ratelimit-headers formatu: kableliais atskirti elementai "<name>";q=<quota>;w=<window in seconds>. key – API rakto užklausų dažnis (kvota – pliūpsnis, laiko langas – laikas, per kurį kvota visiškai atsistato; sesijai tai user, be prisijungimo duomenų – ip); minute, day ir month – organizacijos kvotos kalendorinei minutei, dienai ir mėnesiui pagal UTC.

  • RateLimit

    Kiek liko kiekvieno RateLimit-Policy limito: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Griežčiausio RateLimit-Policy įrašo (kuriame liko mažiausiai užklausų) limitas.

  • X-RateLimit-Remaining

    Likusių užklausų skaičius pagal griežčiausią limitą.

  • X-RateLimit-Reset

    Sekundės iki griežčiausio limito atsistatymo.

application/json

Objektas: Error

403Veiksmas neleidžiamas: vaidmuo nesuteikia reikiamų teisių, nėra prieigos prie rinkinio ar kortelės, užklausa vykdoma režimu „View as“ arba organizacijos veikla sustabdyta ar organizacija ištrinta (`detail` – objektas su `code: org_suspended | org_deleted`).

Atsako antraštės

  • RateLimit-Policy

    Galiojantys limitai IETF juodraščio draft-ietf-httpapi-ratelimit-headers formatu: kableliais atskirti elementai "<name>";q=<quota>;w=<window in seconds>. key – API rakto užklausų dažnis (kvota – pliūpsnis, laiko langas – laikas, per kurį kvota visiškai atsistato; sesijai tai user, be prisijungimo duomenų – ip); minute, day ir month – organizacijos kvotos kalendorinei minutei, dienai ir mėnesiui pagal UTC.

  • RateLimit

    Kiek liko kiekvieno RateLimit-Policy limito: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Griežčiausio RateLimit-Policy įrašo (kuriame liko mažiausiai užklausų) limitas.

  • X-RateLimit-Remaining

    Likusių užklausų skaičius pagal griežčiausią limitą.

  • X-RateLimit-Reset

    Sekundės iki griežčiausio limito atsistatymo.

application/json

Objektas: Error

404Objekto nėra arba jis jums nepasiekiamas. API nepatvirtina, kad ribotos prieigos objektas egzistuoja.

Atsako antraštės

  • RateLimit-Policy

    Galiojantys limitai IETF juodraščio draft-ietf-httpapi-ratelimit-headers formatu: kableliais atskirti elementai "<name>";q=<quota>;w=<window in seconds>. key – API rakto užklausų dažnis (kvota – pliūpsnis, laiko langas – laikas, per kurį kvota visiškai atsistato; sesijai tai user, be prisijungimo duomenų – ip); minute, day ir month – organizacijos kvotos kalendorinei minutei, dienai ir mėnesiui pagal UTC.

  • RateLimit

    Kiek liko kiekvieno RateLimit-Policy limito: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Griežčiausio RateLimit-Policy įrašo (kuriame liko mažiausiai užklausų) limitas.

  • X-RateLimit-Remaining

    Likusių užklausų skaičius pagal griežčiausią limitą.

  • X-RateLimit-Reset

    Sekundės iki griežčiausio limito atsistatymo.

application/json

Objektas: Error

422Validavimo klaida: turinys ar parametrai neatitinka schemos (`detail` – validavimo klaidų sąrašas) arba parametro reikšmė nepatenka į leistiną intervalą (`detail` – pranešimas).

Atsako antraštės

  • RateLimit-Policy

    Galiojantys limitai IETF juodraščio draft-ietf-httpapi-ratelimit-headers formatu: kableliais atskirti elementai "<name>";q=<quota>;w=<window in seconds>. key – API rakto užklausų dažnis (kvota – pliūpsnis, laiko langas – laikas, per kurį kvota visiškai atsistato; sesijai tai user, be prisijungimo duomenų – ip); minute, day ir month – organizacijos kvotos kalendorinei minutei, dienai ir mėnesiui pagal UTC.

  • RateLimit

    Kiek liko kiekvieno RateLimit-Policy limito: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Griežčiausio RateLimit-Policy įrašo (kuriame liko mažiausiai užklausų) limitas.

  • X-RateLimit-Remaining

    Likusių užklausų skaičius pagal griežčiausią limitą.

  • X-RateLimit-Reset

    Sekundės iki griežčiausio limito atsistatymo.

application/json

Objektas: Error

429Per daug užklausų (`api.rate_limited`), išnaudota organizacijos minutės, dienos ar mėnesio kvota (`api.quota_exceeded`; `error.details` pateikia `quota`, `limit` ir `reset_at`), pasiektas organizacijos limitas arba atsakymų paslauga užimta (`answers.engine_busy`). Palaukite tiek, kiek nurodyta antraštėje `Retry-After`.

Atsako antraštės

  • Retry-After

    Kiek sekundžių palaukti prieš kartojant užklausą.

  • RateLimit-Policy

    Galiojantys limitai IETF juodraščio draft-ietf-httpapi-ratelimit-headers formatu: kableliais atskirti elementai "<name>";q=<quota>;w=<window in seconds>. key – API rakto užklausų dažnis (kvota – pliūpsnis, laiko langas – laikas, per kurį kvota visiškai atsistato; sesijai tai user, be prisijungimo duomenų – ip); minute, day ir month – organizacijos kvotos kalendorinei minutei, dienai ir mėnesiui pagal UTC.

  • RateLimit

    Kiek liko kiekvieno RateLimit-Policy limito: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Griežčiausio RateLimit-Policy įrašo (kuriame liko mažiausiai užklausų) limitas.

  • X-RateLimit-Remaining

    Likusių užklausų skaičius pagal griežčiausią limitą.

  • X-RateLimit-Reset

    Sekundės iki griežčiausio limito atsistatymo.

application/json

Objektas: Error

Klaidų kodai

Kodai, kuriuos ši operacija gali grąžinti lauke error.code, be bendrųjų kodų, galimų bet kuriai užklausai.

Užklausų dažnio limitai

Atsakuose yra antraštės RateLimit ir RateLimit-Policy bei ankstesnės X-RateLimit-Limit, X-RateLimit-Remaining ir X-RateLimit-Reset. Atsake 429 yra antraštė Retry-After sekundėmis: palaukite ir pakartokite užklausą.

← cards · API žinynas