Pāriet uz saturu
Sursa Developers

GET/v1/cards

Iegūt kartīšu sarakstu

list_cards

Atgriež kartītes ar filtriem, kārtošanu un lappušošanu. Ar preview=1 (flīžu skatam) katrai kartītei ir arī preview (pirmās 200 teksta rakstzīmes) un preview_tables (lapas ar to rindu skaitu) jūsu datu profila robežās.

Autentifikācija

Nosūtiet API atslēgu galvenē Authorization: Authorization: Bearer <atslēga>.

Vaicājuma parametri

  • collectionstring | null
  • folderstring | null

    <folder ID> atgriež mapes un visu tās apakšmapju kartītes. none atgriež tās kolekcijas kartītes, kas nav nevienā mapē, un prasa collection (citādi 400 cards.invalid_folder_filter). Ja mape neeksistē vai jums nav redzama, pieprasījums atgriež 404 folders.not_found.

    length ≤ 64

  • statusstring | null

    Atļautās vērtības: processingreadyerrorarchivedall

  • ownerstring | null

    me, none vai lietotāja ID.

  • owner_idinteger | null
  • verificationstring | null

    Atļautās vērtības: verifiedneeds_verificationstale

  • kindCardKind
  • typestring | null

    table atgriež kartītes ar faktu tabulām, text – kartītes bez tām.

    Atļautās vērtības: tabletext

  • tagsstring | null

    Ar komatiem atdalītas birkas (kartītei jābūt visām).

  • idsstring | null

    Ar komatiem atdalīti kartīšu ID.

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

    Noklusējums: "created_at"

  • orderstring

    Atļautās vērtības: ascdesc

    Noklusējums: "desc"

  • limitinteger

    Noklusējums: 200

  • offsetinteger

    Noklusējums: 0

  • previewboolean

    true pievieno preview (pirmās 200 rakstzīmes) un preview_tables flīžu skatam.

    Noklusējums: false

  • updated_sincestring (date-time)

    Tikai kartītes, kuru updated_at ir šis brīdis vai vēlāks (RFC 3339 ar laika joslas nobīdi), sinhronizācijai. Ja sort un order nav norādīti tieši, saraksts tiek kārtots pēc updated_at augošā secībā, pēc tam pēc id. Dzēstās kartītes sarakstā neparādās: par dzēšanu ziņo notikumi.

  • metadatamap of string

    Filtrs pēc metadata: metadata[<key>]=<value> pārbauda precīzu atbilstību. Līdz 3 nosacījumiem, un visiem jāizpildās (?metadata[team]=support&metadata[crm_id]=A-1042). Ja nosacījumu ir vairāk nekā 3 vai atslēga nav derīga, atbilde ir 400 api.metadata_invalid.

  • collection_idinteger

    Kolekcija pēc ID. Ja nodots arī collection, noteicošais ir collection_id. Ja kolekcija organizācijā neeksistē vai nav redzama, atbilde ir 404 collections.not_found.

  • external_idstring

    Tikai kartīte ar šo external_id.

  • cursorstring

    Nākamās lapas kursors no X-Next-Cursor vai next_cursor iepriekšējā atbildē ar tiem pašiem filtriem; tas ietver lapas izmēru. Kopā ar offset – 422 validation.failed; cita saraksta kursors, kursors ar citiem filtriem vai bojāts kursors – 400 api.cursor_invalid.

    length ≤ 512

  • expand[]array of string

    Saistītie objekti, ko iekļaut atbildē (kopš 1.62.0): ceļš no operācijas saraksta x-expandable. Parametru var atkārtot līdz 10 reizēm. Ceļā ir līdz 2 segmentiem, kas atdalīti ar punktu (collection.default_owner). Sarakstā ceļš sākas ar data. un attiecas uz katru lapas elementu (expand[]=data.owner). Izvērstais objekts tiek ievietots elementa objektā expanded, un ID lauks paliek. Objekts, ko izsaucējs nedrīkst redzēt saskaņā ar tā lasīšanas operācijas pārbaudēm, tiek izvērsts kā null. Nezināms ceļš, vairāk nekā 10 ceļi vai ceļš, kas garāks par 2 segmentiem, atgriež 400 api.expand_invalid.

    items ≤ 10

