Salt la conținut
Sursa Developers

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

Obține o fișă după ID-ul extern

get_card_by_external_id

Returnează aceeași fișă, cu aceleași verificări de acces ca GET /v1/cards/{card_id}, adresată prin external_id al integratorului. Dacă organizația nu are nicio fișă cu acest external_id sau fișa nu este vizibilă pentru apelant, cererea returnează 404 cards.not_found.

Autentificare

Trimiteți o cheie API în antetul Authorization: Authorization: Bearer <cheie>.

Parametri de cale

  • external_idstringobligatoriu

    Câmpul external_id al fișei: un șir de 1–512 caractere, unic în organizație.

    length ≥ 1, length ≤ 512

Parametri de interogare

  • expand[]array of string

    Obiectele asociate de inclus în răspuns (din 1.62.0): o cale din lista x-expandable a operației. Repetați parametrul de cel mult 10 ori. O cale are cel mult 2 segmente separate prin punct (collection.default_owner). Într-o listă, calea începe cu data. și se aplică fiecărui element al paginii (expand[]=data.owner). Un obiect extins intră în obiectul expanded al elementului, iar câmpul cu ID-ul rămâne. Un obiect pe care apelantul nu are voie să-l vadă conform verificărilor operației proprii de citire este extins ca null. O cale necunoscută, mai mult de 10 căi sau o cale mai adâncă de 2 segmente returnează 400 api.expand_invalid.

    items ≤ 10

Parametri de antet

  • X-View-Asstring

    Doar pentru cheile API cu rolul admin. Execută cererea cu profilul de date <profile>[:viewer|verifier|editor], de exemplu employee:viewer. Cheia de instalare nu poate folosi acest antet (403).

Parametri cookie

  • kb_view_asstring

    Cookie-ul modului „View as” (vizualizare ca alt utilizator) pentru o sesiune. POST /auth/view-as îl setează, iar DELETE /auth/view-as îl șterge.

Răspunsuri

200Răspuns reușit

Antetele răspunsului

  • RateLimit-Policy

    Limitele în vigoare, în formatul proiectului IETF draft-ietf-httpapi-ratelimit-headers: elemente separate prin virgulă "<name>";q=<quota>;w=<window in seconds>. key este frecvența cererilor cheii API (cota este rafala, fereastra este timpul în care rafala se reface complet; pentru o sesiune este user, fără date de autentificare ip); minute, day și month sunt cotele organizației pentru minutul, ziua și luna calendaristice în UTC.

  • RateLimit

    Cât a rămas din fiecare limită din RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limita celei mai stricte intrări din RateLimit-Policy (cea cu cele mai puține cereri rămase).

  • X-RateLimit-Remaining

    Cereri rămase în cadrul celei mai stricte limite.

  • X-RateLimit-Reset

    Secunde până la resetarea celei mai stricte limite.

application/json

