Ugrás a tartalomra
Sursa Developers

GET/v1/cards

Kártyák listázása

list_cards

Visszaadja a kártyákat szűrőkkel, rendezéssel és lapozással. preview=1 esetén (a csempenézethez) minden kártyán a preview (a szöveg első 200 karaktere) és a preview_tables (a munkalapok a soraik számával) mező is szerepel, az adatprofilod keretein belül.

Hitelesítés

Küldj egy API-kulcsot az Authorization fejlécben: Authorization: Bearer <kulcs>.

Lekérdezési paraméterek

  • collectionstring | null
  • folderstring | null

    A <folder ID> a mappa és az összes almappája kártyáit adja vissza. A none a gyűjtemény azon kártyáit adja vissza, amelyek egyetlen mappában sincsenek, és megköveteli a collection paramétert (különben 400 cards.invalid_folder_filter). Ha a mappa nem létezik, vagy nem látható számodra, a válasz 404 folders.not_found.

    length ≤ 64

  • statusstring | null

    Megengedett értékek: processingreadyerrorarchivedall

  • ownerstring | null

    me, none vagy egy felhasználó azonosítója.

  • owner_idinteger | null
  • verificationstring | null

    Megengedett értékek: verifiedneeds_verificationstale

  • kindCardKind
  • typestring | null

    A table a ténytáblákat tartalmazó kártyákat adja vissza, a text a ténytábla nélkülieket.

    Megengedett értékek: tabletext

  • tagsstring | null

    Vesszővel elválasztott címkék (a kártyának mindegyikkel rendelkeznie kell).

  • idsstring | null

    Vesszővel elválasztott kártyaazonosítók.

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

    Alapértelmezett: "created_at"

  • orderstring

    Megengedett értékek: ascdesc

    Alapértelmezett: "desc"

  • limitinteger

    Alapértelmezett: 200

  • offsetinteger

    Alapértelmezett: 0

  • previewboolean

    A true a csempenézethez hozzáadja a preview (az első 200 karakter) és a preview_tables mezőt.

    Alapértelmezett: false

  • updated_sincestring (date-time)

    Csak azok a kártyák, amelyek updated_at értéke erre az időpontra vagy későbbre esik (RFC 3339, időeltolással), szinkronizáláshoz. Explicit sort és order nélkül a lista updated_at szerint növekvő sorrendű, azon belül id szerint. A törölt kártyák nem szerepelnek a listában: a törlések eseményként érkeznek.

  • metadatamap of string

    Szűrés metadata szerint: a metadata[<key>]=<value> pontos egyezést jelent. Legfeljebb 3 feltétel adható meg, és mindegyiknek teljesülnie kell (?metadata[team]=support&metadata[crm_id]=A-1042). 3-nál több feltétel vagy érvénytelen kulcs esetén a válasz 400 api.metadata_invalid.

  • collection_idinteger

    Gyűjtemény azonosító szerint. Ha a collection is meg van adva, a collection_id az irányadó. A szervezetben nem létező vagy nem látható gyűjtemény esetén a válasz 404 collections.not_found.

  • external_idstring

    Csak az ezzel az external_id azonosítóval rendelkező kártya.

  • cursorstring

    A következő oldal kurzora az előző, azonos szűrőkkel küldött kérésre kapott válasz X-Next-Cursor fejlécéből vagy next_cursor mezőjéből; az oldalméretet is magában hordozza. Az offset paraméterrel együtt: 422 validation.failed; más lista vagy más szűrők kurzora, illetve hibás kurzor: 400 api.cursor_invalid.

    length ≤ 512

  • expand[]array of string

    A válaszba felveendő kapcsolódó objektumok (az 1.62.0 verziótól): egy útvonal a művelet x-expandable listájából. A paraméter legfeljebb 10-szer ismételhető. Egy útvonal legfeljebb 2, ponttal elválasztott szegmensből áll (collection.default_owner). Listában az útvonal data. előtaggal kezdődik, és az oldal minden elemére vonatkozik (expand[]=data.owner). A kibontott objektum az elem expanded objektumába kerül, az azonosítómező pedig megmarad. Az az objektum, amelyet a hívó a saját olvasási műveletének hozzáférési vizsgálatai szerint nem láthat, null értékként bomlik ki. Ismeretlen útvonal, 10-nél több útvonal vagy 2 szegmensnél mélyebb útvonal esetén a válasz 400 api.expand_invalid.

    items ≤ 10