Galvenes parametri

  • X-View-Asstring

    Tikai API atslēgām ar lomu admin. Izpilda pieprasījumu datu profila <profile>[:viewer|verifier|editor] vārdā, piemēram, employee:viewer. Instalācijas atslēga šo galveni lietot nevar (403).

Sīkdatņu parametri

  • kb_view_asstring

    Režīma „View as“ (skatīt kā) sīkdatne sesijai. POST /auth/view-as to iestata, un DELETE /auth/view-as to notīra.

Atbildes

200Veiksmīga atbilde

Atbildes galvenes

  • Link

    Nākamās lapas adrese, <…>; rel="next". Ja galvenes nav, šī ir pēdējā lapa.

  • X-Next-Cursor

    Nākamās lapas kursors parametram cursor. Ja galvenes nav, šī ir pēdējā lapa.

  • RateLimit-Policy

    Spēkā esošie limiti IETF dokumenta projekta draft-ietf-httpapi-ratelimit-headers formātā: ar komatiem atdalīti elementi "<name>";q=<quota>;w=<window in seconds>. key ir API atslēgas pieprasījumu biežums (kvota ir īslaicīgais pīķis, laika logs – laiks, kurā kvota pilnībā atjaunojas; sesijai tas ir user, bez akreditācijas datiem – ip); minute, day un month ir organizācijas kvotas kalendārajai minūtei, dienai un mēnesim pēc UTC.

  • RateLimit

    Cik atlicis no katra RateLimit-Policy limita: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Stingrākā RateLimit-Policy ieraksta limits (tā, kurā atlicis vismazāk pieprasījumu).

  • X-RateLimit-Remaining

    Atlikušo pieprasījumu skaits stingrākā limita ietvaros.

  • X-RateLimit-Reset

    Sekundes līdz stingrākā limita atiestatīšanai.

application/json

Objekts: CardList

