Przejdź do treści
Sursa Developers

GET/v1/cards

Pobieranie listy kart

list_cards

Zwraca karty z filtrami, sortowaniem i stronicowaniem. Z preview=1 (dla widoku kafelków) każda karta ma też preview (pierwsze 200 znaków tekstu) i preview_tables (arkusze z liczbą wierszy) – w granicach Twojego profilu dostępu.

Uwierzytelnianie

Wyślij klucz API w nagłówku Authorization: Authorization: Bearer <klucz>.

Parametry zapytania

  • collectionstring | null
  • folderstring | null

    <folder ID> zwraca karty folderu i wszystkich jego podfolderów. none zwraca karty kolekcji, które nie są w żadnym folderze, i wymaga collection (w przeciwnym razie 400 cards.invalid_folder_filter). Jeśli folder nie istnieje lub nie jest dla Ciebie widoczny, żądanie zwraca 404 folders.not_found.

    length ≤ 64

  • statusstring | null

    Dozwolone wartości: processingreadyerrorarchivedall

  • ownerstring | null

    me, none lub ID użytkownika.

  • owner_idinteger | null
  • verificationstring | null

    Dozwolone wartości: verifiedneeds_verificationstale

  • kindCardKind
  • typestring | null

    table zwraca karty z tabelami faktów, text – karty bez nich.

    Dozwolone wartości: tabletext

  • tagsstring | null

    Tagi rozdzielone przecinkami (karta musi mieć wszystkie).

  • idsstring | null

    ID kart rozdzielone przecinkami.

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

    Domyślnie: "created_at"

  • orderstring

    Dozwolone wartości: ascdesc

    Domyślnie: "desc"

  • limitinteger

    Domyślnie: 200

  • offsetinteger

    Domyślnie: 0

  • previewboolean

    true dodaje preview (pierwsze 200 znaków) i preview_tables dla widoku kafelków.

    Domyślnie: false

  • updated_sincestring (date-time)

    Tylko karty z updated_at w tym momencie lub później (RFC 3339 z przesunięciem strefy czasowej), do synchronizacji. Bez jawnych sort i order lista jest sortowana rosnąco według updated_at, a następnie według id. Usuniętych kart nie ma na liście: usunięcia przychodzą jako zdarzenia.

  • metadatamap of string

    Filtr według metadata: metadata[<key>]=<value> oznacza dokładne dopasowanie. Do 3 warunków, wszystkie muszą być spełnione (?metadata[team]=support&metadata[crm_id]=A-1042). Więcej niż 3 warunki lub nieprawidłowy klucz zwracają 400 api.metadata_invalid.

  • collection_idinteger

    Kolekcja według ID. Gdy przekazano też collection, pierwszeństwo ma collection_id. Kolekcja, która nie istnieje w organizacji lub nie jest widoczna, zwraca 404 collections.not_found.

  • external_idstring

    Tylko karta z tym external_id.

  • cursorstring

    Kursor następnej strony z X-Next-Cursor lub next_cursor poprzedniej odpowiedzi z tymi samymi filtrami; zawiera rozmiar strony. Razem z offset: 422 validation.failed; kursor innej listy, innych filtrów lub uszkodzony: 400 api.cursor_invalid.

    length ≤ 512

  • expand[]array of string

    Powiązane obiekty, które mają się znaleźć w odpowiedzi (od wersji 1.62.0): ścieżka z listy x-expandable operacji. Parametr można powtórzyć do 10 razy. Ścieżka ma do 2 segmentów rozdzielonych kropką (collection.default_owner). Na liście ścieżka zaczyna się od data. i dotyczy każdego elementu strony (expand[]=data.owner). Rozwinięty obiekt trafia do obiektu expanded elementu, a pole ID pozostaje na miejscu. Obiekt, którego wywołujący nie może widzieć według kontroli jego własnej operacji odczytu, jest rozwijany jako null. Nieznana ścieżka, więcej niż 10 ścieżek lub ścieżka głębsza niż 2 segmenty zwraca 400 api.expand_invalid.

    items ≤ 10

Parametry nagłówka

  • X-View-Asstring

    Tylko dla kluczy API z rolą admin. Wykonuje żądanie jako profil dostępu <profile>[:viewer|verifier|editor], np. employee:viewer. Klucz instalacji nie może używać tego nagłówka (403).

Parametry cookie

  • kb_view_asstring

    Plik cookie trybu „View as” dla sesji. POST /auth/view-as go ustawia, a DELETE /auth/view-as usuwa.

Odpowiedzi

200Pomyślna odpowiedź