Fejlécparaméterek

  • X-View-Asstring

    Csak admin szerepkörű API-kulcsokhoz. A kérést a <profile>[:viewer|verifier|editor] adatprofil nevében hajtja végre, például employee:viewer. A telepítési kulcs nem használhatja ezt a fejlécet (403).

Cookie-paraméterek

  • kb_view_asstring

    A „View as” mód sütije egy munkamenethez. A POST /auth/view-as beállítja, a DELETE /auth/view-as törli.

Válaszok

200Sikeres válasz

Válaszfejlécek

  • Link

    A következő oldal címe, <…>; rel="next". Ha a fejléc hiányzik, ez az utolsó oldal.

  • X-Next-Cursor

    A következő oldal kurzora a cursor paraméterhez. Ha a fejléc hiányzik, ez az utolsó oldal.

  • RateLimit-Policy

    Az érvényben lévő korlátok az IETF draft-ietf-httpapi-ratelimit-headers tervezetének formátumában: vesszővel elválasztott "<name>";q=<quota>;w=<window in seconds> elemek. A key az API-kulcs kérésgyakorisága (a kvóta a csúcskeret, az időablak a teljes visszatöltődés ideje; munkamenetnél user, hitelesítő adatok nélkül ip); a minute, a day és a month a szervezetnek az UTC szerinti naptári percre, napra és hónapra szóló kvótája.

  • RateLimit

    Mennyi maradt a RateLimit-Policy egyes korlátaiból: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    A RateLimit-Policy legszigorúbb elemének korlátja (amelyből a legkevesebb kérés maradt).

  • X-RateLimit-Remaining

    A legszigorúbb korlát szerint még hátralévő kérések száma.

  • X-RateLimit-Reset

    A legszigorúbb korlát visszaállásáig hátralévő másodpercek.

application/json

Objektum: CardList