array of Card
  • expandedCardExpanded
  • permissionsObjectPermissionList
  • accessstring

    Atļautās vērtības: wholepartial

  • access_contactstring

    Pie kā vērsties pēc piekļuves (tikai tad, ja access=partial).

  • aclobject
    Lauki
    • verifybooleanobligāts
    • writebooleanobligāts
  • categorystringobligāts
  • category_confidencenumber | nullobligāts
  • category_lockedbooleanobligāts
  • category_reviewbooleanobligāts
  • category_sourceCategorySource | nullobligāts
  • collectionstringobligāts
  • collection_idintegerobligāts
  • collection_titlestring
  • commentsarray of CardComment
  • content_jsonContentJSON | null

    Pēdējās publicētās versijas redaktora saturs. Lauka var nebūt; tādā gadījumā redaktora saturu iegūstiet no melnraksta (POST /v1/drafts ar card_id).

  • editing_lockEditingLock | null

    Aktīvā rediģēšanas bloķēšana. Lauka var nebūt; tādā gadījumā redaktors uzzina, kam pieder bloķēšana, no 409 cards.locked atbildē uz POST /v1/cards/{card_id}/lock.

  • created_atstring (date-time)obligāts
  • days_since_verifiedintegerobligāts
  • errorstring | nullobligāts
  • eventsarray of CardEvent
  • feedback_negintegerobligāts
  • feedback_posintegerobligāts
  • foldersarray of CardFolderRef

    Tikai kartīšu sarakstā: mapes, kurās ir kartīte (lietotājam redzamās), ar to ceļiem no kolekcijas saknes. Tukšs saraksts nozīmē, ka kartīte nav nevienā mapē.

  • has_tablesboolean

    Tikai kartīšu sarakstā.

  • hidden_partsboolean
  • idstringobligāts
  • jobJob | null
  • kindCardKindobligāts
  • org_idintegerobligāts
  • owner_activeboolean | null
  • owner_idinteger | nullobligāts
  • owner_namestring | nullobligāts
  • pagesinteger | nullobligāts
  • parserstring | nullobligāts

    Dokumenta nolasīšanas veids kā neitrāls kods: document (pilna struktūra: lappuses, virsraksti, tabulas, skenētas lappuses), pdf (PDF teksta slānis), docx, xlsx, csv, markdown, html, text. Saraksts var paplašināties.

  • partsarray of CardPartobligāts
  • sensitivebooleanobligāts
  • sha256string | nullobligāts
  • sizeintegerobligāts
  • snoozed_atstring (date-time) | null
  • snoozed_byinteger | null
  • snoozed_untilstring | null
  • source_changedbooleanobligāts
  • source_pathstring | nullobligāts
  • source_urlstring | nullobligāts
  • statusstringobligāts

    Atļautās vērtības: processingreadyerrorarchived

  • tablesarray of CardTable
  • tagsarray of stringobligāts
  • titlestringobligāts
  • trustnumberobligāts
  • trust_if_verifiednumber
  • trust_partsTrustPartsobligāts
  • updated_atstring (date-time)obligāts
  • verificationVerificationobligāts
  • verified_atstring (date-time) | nullobligāts
  • verified_byinteger | nullobligāts
  • verified_by_namestring | null
  • verifier_idsarray of integerobligāts
  • verifiersarray of object
    Lauki
    • activebooleanobligāts
    • idintegerobligāts
    • namestringobligāts
  • verify_interval_daysintegerobligāts
  • versionintegerobligāts
  • versionsarray of CardVersion
  • source_archiveArchiveSource
  • created_byinteger | null
  • manual_optionsobject

    Manuālie nolasīšanas iestatījumi (priekšskatījums).

  • doc_kindDocKind | null

    Dokumenta tips. null, ja tips nav noteikts (piemēram, kartītēm, kas indeksētas pirms dokumentu tipu ieviešanas).

  • doc_kind_confidencenumber | null

    Pārliecības līmenis par dokumenta tipu, no 0 līdz 1.

  • doc_kind_sourcestring | null

    Kas noteica tipu: noteikumi (rules), lietotājs (manual) vai automātiska klasifikācija. Saraksts var paplašināties: nezināmu vērtību uzskatiet par automātisku klasifikāciju.

    Atļautās vērtības: rulesmanualnull

  • invoiceDocInvoiceExtraction | null

    Rēķina, kredītrēķina vai čeka lauki (tikai šiem tipiem un tikai kartītē, ne sarakstā). null, ja jums nav piekļuves visam dokumentam, jo lauki tiek iegūti no visa dokumenta.

  • warningsarray of ReviewWarning

    Dokumenta nolasīšanas brīdinājumi (ReviewWarning; tikai kartītē, ne sarakstā).

  • enrichmentCardEnrichmentStatus | null

    Bagātināšanas statuss (tikai kartītē, ne sarakstā). Dokumenta tips, rēķina lauki un finanšu ieraksti tiek pievienoti fonā pēc indeksēšanas un vēlāk var tikt pārrēķināti; tie parādās kartītē, kad ir gatavi. null nozīmē, ka statuss nav pieejams (kartīte indeksēta bez bagātināšanas fonā).

  • external_idstring | null

    Kartītes ID integratora sistēmā. Tas ir unikāls organizācijā starp kartītēm, kas nenāk no avotiem; null nozīmē, ka tas nav iestatīts. /v1/cards-by-external-id/{external_id} pēc tā nolasa un aizstāj kartīti.

    length ≤ 512

  • metadataMetadata
400Pieprasījums nav derīgs: parametra vērtība vai objekta stāvoklis neļauj veikt darbību (`detail` ir ziņojums).