Obiect: Card

  • expandedCardExpanded
  • permissionsObjectPermissionList
  • accessstring

    Valori permise: wholepartial

  • access_contactstring

    Persoana de contactat pentru acces (doar când access=partial).

  • aclobject
    Câmpuri
    • verifybooleanobligatoriu
    • writebooleanobligatoriu
  • categorystringobligatoriu
  • category_confidencenumber | nullobligatoriu
  • category_lockedbooleanobligatoriu
  • category_reviewbooleanobligatoriu
  • category_sourceCategorySource | nullobligatoriu
  • collectionstringobligatoriu
  • collection_idintegerobligatoriu
  • collection_titlestring
  • commentsarray of CardComment
  • content_jsonContentJSON | null

    Conținutul din editor al ultimei versiuni publicate. Câmpul poate lipsi; în acest caz, obțineți conținutul din editor dintr-o schiță (POST /v1/drafts cu card_id).

  • editing_lockEditingLock | null

    Blocarea activă pentru editare. Câmpul poate lipsi; în acest caz, editorul află cine deține blocarea din 409 cards.locked la POST /v1/cards/{card_id}/lock.

  • created_atstring (date-time)obligatoriu
  • days_since_verifiedintegerobligatoriu
  • errorstring | nullobligatoriu
  • eventsarray of CardEvent
  • feedback_negintegerobligatoriu
  • feedback_posintegerobligatoriu
  • foldersarray of CardFolderRef

    Doar în lista fișelor: dosarele care conțin fișa (cele vizibile utilizatorului), cu căile lor de la rădăcina colecției. O listă goală înseamnă că fișa nu se află în niciun dosar.

  • has_tablesboolean

    Doar în lista fișelor.

  • hidden_partsboolean
  • idstringobligatoriu
  • jobJob | null
  • kindCardKindobligatoriu
  • org_idintegerobligatoriu
  • owner_activeboolean | null
  • owner_idinteger | nullobligatoriu
  • owner_namestring | nullobligatoriu
  • pagesinteger | nullobligatoriu
  • parserstring | nullobligatoriu

    Analizorul documentului, ca un cod neutru: document (structură completă: pagini, titluri, tabele, pagini scanate), pdf (stratul de text al PDF-ului), docx, xlsx, csv, markdown, html, text. Lista se poate extinde.

  • partsarray of CardPartobligatoriu
  • sensitivebooleanobligatoriu
  • sha256string | nullobligatoriu
  • sizeintegerobligatoriu
  • snoozed_atstring (date-time) | null
  • snoozed_byinteger | null
  • snoozed_untilstring | null
  • source_changedbooleanobligatoriu
  • source_pathstring | nullobligatoriu
  • source_urlstring | nullobligatoriu
  • statusstringobligatoriu

    Valori permise: processingreadyerrorarchived

  • tablesarray of CardTable
  • tagsarray of stringobligatoriu
  • titlestringobligatoriu
  • trustnumberobligatoriu
  • trust_if_verifiednumber
  • trust_partsTrustPartsobligatoriu
  • updated_atstring (date-time)obligatoriu
  • verificationVerificationobligatoriu
  • verified_atstring (date-time) | nullobligatoriu
  • verified_byinteger | nullobligatoriu
  • verified_by_namestring | null
  • verifier_idsarray of integerobligatoriu
  • verifiersarray of object
    Câmpuri
    • activebooleanobligatoriu
    • idintegerobligatoriu
    • namestringobligatoriu
  • verify_interval_daysintegerobligatoriu
  • versionintegerobligatoriu
  • versionsarray of CardVersion
  • source_archiveArchiveSource
  • created_byinteger | null
  • manual_optionsobject

    Setările manuale de analiză a documentului (previzualizare).

  • doc_kindDocKind | null

    Tipul documentului. null dacă tipul nu este determinat (de exemplu, pentru fișele indexate înainte de introducerea tipurilor de documente).

  • doc_kind_confidencenumber | null

    Gradul de certitudine al tipului documentului, de la 0 la 1.

  • doc_kind_sourcestring | null

    Ce a determinat tipul: regulile (rules), un utilizator (manual) sau clasificarea automată. Lista se poate extinde: tratați o valoare necunoscută drept clasificare automată.

    Valori permise: rulesmanualnull

  • invoiceDocInvoiceExtraction | null

    Câmpurile unei facturi, ale unei note de credit sau ale unei chitanțe (doar pentru aceste tipuri și doar în fișă, nu în listă). null dacă nu aveți acces la întregul document, deoarece câmpurile se extrag din întregul document.

  • warningsarray of ReviewWarning

    Avertismentele analizei documentului (ReviewWarning; doar în fișă, nu în listă).

  • enrichmentCardEnrichmentStatus | null

    Starea îmbogățirii (doar în fișă, nu în listă). Tipul documentului, câmpurile facturii și înregistrările financiare se adaugă în fundal după indexare și pot fi recalculate ulterior; apar în fișă când sunt gata. null înseamnă că nu există nicio stare (fișa a fost indexată fără îmbogățire în fundal).

  • external_idstring | null

    ID-ul fișei în sistemul integratorului. Este unic în organizație printre fișele care nu provin din surse; null înseamnă că nu este setat. /v1/cards-by-external-id/{external_id} citește și înlocuiește fișa după el.

    length ≤ 512

  • metadataMetadata
400Cererea este invalidă: valoarea unui parametru sau starea obiectului nu permite acțiunea (`detail` este un mesaj).

Antetele răspunsului

  • RateLimit-Policy

    Limitele în vigoare, în formatul proiectului IETF draft-ietf-httpapi-ratelimit-headers: elemente separate prin virgulă "<name>";q=<quota>;w=<window in seconds>. key este frecvența cererilor cheii API (cota este rafala, fereastra este timpul în care rafala se reface complet; pentru o sesiune este user, fără date de autentificare ip); minute, day și month sunt cotele organizației pentru minutul, ziua și luna calendaristice în UTC.

  • RateLimit

    Cât a rămas din fiecare limită din RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limita celei mai stricte intrări din RateLimit-Policy (cea cu cele mai puține cereri rămase).

  • X-RateLimit-Remaining

    Cereri rămase în cadrul celei mai stricte limite.

  • X-RateLimit-Reset

    Secunde până la resetarea celei mai stricte limite.

application/json

Obiect: Error

401Nu au fost trimise date de autentificare (nici cookie de sesiune, nici cheie API) sau cheia nu a fost găsită.

Antetele răspunsului

  • RateLimit-Policy

    Limitele în vigoare, în formatul proiectului IETF draft-ietf-httpapi-ratelimit-headers: elemente separate prin virgulă "<name>";q=<quota>;w=<window in seconds>. key este frecvența cererilor cheii API (cota este rafala, fereastra este timpul în care rafala se reface complet; pentru o sesiune este user, fără date de autentificare ip); minute, day și month sunt cotele organizației pentru minutul, ziua și luna calendaristice în UTC.

  • RateLimit

    Cât a rămas din fiecare limită din RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limita celei mai stricte intrări din RateLimit-Policy (cea cu cele mai puține cereri rămase).

  • X-RateLimit-Remaining

    Cereri rămase în cadrul celei mai stricte limite.

  • X-RateLimit-Reset

    Secunde până la resetarea celei mai stricte limite.