array of Card
  • expandedCardExpanded
  • permissionsObjectPermissionList
  • accessstring

    Megengedett értékek: wholepartial

  • access_contactstring

    Kihez lehet fordulni hozzáférésért (csak access=partial esetén).

  • aclobject
    Mezők
    • verifybooleankötelező
    • writebooleankötelező
  • categorystringkötelező
  • category_confidencenumber | nullkötelező
  • category_lockedbooleankötelező
  • category_reviewbooleankötelező
  • category_sourceCategorySource | nullkötelező
  • collectionstringkötelező
  • collection_idintegerkötelező
  • collection_titlestring
  • commentsarray of CardComment
  • content_jsonContentJSON | null

    A legutóbb közzétett verzió szerkesztői tartalma. A mező hiányozhat; ilyenkor a szerkesztői tartalmat egy piszkozatból kérd le (POST /v1/drafts a card_id megadásával).

  • editing_lockEditingLock | null

    Aktív szerkesztési zárolás. A mező hiányozhat; ilyenkor a szerkesztő a POST /v1/cards/{card_id}/lock hívásra kapott 409 cards.locked válaszból tudja meg, ki tartja a zárolást.

  • created_atstring (date-time)kötelező
  • days_since_verifiedintegerkötelező
  • errorstring | nullkötelező
  • eventsarray of CardEvent
  • feedback_negintegerkötelező
  • feedback_posintegerkötelező
  • foldersarray of CardFolderRef

    Csak a kártyalistában: a kártyát tartalmazó mappák (a felhasználó számára láthatók), a gyűjtemény gyökerétől számított útvonalukkal. Az üres lista azt jelenti, hogy a kártya egyik mappában sincs.

  • has_tablesboolean

    Csak a kártyalistában.

  • hidden_partsboolean
  • idstringkötelező
  • jobJob | null
  • kindCardKindkötelező
  • org_idintegerkötelező
  • owner_activeboolean | null
  • owner_idinteger | nullkötelező
  • owner_namestring | nullkötelező
  • pagesinteger | nullkötelező
  • parserstring | nullkötelező

    A dokumentum feldolgozója semleges kódként: document (teljes szerkezet: oldalak, címsorok, táblázatok, szkennelt oldalak), pdf (a PDF szövegrétege), docx, xlsx, csv, markdown, html, text. A lista bővülhet.

  • partsarray of CardPartkötelező
  • sensitivebooleankötelező
  • sha256string | nullkötelező
  • sizeintegerkötelező
  • snoozed_atstring (date-time) | null
  • snoozed_byinteger | null
  • snoozed_untilstring | null
  • source_changedbooleankötelező
  • source_pathstring | nullkötelező
  • source_urlstring | nullkötelező
  • statusstringkötelező

    Megengedett értékek: processingreadyerrorarchived

  • tablesarray of CardTable
  • tagsarray of stringkötelező
  • titlestringkötelező
  • trustnumberkötelező
  • trust_if_verifiednumber
  • trust_partsTrustPartskötelező
  • updated_atstring (date-time)kötelező
  • verificationVerificationkötelező
  • verified_atstring (date-time) | nullkötelező
  • verified_byinteger | nullkötelező
  • verified_by_namestring | null
  • verifier_idsarray of integerkötelező
  • verifiersarray of object
    Mezők
    • activebooleankötelező
    • idintegerkötelező
    • namestringkötelező
  • verify_interval_daysintegerkötelező
  • versionintegerkötelező
  • versionsarray of CardVersion
  • source_archiveArchiveSource
  • created_byinteger | null
  • manual_optionsobject

    Kézi feldolgozási beállítások (előnézet).

  • doc_kindDocKind | null

    A dokumentum típusa. null, ha a típus nincs meghatározva (például a dokumentumtípusok bevezetése előtt indexelt kártyáknál).

  • doc_kind_confidencenumber | null

    A dokumentumtípus bizonyossági szintje 0 és 1 között.

  • doc_kind_sourcestring | null

    Mi határozta meg a típust: szabályok (rules), egy felhasználó (manual) vagy automatikus besorolás. A lista bővülhet: az ismeretlen értéket automatikus besorolásként kezeld.

    Megengedett értékek: rulesmanualnull

  • invoiceDocInvoiceExtraction | null

    Számla, jóváíró számla vagy nyugta mezői (csak ezeknél a típusoknál, és csak a kártyában, a listában nem). null, ha nincs hozzáférésed a teljes dokumentumhoz, mert a mezők a teljes dokumentumból származnak.

  • warningsarray of ReviewWarning

    A dokumentum feldolgozásának figyelmeztetései (ReviewWarning; csak a kártyában, a listában nem).

  • enrichmentCardEnrichmentStatus | null

    A gazdagítás állapota (csak a kártyában, a listában nem). A dokumentum típusa, a számla mezői és a pénzügyi rekordok az indexelés után a háttérben kerülnek hozzáadásra, és később újraszámolhatók; amikor elkészülnek, megjelennek a kártyában. A null azt jelenti, hogy nincs elérhető állapot (a kártyát háttérbeli gazdagítás nélkül indexelték).

  • external_idstring | null

    A kártya azonosítója az integrátor rendszerében. A szervezetben egyedi a nem forrásból származó kártyák között; a null azt jelenti, hogy nincs beállítva. A /v1/cards-by-external-id/{external_id} ez alapján olvassa és cseréli a kártyát.

    length ≤ 512

  • metadataMetadata
400A kérés érvénytelen: egy paraméter értéke vagy az objektum állapota nem teszi lehetővé a műveletet (a `detail` egy üzenet).