Atbildes galvenes

  • RateLimit-Policy

    Spēkā esošie limiti IETF dokumenta projekta draft-ietf-httpapi-ratelimit-headers formātā: ar komatiem atdalīti elementi "<name>";q=<quota>;w=<window in seconds>. key ir API atslēgas pieprasījumu biežums (kvota ir īslaicīgais pīķis, laika logs – laiks, kurā kvota pilnībā atjaunojas; sesijai tas ir user, bez akreditācijas datiem – ip); minute, day un month ir organizācijas kvotas kalendārajai minūtei, dienai un mēnesim pēc UTC.

  • RateLimit

    Cik atlicis no katra RateLimit-Policy limita: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Stingrākā RateLimit-Policy ieraksta limits (tā, kurā atlicis vismazāk pieprasījumu).

  • X-RateLimit-Remaining

    Atlikušo pieprasījumu skaits stingrākā limita ietvaros.

  • X-RateLimit-Reset

    Sekundes līdz stingrākā limita atiestatīšanai.

application/json

Objekts: Error

401Nav nosūtīti akreditācijas dati (ne sesijas sīkdatne, ne API atslēga), vai atslēga nav atrasta.

Atbildes galvenes

  • RateLimit-Policy

    Spēkā esošie limiti IETF dokumenta projekta draft-ietf-httpapi-ratelimit-headers formātā: ar komatiem atdalīti elementi "<name>";q=<quota>;w=<window in seconds>. key ir API atslēgas pieprasījumu biežums (kvota ir īslaicīgais pīķis, laika logs – laiks, kurā kvota pilnībā atjaunojas; sesijai tas ir user, bez akreditācijas datiem – ip); minute, day un month ir organizācijas kvotas kalendārajai minūtei, dienai un mēnesim pēc UTC.

  • RateLimit

    Cik atlicis no katra RateLimit-Policy limita: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Stingrākā RateLimit-Policy ieraksta limits (tā, kurā atlicis vismazāk pieprasījumu).

  • X-RateLimit-Remaining

    Atlikušo pieprasījumu skaits stingrākā limita ietvaros.

  • X-RateLimit-Reset

    Sekundes līdz stingrākā limita atiestatīšanai.

application/json

Objekts: Error

403Darbība nav atļauta: loma nav pietiekama, nav piekļuves kolekcijai vai kartītei, pieprasījums izpildās režīmā „View as“ vai organizācija ir apturēta vai dzēsta (`detail` ir objekts ar `code: org_suspended | org_deleted`).

Atbildes galvenes

  • RateLimit-Policy

    Spēkā esošie limiti IETF dokumenta projekta draft-ietf-httpapi-ratelimit-headers formātā: ar komatiem atdalīti elementi "<name>";q=<quota>;w=<window in seconds>. key ir API atslēgas pieprasījumu biežums (kvota ir īslaicīgais pīķis, laika logs – laiks, kurā kvota pilnībā atjaunojas; sesijai tas ir user, bez akreditācijas datiem – ip); minute, day un month ir organizācijas kvotas kalendārajai minūtei, dienai un mēnesim pēc UTC.

  • RateLimit

    Cik atlicis no katra RateLimit-Policy limita: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Stingrākā RateLimit-Policy ieraksta limits (tā, kurā atlicis vismazāk pieprasījumu).

  • X-RateLimit-Remaining

    Atlikušo pieprasījumu skaits stingrākā limita ietvaros.

  • X-RateLimit-Reset

    Sekundes līdz stingrākā limita atiestatīšanai.

application/json

Objekts: Error

404Objekts neeksistē vai jums nav pieejams. API neapstiprina, ka ierobežotas piekļuves objekts eksistē.