Nagłówki odpowiedzi

  • Link

    Adres następnej strony, <…>; rel="next". Brak nagłówka oznacza, że to ostatnia strona.

  • X-Next-Cursor

    Kursor następnej strony dla parametru cursor. Brak nagłówka oznacza, że to ostatnia strona.

  • RateLimit-Policy

    Obowiązujące limity w formacie projektu IETF draft-ietf-httpapi-ratelimit-headers: elementy rozdzielone przecinkami "<name>";q=<quota>;w=<window in seconds>. key to częstotliwość żądań klucza API (przydział to wielkość chwilowego szczytu (burst), okno to czas jego pełnego odnowienia; dla sesji jest to user, bez danych uwierzytelniających ip); minute, day i month to przydziały organizacji na minutę, dzień i miesiąc kalendarzowy w UTC.

  • RateLimit

    Co pozostało z każdego limitu w RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit najbardziej restrykcyjnej pozycji w RateLimit-Policy (tej, w której zostało najmniej żądań).

  • X-RateLimit-Remaining

    Liczba żądań pozostałych w ramach najbardziej restrykcyjnego limitu.

  • X-RateLimit-Reset

    Liczba sekund do odnowienia najbardziej restrykcyjnego limitu.

application/json

Obiekt: CardList

array of Card
  • expandedCardExpanded
  • permissionsObjectPermissionList
  • accessstring

    Dozwolone wartości: wholepartial

  • access_contactstring

    Z kim kontaktować się w sprawie dostępu (tylko gdy access=partial).

  • aclobject
    Pola
    • verifybooleanwymagane
    • writebooleanwymagane
  • categorystringwymagane
  • category_confidencenumber | nullwymagane
  • category_lockedbooleanwymagane
  • category_reviewbooleanwymagane
  • category_sourceCategorySource | nullwymagane
  • collectionstringwymagane
  • collection_idintegerwymagane
  • collection_titlestring
  • commentsarray of CardComment
  • content_jsonContentJSON | null

    Zawartość edytora najnowszej opublikowanej wersji. Pola może nie być; wtedy pobierz zawartość edytora ze szkicu (POST /v1/drafts z card_id).

  • editing_lockEditingLock | null

    Aktywna blokada edycji. Pola może nie być; wtedy edytor dowiaduje się, kto trzyma blokadę, z 409 cards.locked przy POST /v1/cards/{card_id}/lock.

  • created_atstring (date-time)wymagane
  • days_since_verifiedintegerwymagane
  • errorstring | nullwymagane
  • eventsarray of CardEvent
  • feedback_negintegerwymagane
  • feedback_posintegerwymagane
  • foldersarray of CardFolderRef

    Tylko na liście kart: foldery zawierające kartę (te, które widzi użytkownik), ze ścieżkami od najwyższego poziomu kolekcji. Pusta lista oznacza, że karta nie jest w żadnym folderze.

  • has_tablesboolean

    Tylko na liście kart.

  • hidden_partsboolean
  • idstringwymagane
  • jobJob | null
  • kindCardKindwymagane
  • org_idintegerwymagane
  • owner_activeboolean | null
  • owner_idinteger | nullwymagane
  • owner_namestring | nullwymagane
  • pagesinteger | nullwymagane
  • parserstring | nullwymagane

    Parser dokumentu jako kod neutralny: document (pełna struktura: strony, nagłówki, tabele, zeskanowane strony), pdf (warstwa tekstowa PDF), docx, xlsx, csv, markdown, html, text. Lista może się rozszerzać.

  • partsarray of CardPartwymagane
  • sensitivebooleanwymagane
  • sha256string | nullwymagane
  • sizeintegerwymagane
  • snoozed_atstring (date-time) | null
  • snoozed_byinteger | null
  • snoozed_untilstring | null
  • source_changedbooleanwymagane
  • source_pathstring | nullwymagane
  • source_urlstring | nullwymagane
  • statusstringwymagane

    Dozwolone wartości: processingreadyerrorarchived

  • tablesarray of CardTable
  • tagsarray of stringwymagane
  • titlestringwymagane
  • trustnumberwymagane
  • trust_if_verifiednumber
  • trust_partsTrustPartswymagane
  • updated_atstring (date-time)wymagane
  • verificationVerificationwymagane
  • verified_atstring (date-time) | nullwymagane
  • verified_byinteger | nullwymagane
  • verified_by_namestring | null
  • verifier_idsarray of integerwymagane
  • verifiersarray of object
    Pola
    • activebooleanwymagane
    • idintegerwymagane
    • namestringwymagane
  • verify_interval_daysintegerwymagane
  • versionintegerwymagane
  • versionsarray of CardVersion
  • source_archiveArchiveSource
  • created_byinteger | null
  • manual_optionsobject

    Ręczne ustawienia parsowania (podgląd).

  • doc_kindDocKind | null

    Typ dokumentu. null, jeśli typu nie określono (np. dla kart zindeksowanych przed wprowadzeniem typów dokumentów).

  • doc_kind_confidencenumber | null

    Poziom pewności typu dokumentu, od 0 do 1.

  • doc_kind_sourcestring | null

    Co określiło typ: reguły (rules), użytkownik (manual) lub automatyczna klasyfikacja. Lista może się rozszerzać: nieznaną wartość traktuj jako automatyczną klasyfikację.

    Dozwolone wartości: rulesmanualnull

  • invoiceDocInvoiceExtraction | null

    Pola faktury, faktury korygującej lub paragonu (tylko dla tych typów i tylko w karcie, nie na liście). null, jeśli nie masz dostępu do całego dokumentu, bo pola są wyodrębniane z całego dokumentu.

  • warningsarray of ReviewWarning

    Ostrzeżenia z parsowania dokumentu (ReviewWarning; tylko w karcie, nie na liście).

  • enrichmentCardEnrichmentStatus | null

    Stan wzbogacania (tylko w karcie, nie na liście). Typ dokumentu, pola faktury i wpisy finansowe są dodawane w tle po indeksowaniu i mogą zostać później przeliczone; pojawiają się w karcie, gdy są gotowe. null oznacza, że stan jest niedostępny (karta została zindeksowana bez wzbogacania w tle).

  • external_idstring | null

    ID karty w systemie integratora. Jest unikalny w organizacji wśród kart, które nie pochodzą ze źródeł; null oznacza, że nie jest ustawiony. /v1/cards-by-external-id/{external_id} odczytuje i zastępuje kartę według niego.

    length ≤ 512

  • metadataMetadata