Válaszfejlécek

  • RateLimit-Policy

    Az érvényben lévő korlátok az IETF draft-ietf-httpapi-ratelimit-headers tervezetének formátumában: vesszővel elválasztott "<name>";q=<quota>;w=<window in seconds> elemek. A key az API-kulcs kérésgyakorisága (a kvóta a csúcskeret, az időablak a teljes visszatöltődés ideje; munkamenetnél user, hitelesítő adatok nélkül ip); a minute, a day és a month a szervezetnek az UTC szerinti naptári percre, napra és hónapra szóló kvótája.

  • RateLimit

    Mennyi maradt a RateLimit-Policy egyes korlátaiból: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    A RateLimit-Policy legszigorúbb elemének korlátja (amelyből a legkevesebb kérés maradt).

  • X-RateLimit-Remaining

    A legszigorúbb korlát szerint még hátralévő kérések száma.

  • X-RateLimit-Reset

    A legszigorúbb korlát visszaállásáig hátralévő másodpercek.

application/json

Objektum: Error

401Nem érkeztek hitelesítő adatok (sem munkamenet-süti, sem API-kulcs), vagy a kulcs nem található.

Válaszfejlécek

  • RateLimit-Policy

    Az érvényben lévő korlátok az IETF draft-ietf-httpapi-ratelimit-headers tervezetének formátumában: vesszővel elválasztott "<name>";q=<quota>;w=<window in seconds> elemek. A key az API-kulcs kérésgyakorisága (a kvóta a csúcskeret, az időablak a teljes visszatöltődés ideje; munkamenetnél user, hitelesítő adatok nélkül ip); a minute, a day és a month a szervezetnek az UTC szerinti naptári percre, napra és hónapra szóló kvótája.

  • RateLimit

    Mennyi maradt a RateLimit-Policy egyes korlátaiból: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    A RateLimit-Policy legszigorúbb elemének korlátja (amelyből a legkevesebb kérés maradt).

  • X-RateLimit-Remaining

    A legszigorúbb korlát szerint még hátralévő kérések száma.

  • X-RateLimit-Reset

    A legszigorúbb korlát visszaállásáig hátralévő másodpercek.

application/json

Objektum: Error

403A művelet nem engedélyezett: a szerepkör nem elegendő, nincs hozzáférés a gyűjteményhez vagy a kártyához, a kérés „View as” módban fut, vagy a szervezetet felfüggesztették vagy törölték (a `detail` egy objektum, `code: org_suspended | org_deleted` mezővel).

Válaszfejlécek

  • RateLimit-Policy

    Az érvényben lévő korlátok az IETF draft-ietf-httpapi-ratelimit-headers tervezetének formátumában: vesszővel elválasztott "<name>";q=<quota>;w=<window in seconds> elemek. A key az API-kulcs kérésgyakorisága (a kvóta a csúcskeret, az időablak a teljes visszatöltődés ideje; munkamenetnél user, hitelesítő adatok nélkül ip); a minute, a day és a month a szervezetnek az UTC szerinti naptári percre, napra és hónapra szóló kvótája.

  • RateLimit

    Mennyi maradt a RateLimit-Policy egyes korlátaiból: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    A RateLimit-Policy legszigorúbb elemének korlátja (amelyből a legkevesebb kérés maradt).

  • X-RateLimit-Remaining

    A legszigorúbb korlát szerint még hátralévő kérések száma.

  • X-RateLimit-Reset

    A legszigorúbb korlát visszaállásáig hátralévő másodpercek.

application/json

Objektum: Error

404Az objektum nem létezik, vagy nem érhető el számodra. Az API nem erősíti meg, hogy egy korlátozott hozzáférésű objektum létezik.

