Przejdź do treści
Sursa Developers

POST/v1/cards/{card_id}/verify

Potwierdzanie aktualności karty

verify_card

Uwierzytelnianie

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

Parametry ścieżki

  • card_idstringwymagane

Parametry nagłówka

  • Idempotency-Keystring

    Klucz bezpiecznego ponowienia zapisu: od 1 do 255 drukowalnych znaków ASCII; zalecany jest UUID v4 na każdą operację logiczną. Ponowienie z tym samym kluczem w ciągu 24 godzin nie wykonuje operacji ponownie: zwraca zapisaną odpowiedź (status, nagłówki i treść) z nagłówkiem Idempotency-Replayed: true. Ten sam klucz z inną metodą, ścieżką, Content-Type lub treścią zwraca 409 api.idempotency_mismatch; dopóki pierwsze żądanie jest jeszcze wykonywane – 409 api.idempotency_in_progress z Retry-After: 1. Po odpowiedzi 5xx lub 429 klucz zostaje zwolniony, a ponowienie wykonuje operację jeszcze raz. Klucz obowiązuje w obrębie organizacji i wywołującego (klucz API, użytkownik lub klucz własnego źródła).

    length ≥ 1, length ≤ 255

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

Treść żądania

application/json

Obiekt: VerifyRequest

  • notestring | null

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.

  • Idempotency-Replayed

    true oznacza, że odpowiedź została odtworzona z odpowiedzi zapisanej dla tego Idempotency-Key: operacja nie została wykonana ponownie.

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.

Bezpieczne ponawianie

Wysyłaj nagłówek Idempotency-Key (na przykład UUID) z każdym żądaniem POST i PATCH. Ponowienie z tym samym kluczem w ciągu 24 godzin zwraca zapisaną odpowiedź, zamiast ponownie wykonywać żądanie.

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