Przejdź do treści
Sursa Developers

GET/v1/cards-by-external-id/{external_id}

Pobieranie karty według identyfikatora zewnętrznego

get_card_by_external_id

Zwraca tę samą kartę z tymi samymi kontrolami dostępu co GET /v1/cards/{card_id}, wskazaną przez external_id integratora. Jeśli organizacja nie ma karty z tym external_id lub karta nie jest widoczna dla wywołującego, żądanie zwraca 404 cards.not_found.

Uwierzytelnianie

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

Parametry ścieżki

  • external_idstringwymagane

    external_id karty: ciąg 1–512 znaków, unikalny w organizacji.

    length ≥ 1, length ≤ 512

Parametry zapytania

  • 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

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