application/json

Obiect: Error

403Acțiunea nu este permisă: rolul este insuficient, nu există acces la colecție sau la fișă, cererea rulează în modul „View as” (vizualizare ca alt utilizator) sau organizația este suspendată ori ștearsă (`detail` este un obiect cu `code: org_suspended | org_deleted`).

Antetele răspunsului

  • RateLimit-Policy

    Limitele în vigoare, în formatul proiectului IETF draft-ietf-httpapi-ratelimit-headers: elemente separate prin virgulă "<name>";q=<quota>;w=<window in seconds>. key este frecvența cererilor cheii API (cota este rafala, fereastra este timpul în care rafala se reface complet; pentru o sesiune este user, fără date de autentificare ip); minute, day și month sunt cotele organizației pentru minutul, ziua și luna calendaristice în UTC.

  • RateLimit

    Cât a rămas din fiecare limită din RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limita celei mai stricte intrări din RateLimit-Policy (cea cu cele mai puține cereri rămase).

  • X-RateLimit-Remaining

    Cereri rămase în cadrul celei mai stricte limite.

  • X-RateLimit-Reset

    Secunde până la resetarea celei mai stricte limite.

application/json

Obiect: Error

404Obiectul nu există sau nu vă este disponibil. API-ul nu confirmă existența unui obiect restricționat.

Antetele răspunsului

  • RateLimit-Policy

    Limitele în vigoare, în formatul proiectului IETF draft-ietf-httpapi-ratelimit-headers: elemente separate prin virgulă "<name>";q=<quota>;w=<window in seconds>. key este frecvența cererilor cheii API (cota este rafala, fereastra este timpul în care rafala se reface complet; pentru o sesiune este user, fără date de autentificare ip); minute, day și month sunt cotele organizației pentru minutul, ziua și luna calendaristice în UTC.

  • RateLimit

    Cât a rămas din fiecare limită din RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limita celei mai stricte intrări din RateLimit-Policy (cea cu cele mai puține cereri rămase).

  • X-RateLimit-Remaining

    Cereri rămase în cadrul celei mai stricte limite.

  • X-RateLimit-Reset

    Secunde până la resetarea celei mai stricte limite.

application/json

Obiect: Error

422Eroare de validare: corpul sau parametrii nu corespund schemei (`detail` este o listă de erori de validare) ori valoarea unui parametru este în afara intervalului permis (`detail` este un mesaj).

Antetele răspunsului

  • RateLimit-Policy

    Limitele în vigoare, în formatul proiectului IETF draft-ietf-httpapi-ratelimit-headers: elemente separate prin virgulă "<name>";q=<quota>;w=<window in seconds>. key este frecvența cererilor cheii API (cota este rafala, fereastra este timpul în care rafala se reface complet; pentru o sesiune este user, fără date de autentificare ip); minute, day și month sunt cotele organizației pentru minutul, ziua și luna calendaristice în UTC.

  • RateLimit

    Cât a rămas din fiecare limită din RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limita celei mai stricte intrări din RateLimit-Policy (cea cu cele mai puține cereri rămase).

  • X-RateLimit-Remaining

    Cereri rămase în cadrul celei mai stricte limite.

  • X-RateLimit-Reset

    Secunde până la resetarea celei mai stricte limite.

application/json

Obiect: Error

429Prea multe cereri (`api.rate_limited`), cota organizației pentru minut, zi sau lună este epuizată (`api.quota_exceeded`; `error.details` conține `quota`, `limit` și `reset_at`), limita organizației este atinsă sau serviciul de răspunsuri este ocupat (`answers.engine_busy`). Așteptați timpul indicat în antetul `Retry-After`.

Antetele răspunsului

  • Retry-After

    Numărul de secunde de așteptat înainte de a reîncerca cererea.

  • RateLimit-Policy

    Limitele în vigoare, în formatul proiectului IETF draft-ietf-httpapi-ratelimit-headers: elemente separate prin virgulă "<name>";q=<quota>;w=<window in seconds>. key este frecvența cererilor cheii API (cota este rafala, fereastra este timpul în care rafala se reface complet; pentru o sesiune este user, fără date de autentificare ip); minute, day și month sunt cotele organizației pentru minutul, ziua și luna calendaristice în UTC.

  • RateLimit

    Cât a rămas din fiecare limită din RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limita celei mai stricte intrări din RateLimit-Policy (cea cu cele mai puține cereri rămase).

  • X-RateLimit-Remaining

    Cereri rămase în cadrul celei mai stricte limite.

  • X-RateLimit-Reset

    Secunde până la resetarea celei mai stricte limite.

application/json

Obiect: Error

Coduri de eroare

Codurile pe care acest endpoint le poate returna în error.code, pe lângă codurile generale ale oricărei cereri.

Limite de frecvență

Răspunsurile conțin antetele RateLimit și RateLimit-Policy, precum și antetele anterioare X-RateLimit-Limit, X-RateLimit-Remaining și X-RateLimit-Reset. Un răspuns 429 conține Retry-After în secunde: așteptați și reîncercați.

← cards · Referința API