Atbildes galvenes

  • RateLimit-Policy

    Spēkā esošie limiti IETF dokumenta projekta draft-ietf-httpapi-ratelimit-headers formātā: ar komatiem atdalīti elementi "<name>";q=<quota>;w=<window in seconds>. key ir API atslēgas pieprasījumu biežums (kvota ir īslaicīgais pīķis, laika logs – laiks, kurā kvota pilnībā atjaunojas; sesijai tas ir user, bez akreditācijas datiem – ip); minute, day un month ir organizācijas kvotas kalendārajai minūtei, dienai un mēnesim pēc UTC.

  • RateLimit

    Cik atlicis no katra RateLimit-Policy limita: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Stingrākā RateLimit-Policy ieraksta limits (tā, kurā atlicis vismazāk pieprasījumu).

  • X-RateLimit-Remaining

    Atlikušo pieprasījumu skaits stingrākā limita ietvaros.

  • X-RateLimit-Reset

    Sekundes līdz stingrākā limita atiestatīšanai.

application/json

Objekts: Error

422Validācijas kļūda: saturs vai parametri neatbilst shēmai (`detail` ir validācijas kļūdu saraksts), vai parametra vērtība ir ārpus pieļaujamā diapazona (`detail` ir ziņojums).

Atbildes galvenes

  • RateLimit-Policy

    Spēkā esošie limiti IETF dokumenta projekta draft-ietf-httpapi-ratelimit-headers formātā: ar komatiem atdalīti elementi "<name>";q=<quota>;w=<window in seconds>. key ir API atslēgas pieprasījumu biežums (kvota ir īslaicīgais pīķis, laika logs – laiks, kurā kvota pilnībā atjaunojas; sesijai tas ir user, bez akreditācijas datiem – ip); minute, day un month ir organizācijas kvotas kalendārajai minūtei, dienai un mēnesim pēc UTC.

  • RateLimit

    Cik atlicis no katra RateLimit-Policy limita: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Stingrākā RateLimit-Policy ieraksta limits (tā, kurā atlicis vismazāk pieprasījumu).

  • X-RateLimit-Remaining

    Atlikušo pieprasījumu skaits stingrākā limita ietvaros.

  • X-RateLimit-Reset

    Sekundes līdz stingrākā limita atiestatīšanai.

application/json

Objekts: Error

429Pārāk daudz pieprasījumu (`api.rate_limited`), organizācijas minūtes, dienas vai mēneša kvota ir izlietota (`api.quota_exceeded`; `error.details` satur `quota`, `limit` un `reset_at`), sasniegts organizācijas limits vai atbilžu pakalpojums ir aizņemts (`answers.engine_busy`). Pagaidiet galvenē `Retry-After` norādīto laiku.

Atbildes galvenes

  • Retry-After

    Sekunžu skaits, kas jāpagaida, pirms atkārtojat pieprasījumu.

  • RateLimit-Policy

    Spēkā esošie limiti IETF dokumenta projekta draft-ietf-httpapi-ratelimit-headers formātā: ar komatiem atdalīti elementi "<name>";q=<quota>;w=<window in seconds>. key ir API atslēgas pieprasījumu biežums (kvota ir īslaicīgais pīķis, laika logs – laiks, kurā kvota pilnībā atjaunojas; sesijai tas ir user, bez akreditācijas datiem – ip); minute, day un month ir organizācijas kvotas kalendārajai minūtei, dienai un mēnesim pēc UTC.

  • RateLimit

    Cik atlicis no katra RateLimit-Policy limita: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Stingrākā RateLimit-Policy ieraksta limits (tā, kurā atlicis vismazāk pieprasījumu).

  • X-RateLimit-Remaining

    Atlikušo pieprasījumu skaits stingrākā limita ietvaros.

  • X-RateLimit-Reset

    Sekundes līdz stingrākā limita atiestatīšanai.

application/json

Objekts: Error

Kļūdu kodi

Kodi, ko šī operācija var atgriezt laukā error.code papildus vispārīgajiem kodiem, kas iespējami jebkuram pieprasījumam.

Pieprasījumu biežuma limiti

Atbildēs ir galvenes RateLimit un RateLimit-Policy, kā arī agrākās X-RateLimit-Limit, X-RateLimit-Remaining un X-RateLimit-Reset. Atbildē 429 ir galvene Retry-After sekundēs: nogaidiet un atkārtojiet pieprasījumu.

← cards · API rokasgrāmata