400Żądanie jest nieprawidłowe: wartość parametru lub stan obiektu nie pozwala na to działanie (`detail` zawiera komunikat).

Nagłówki odpowiedzi

  • RateLimit-Policy

    Obowiązujące limity w formacie projektu IETF draft-ietf-httpapi-ratelimit-headers: elementy rozdzielone przecinkami "<name>";q=<quota>;w=<window in seconds>. key to częstotliwość żądań klucza API (przydział to wielkość chwilowego szczytu (burst), okno to czas jego pełnego odnowienia; dla sesji jest to user, bez danych uwierzytelniających ip); minute, day i month to przydziały organizacji na minutę, dzień i miesiąc kalendarzowy w UTC.

  • RateLimit

    Co pozostało z każdego limitu w RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit najbardziej restrykcyjnej pozycji w RateLimit-Policy (tej, w której zostało najmniej żądań).

  • X-RateLimit-Remaining

    Liczba żądań pozostałych w ramach najbardziej restrykcyjnego limitu.

  • X-RateLimit-Reset

    Liczba sekund do odnowienia najbardziej restrykcyjnego limitu.

application/json

Obiekt: Error

401Nie przesłano danych uwierzytelniających (ani pliku cookie sesji, ani klucza API) lub nie znaleziono klucza.

Nagłówki odpowiedzi

  • RateLimit-Policy

    Obowiązujące limity w formacie projektu IETF draft-ietf-httpapi-ratelimit-headers: elementy rozdzielone przecinkami "<name>";q=<quota>;w=<window in seconds>. key to częstotliwość żądań klucza API (przydział to wielkość chwilowego szczytu (burst), okno to czas jego pełnego odnowienia; dla sesji jest to user, bez danych uwierzytelniających ip); minute, day i month to przydziały organizacji na minutę, dzień i miesiąc kalendarzowy w UTC.

  • RateLimit

    Co pozostało z każdego limitu w RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit najbardziej restrykcyjnej pozycji w RateLimit-Policy (tej, w której zostało najmniej żądań).

  • X-RateLimit-Remaining

    Liczba żądań pozostałych w ramach najbardziej restrykcyjnego limitu.

  • X-RateLimit-Reset

    Liczba sekund do odnowienia najbardziej restrykcyjnego limitu.

application/json

Obiekt: Error

403Działanie jest niedozwolone: rola jest niewystarczająca, brak dostępu do kolekcji lub karty, żądanie jest wykonywane w trybie „View as” albo organizacja jest zawieszona lub usunięta (`detail` to obiekt z `code: org_suspended | org_deleted`).

Nagłówki odpowiedzi

  • RateLimit-Policy

    Obowiązujące limity w formacie projektu IETF draft-ietf-httpapi-ratelimit-headers: elementy rozdzielone przecinkami "<name>";q=<quota>;w=<window in seconds>. key to częstotliwość żądań klucza API (przydział to wielkość chwilowego szczytu (burst), okno to czas jego pełnego odnowienia; dla sesji jest to user, bez danych uwierzytelniających ip); minute, day i month to przydziały organizacji na minutę, dzień i miesiąc kalendarzowy w UTC.

  • RateLimit

    Co pozostało z każdego limitu w RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit najbardziej restrykcyjnej pozycji w RateLimit-Policy (tej, w której zostało najmniej żądań).

  • X-RateLimit-Remaining

    Liczba żądań pozostałych w ramach najbardziej restrykcyjnego limitu.

  • X-RateLimit-Reset

    Liczba sekund do odnowienia najbardziej restrykcyjnego limitu.