Válaszfejlécek

  • RateLimit-Policy

    Az érvényben lévő korlátok az IETF draft-ietf-httpapi-ratelimit-headers tervezetének formátumában: vesszővel elválasztott "<name>";q=<quota>;w=<window in seconds> elemek. A key az API-kulcs kérésgyakorisága (a kvóta a csúcskeret, az időablak a teljes visszatöltődés ideje; munkamenetnél user, hitelesítő adatok nélkül ip); a minute, a day és a month a szervezetnek az UTC szerinti naptári percre, napra és hónapra szóló kvótája.

  • RateLimit

    Mennyi maradt a RateLimit-Policy egyes korlátaiból: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    A RateLimit-Policy legszigorúbb elemének korlátja (amelyből a legkevesebb kérés maradt).

  • X-RateLimit-Remaining

    A legszigorúbb korlát szerint még hátralévő kérések száma.

  • X-RateLimit-Reset

    A legszigorúbb korlát visszaállásáig hátralévő másodpercek.

application/json

Objektum: Error

422Érvényesítési hiba: a törzs vagy a paraméterek nem felelnek meg a sémának (a `detail` az érvényesítési hibák listája), vagy egy paraméter értéke kívül esik a megengedett tartományon (a `detail` egy üzenet).

Válaszfejlécek

  • RateLimit-Policy

    Az érvényben lévő korlátok az IETF draft-ietf-httpapi-ratelimit-headers tervezetének formátumában: vesszővel elválasztott "<name>";q=<quota>;w=<window in seconds> elemek. A key az API-kulcs kérésgyakorisága (a kvóta a csúcskeret, az időablak a teljes visszatöltődés ideje; munkamenetnél user, hitelesítő adatok nélkül ip); a minute, a day és a month a szervezetnek az UTC szerinti naptári percre, napra és hónapra szóló kvótája.

  • RateLimit

    Mennyi maradt a RateLimit-Policy egyes korlátaiból: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    A RateLimit-Policy legszigorúbb elemének korlátja (amelyből a legkevesebb kérés maradt).

  • X-RateLimit-Remaining

    A legszigorúbb korlát szerint még hátralévő kérések száma.

  • X-RateLimit-Reset

    A legszigorúbb korlát visszaállásáig hátralévő másodpercek.

application/json

Objektum: Error

429Túl sok kérés (`api.rate_limited`), elfogyott a szervezet percre, napra vagy hónapra szóló kvótája (`api.quota_exceeded`; az `error.details` a `quota`, a `limit` és a `reset_at` mezőt tartalmazza), a szervezet elérte a korlátját, vagy a válaszszolgáltatás foglalt (`answers.engine_busy`). Várj a `Retry-After` fejlécben megadott ideig.

Válaszfejlécek

  • Retry-After

    Ennyi másodpercet várj, mielőtt újrapróbálod a kérést.

  • RateLimit-Policy

    Az érvényben lévő korlátok az IETF draft-ietf-httpapi-ratelimit-headers tervezetének formátumában: vesszővel elválasztott "<name>";q=<quota>;w=<window in seconds> elemek. A key az API-kulcs kérésgyakorisága (a kvóta a csúcskeret, az időablak a teljes visszatöltődés ideje; munkamenetnél user, hitelesítő adatok nélkül ip); a minute, a day és a month a szervezetnek az UTC szerinti naptári percre, napra és hónapra szóló kvótája.

  • RateLimit

    Mennyi maradt a RateLimit-Policy egyes korlátaiból: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    A RateLimit-Policy legszigorúbb elemének korlátja (amelyből a legkevesebb kérés maradt).

  • X-RateLimit-Remaining

    A legszigorúbb korlát szerint még hátralévő kérések száma.

  • X-RateLimit-Reset

    A legszigorúbb korlát visszaállásáig hátralévő másodpercek.

application/json

Objektum: Error

Hibakódok

Azok a kódok, amelyeket ez a végpont hiba esetén az error.code mezőben visszaadhat, a minden kérésre érvényes általános kódokon kívül.

Gyakorisági korlátok

A válaszokban ott van a RateLimit és a RateLimit-Policy fejléc, valamint a korábbi X-RateLimit-Limit, X-RateLimit-Remaining és X-RateLimit-Reset fejléc. A 429-es válasz Retry-After fejléce másodpercben adja meg a várakozást: várj, majd próbáld újra.

← cards · API-referencia