application/json

Obiekt: Error

404Obiekt nie istnieje lub nie jest dla Ciebie dostępny. API nie potwierdza istnienia obiektu z ograniczonym dostępem.

Nagłówki odpowiedzi

  • RateLimit-Policy

    Obowiązujące limity w formacie projektu IETF draft-ietf-httpapi-ratelimit-headers: elementy rozdzielone przecinkami "<name>";q=<quota>;w=<window in seconds>. key to częstotliwość żądań klucza API (przydział to wielkość chwilowego szczytu (burst), okno to czas jego pełnego odnowienia; dla sesji jest to user, bez danych uwierzytelniających ip); minute, day i month to przydziały organizacji na minutę, dzień i miesiąc kalendarzowy w UTC.

  • RateLimit

    Co pozostało z każdego limitu w RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit najbardziej restrykcyjnej pozycji w RateLimit-Policy (tej, w której zostało najmniej żądań).

  • X-RateLimit-Remaining

    Liczba żądań pozostałych w ramach najbardziej restrykcyjnego limitu.

  • X-RateLimit-Reset

    Liczba sekund do odnowienia najbardziej restrykcyjnego limitu.

application/json

Obiekt: Error

422Błąd walidacji: treść lub parametry nie odpowiadają schematowi (`detail` to lista błędów walidacji) albo wartość parametru jest poza zakresem (`detail` zawiera komunikat).

Nagłówki odpowiedzi

  • RateLimit-Policy

    Obowiązujące limity w formacie projektu IETF draft-ietf-httpapi-ratelimit-headers: elementy rozdzielone przecinkami "<name>";q=<quota>;w=<window in seconds>. key to częstotliwość żądań klucza API (przydział to wielkość chwilowego szczytu (burst), okno to czas jego pełnego odnowienia; dla sesji jest to user, bez danych uwierzytelniających ip); minute, day i month to przydziały organizacji na minutę, dzień i miesiąc kalendarzowy w UTC.

  • RateLimit

    Co pozostało z każdego limitu w RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit najbardziej restrykcyjnej pozycji w RateLimit-Policy (tej, w której zostało najmniej żądań).

  • X-RateLimit-Remaining

    Liczba żądań pozostałych w ramach najbardziej restrykcyjnego limitu.

  • X-RateLimit-Reset

    Liczba sekund do odnowienia najbardziej restrykcyjnego limitu.

application/json

Obiekt: Error

429Zbyt wiele żądań (`api.rate_limited`), wyczerpano przydział organizacji na minutę, dzień lub miesiąc (`api.quota_exceeded`; `error.details` zawiera `quota`, `limit` i `reset_at`), osiągnięto limit organizacji albo usługa odpowiedzi jest zajęta (`answers.engine_busy`). Odczekaj czas podany w nagłówku `Retry-After`.

Nagłówki odpowiedzi

  • Retry-After

    Liczba sekund oczekiwania przed ponowieniem żądania.

  • RateLimit-Policy

    Obowiązujące limity w formacie projektu IETF draft-ietf-httpapi-ratelimit-headers: elementy rozdzielone przecinkami "<name>";q=<quota>;w=<window in seconds>. key to częstotliwość żądań klucza API (przydział to wielkość chwilowego szczytu (burst), okno to czas jego pełnego odnowienia; dla sesji jest to user, bez danych uwierzytelniających ip); minute, day i month to przydziały organizacji na minutę, dzień i miesiąc kalendarzowy w UTC.

  • RateLimit

    Co pozostało z każdego limitu w RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit najbardziej restrykcyjnej pozycji w RateLimit-Policy (tej, w której zostało najmniej żądań).

  • X-RateLimit-Remaining

    Liczba żądań pozostałych w ramach najbardziej restrykcyjnego limitu.

  • X-RateLimit-Reset

    Liczba sekund do odnowienia najbardziej restrykcyjnego limitu.

application/json

Obiekt: Error

Kody błędów

Kody, które ta operacja może zwrócić w error.code, oprócz ogólnych kodów każdego żądania.

Limity częstotliwości

Odpowiedzi zawierają nagłówki RateLimit i RateLimit-Policy oraz starsze X-RateLimit-Limit, X-RateLimit-Remaining i X-RateLimit-Reset. Odpowiedź 429 ma nagłówek Retry-After w sekundach: odczekaj i ponów żądanie.

← cards · Dokumentacja API