Pereiti prie turinio
Sursa Developers

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

Gauti kortelę pagal išorinį ID

get_card_by_external_id

Grąžina tą pačią kortelę su tomis pačiomis prieigos patikromis kaip GET /v1/cards/{card_id}, adresuojamą pagal integratoriaus external_id. Jei organizacijoje nėra kortelės su šiuo external_id arba kortelė iškvietėjui nematoma, užklausa grąžina 404 cards.not_found.

Autentifikavimas

Siųskite API raktą antraštėje Authorization: Authorization: Bearer <raktas>.

Kelio parametrai

  • external_idstringprivalomas

    Kortelės external_id: 1–512 simbolių eilutė, unikali organizacijoje.

    length ≥ 1, length ≤ 512

Užklausos parametrai

  • expand[]array of string

    Susiję objektai, kuriuos reikia įtraukti į atsaką (nuo 1.62.0): kelias iš operacijos sąrašo x-expandable. Parametrą kartokite iki 10 kartų. Kelią sudaro iki 2 segmentų, atskirtų tašku (collection.default_owner). Sąraše kelias prasideda data. ir taikomas kiekvienam puslapio elementui (expand[]=data.owner). Išplėstas objektas patenka į elemento objektą expanded, o ID laukas lieka. Objektas, kurio iškvietėjas negali matyti pagal jo paties skaitymo operacijos patikras, išplečiamas kaip null. Nežinomas kelias, daugiau nei 10 kelių arba gilesnis nei 2 segmentų kelias grąžina 400 api.expand_invalid.

    items ≤ 10

Antraštės parametrai

  • X-View-Asstring

    Tik API raktams su vaidmeniu admin. Užklausa vykdoma duomenų profilio <profile>[:viewer|verifier|editor] vardu, pvz., employee:viewer. Diegimo raktas šios antraštės naudoti negali (403).

Slapuko parametrai

  • kb_view_asstring

    Režimo „View as“ (žiūrėti kaip) sesijos slapukas. POST /auth/view-as jį nustato, o DELETE /auth/view-as išvalo.

Atsakai

200Sėkmingas atsakas

Atsako antraštės

  • RateLimit-Policy

    Galiojantys limitai IETF juodraščio draft-ietf-httpapi-ratelimit-headers formatu: kableliais atskirti elementai "<name>";q=<quota>;w=<window in seconds>. key – API rakto užklausų dažnis (kvota – pliūpsnis, laiko langas – laikas, per kurį kvota visiškai atsistato; sesijai tai user, be prisijungimo duomenų – ip); minute, day ir month – organizacijos kvotos kalendorinei minutei, dienai ir mėnesiui pagal UTC.

  • RateLimit

    Kiek liko kiekvieno RateLimit-Policy limito: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Griežčiausio RateLimit-Policy įrašo (kuriame liko mažiausiai užklausų) limitas.

  • X-RateLimit-Remaining

    Likusių užklausų skaičius pagal griežčiausią limitą.

  • X-RateLimit-Reset

    Sekundės iki griežčiausio limito atsistatymo.

application/json

Objektas: Card

  • expandedCardExpanded
  • permissionsObjectPermissionList
  • accessstring

    Leidžiamos reikšmės: wholepartial

  • access_contactstring

    Į ką kreiptis dėl prieigos (tik kai access=partial).

  • aclobject
    Laukai
    • verifybooleanprivalomas
    • writebooleanprivalomas
  • categorystringprivalomas
  • category_confidencenumber | nullprivalomas
  • category_lockedbooleanprivalomas
  • category_reviewbooleanprivalomas
  • category_sourceCategorySource | nullprivalomas
  • collectionstringprivalomas
  • collection_idintegerprivalomas
  • collection_titlestring
  • commentsarray of CardComment
  • content_jsonContentJSON | null

    Naujausios paskelbtos versijos redaktoriaus turinys. Lauko gali nebūti; tada redaktoriaus turinį gaukite iš juodraščio (POST /v1/drafts su card_id).

  • editing_lockEditingLock | null

    Aktyvus redagavimo užraktas. Lauko gali nebūti; tada redaktorius sužino, kas laiko užraktą, iš atsako 409 cards.locked į POST /v1/cards/{card_id}/lock.

  • created_atstring (date-time)privalomas
  • days_since_verifiedintegerprivalomas
  • errorstring | nullprivalomas
  • eventsarray of CardEvent
  • feedback_negintegerprivalomas
  • feedback_posintegerprivalomas
  • foldersarray of CardFolderRef

    Tik kortelių sąraše: aplankai, kuriuose yra kortelė (tie, kuriuos mato naudotojas), su keliais nuo rinkinio šaknies. Tuščias sąrašas reiškia, kad kortelės nėra jokiame aplanke.

  • has_tablesboolean

    Tik kortelių sąraše.

  • hidden_partsboolean
  • idstringprivalomas
  • jobJob | null
  • kindCardKindprivalomas
  • org_idintegerprivalomas
  • owner_activeboolean | null
  • owner_idinteger | nullprivalomas
  • owner_namestring | nullprivalomas
  • pagesinteger | nullprivalomas
  • parserstring | nullprivalomas

    Dokumento nuskaitymo priemonė kaip neutralus kodas: document (visa struktūra: puslapiai, antraštės, lentelės, nuskenuoti puslapiai), pdf (PDF teksto sluoksnis), docx, xlsx, csv, markdown, html, text. Sąrašas gali būti papildytas.

  • partsarray of CardPartprivalomas
  • sensitivebooleanprivalomas
  • sha256string | nullprivalomas
  • sizeintegerprivalomas
  • snoozed_atstring (date-time) | null
  • snoozed_byinteger | null
  • snoozed_untilstring | null
  • source_changedbooleanprivalomas
  • source_pathstring | nullprivalomas
  • source_urlstring | nullprivalomas
  • statusstringprivalomas

    Leidžiamos reikšmės: processingreadyerrorarchived

  • tablesarray of CardTable
  • tagsarray of stringprivalomas
  • titlestringprivalomas
  • trustnumberprivalomas
  • trust_if_verifiednumber
  • trust_partsTrustPartsprivalomas
  • updated_atstring (date-time)privalomas
  • verificationVerificationprivalomas
  • verified_atstring (date-time) | nullprivalomas
  • verified_byinteger | nullprivalomas
  • verified_by_namestring | null
  • verifier_idsarray of integerprivalomas
  • verifiersarray of object
    Laukai
    • activebooleanprivalomas
    • idintegerprivalomas
    • namestringprivalomas
  • verify_interval_daysintegerprivalomas
  • versionintegerprivalomas
  • versionsarray of CardVersion
  • source_archiveArchiveSource
  • created_byinteger | null
  • manual_optionsobject

    Rankiniai nuskaitymo nustatymai (peržiūra).

  • doc_kindDocKind | null

    Dokumento tipas. null, jei tipas nenustatytas (pavyzdžiui, kortelėms, indeksuotoms dar prieš atsirandant dokumentų tipams).

  • doc_kind_confidencenumber | null

    Dokumento tipo užtikrintumas, nuo 0 iki 1.

  • doc_kind_sourcestring | null

    Kas nustatė tipą: taisyklės (rules), naudotojas (manual) ar automatinis klasifikavimas. Sąrašas gali būti papildytas: nežinomą reikšmę laikykite automatiniu klasifikavimu.

    Leidžiamos reikšmės: rulesmanualnull

  • invoiceDocInvoiceExtraction | null

    Sąskaitos faktūros, kreditinės sąskaitos faktūros arba kvito laukai (tik šiems tipams ir tik kortelėje, ne sąraše). null, jei neturite prieigos prie viso dokumento, nes laukai išgaunami iš viso dokumento.

  • warningsarray of ReviewWarning

    Dokumento nuskaitymo įspėjimai (ReviewWarning; tik kortelėje, ne sąraše).

  • enrichmentCardEnrichmentStatus | null

    Papildymo būsena (tik kortelėje, ne sąraše). Dokumento tipas, sąskaitos faktūros laukai ir finansiniai įrašai pridedami fone po indeksavimo ir vėliau gali būti perskaičiuoti; kortelėje jie atsiranda, kai yra paruošti. null reiškia, kad būsenos nėra (kortelė indeksuota be papildymo fone).

  • external_idstring | null

    Kortelės ID integratoriaus sistemoje. Jis unikalus organizacijoje tarp kortelių, kurios nėra iš šaltinių; null reiškia, kad jis nenustatytas. /v1/cards-by-external-id/{external_id} pagal jį skaito ir pakeičia kortelę.

    length ≤ 512

  • metadataMetadata
400Užklausa netinkama: parametro reikšmė arba objekto būsena neleidžia atlikti veiksmo (`detail` – pranešimas).

Atsako antraštės

  • RateLimit-Policy

    Galiojantys limitai IETF juodraščio draft-ietf-httpapi-ratelimit-headers formatu: kableliais atskirti elementai "<name>";q=<quota>;w=<window in seconds>. key – API rakto užklausų dažnis (kvota – pliūpsnis, laiko langas – laikas, per kurį kvota visiškai atsistato; sesijai tai user, be prisijungimo duomenų – ip); minute, day ir month – organizacijos kvotos kalendorinei minutei, dienai ir mėnesiui pagal UTC.

  • RateLimit

    Kiek liko kiekvieno RateLimit-Policy limito: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Griežčiausio RateLimit-Policy įrašo (kuriame liko mažiausiai užklausų) limitas.

  • X-RateLimit-Remaining

    Likusių užklausų skaičius pagal griežčiausią limitą.

  • X-RateLimit-Reset

    Sekundės iki griežčiausio limito atsistatymo.

application/json

Objektas: Error

401Prisijungimo duomenys neišsiųsti (nei sesijos slapukas, nei API raktas) arba raktas nerastas.

Atsako antraštės

  • RateLimit-Policy

    Galiojantys limitai IETF juodraščio draft-ietf-httpapi-ratelimit-headers formatu: kableliais atskirti elementai "<name>";q=<quota>;w=<window in seconds>. key – API rakto užklausų dažnis (kvota – pliūpsnis, laiko langas – laikas, per kurį kvota visiškai atsistato; sesijai tai user, be prisijungimo duomenų – ip); minute, day ir month – organizacijos kvotos kalendorinei minutei, dienai ir mėnesiui pagal UTC.

  • RateLimit

    Kiek liko kiekvieno RateLimit-Policy limito: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Griežčiausio RateLimit-Policy įrašo (kuriame liko mažiausiai užklausų) limitas.

  • X-RateLimit-Remaining

    Likusių užklausų skaičius pagal griežčiausią limitą.

  • X-RateLimit-Reset

    Sekundės iki griežčiausio limito atsistatymo.

application/json

Objektas: Error

403Veiksmas neleidžiamas: vaidmuo nesuteikia reikiamų teisių, nėra prieigos prie rinkinio ar kortelės, užklausa vykdoma režimu „View as“ arba organizacijos veikla sustabdyta ar organizacija ištrinta (`detail` – objektas su `code: org_suspended | org_deleted`).

Atsako antraštės

  • RateLimit-Policy

    Galiojantys limitai IETF juodraščio draft-ietf-httpapi-ratelimit-headers formatu: kableliais atskirti elementai "<name>";q=<quota>;w=<window in seconds>. key – API rakto užklausų dažnis (kvota – pliūpsnis, laiko langas – laikas, per kurį kvota visiškai atsistato; sesijai tai user, be prisijungimo duomenų – ip); minute, day ir month – organizacijos kvotos kalendorinei minutei, dienai ir mėnesiui pagal UTC.

  • RateLimit

    Kiek liko kiekvieno RateLimit-Policy limito: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Griežčiausio RateLimit-Policy įrašo (kuriame liko mažiausiai užklausų) limitas.

  • X-RateLimit-Remaining

    Likusių užklausų skaičius pagal griežčiausią limitą.

  • X-RateLimit-Reset

    Sekundės iki griežčiausio limito atsistatymo.

application/json

Objektas: Error

404Objekto nėra arba jis jums nepasiekiamas. API nepatvirtina, kad ribotos prieigos objektas egzistuoja.

Atsako antraštės

  • RateLimit-Policy

    Galiojantys limitai IETF juodraščio draft-ietf-httpapi-ratelimit-headers formatu: kableliais atskirti elementai "<name>";q=<quota>;w=<window in seconds>. key – API rakto užklausų dažnis (kvota – pliūpsnis, laiko langas – laikas, per kurį kvota visiškai atsistato; sesijai tai user, be prisijungimo duomenų – ip); minute, day ir month – organizacijos kvotos kalendorinei minutei, dienai ir mėnesiui pagal UTC.

  • RateLimit

    Kiek liko kiekvieno RateLimit-Policy limito: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Griežčiausio RateLimit-Policy įrašo (kuriame liko mažiausiai užklausų) limitas.

  • X-RateLimit-Remaining

    Likusių užklausų skaičius pagal griežčiausią limitą.

  • X-RateLimit-Reset

    Sekundės iki griežčiausio limito atsistatymo.

application/json

Objektas: Error

422Validavimo klaida: turinys ar parametrai neatitinka schemos (`detail` – validavimo klaidų sąrašas) arba parametro reikšmė nepatenka į leistiną intervalą (`detail` – pranešimas).

Atsako antraštės

  • RateLimit-Policy

    Galiojantys limitai IETF juodraščio draft-ietf-httpapi-ratelimit-headers formatu: kableliais atskirti elementai "<name>";q=<quota>;w=<window in seconds>. key – API rakto užklausų dažnis (kvota – pliūpsnis, laiko langas – laikas, per kurį kvota visiškai atsistato; sesijai tai user, be prisijungimo duomenų – ip); minute, day ir month – organizacijos kvotos kalendorinei minutei, dienai ir mėnesiui pagal UTC.

  • RateLimit

    Kiek liko kiekvieno RateLimit-Policy limito: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Griežčiausio RateLimit-Policy įrašo (kuriame liko mažiausiai užklausų) limitas.

  • X-RateLimit-Remaining

    Likusių užklausų skaičius pagal griežčiausią limitą.

  • X-RateLimit-Reset

    Sekundės iki griežčiausio limito atsistatymo.

application/json

Objektas: Error

429Per daug užklausų (`api.rate_limited`), išnaudota organizacijos minutės, dienos ar mėnesio kvota (`api.quota_exceeded`; `error.details` pateikia `quota`, `limit` ir `reset_at`), pasiektas organizacijos limitas arba atsakymų paslauga užimta (`answers.engine_busy`). Palaukite tiek, kiek nurodyta antraštėje `Retry-After`.

Atsako antraštės

  • Retry-After

    Kiek sekundžių palaukti prieš kartojant užklausą.

  • RateLimit-Policy

    Galiojantys limitai IETF juodraščio draft-ietf-httpapi-ratelimit-headers formatu: kableliais atskirti elementai "<name>";q=<quota>;w=<window in seconds>. key – API rakto užklausų dažnis (kvota – pliūpsnis, laiko langas – laikas, per kurį kvota visiškai atsistato; sesijai tai user, be prisijungimo duomenų – ip); minute, day ir month – organizacijos kvotos kalendorinei minutei, dienai ir mėnesiui pagal UTC.

  • RateLimit

    Kiek liko kiekvieno RateLimit-Policy limito: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Griežčiausio RateLimit-Policy įrašo (kuriame liko mažiausiai užklausų) limitas.

  • X-RateLimit-Remaining

    Likusių užklausų skaičius pagal griežčiausią limitą.

  • X-RateLimit-Reset

    Sekundės iki griežčiausio limito atsistatymo.

application/json

Objektas: Error

Klaidų kodai

Kodai, kuriuos ši operacija gali grąžinti lauke error.code, be bendrųjų kodų, galimų bet kuriai užklausai.

Užklausų dažnio limitai

Atsakuose yra antraštės RateLimit ir RateLimit-Policy bei ankstesnės X-RateLimit-Limit, X-RateLimit-Remaining ir X-RateLimit-Reset. Atsake 429 yra antraštė Retry-After sekundėmis: palaukite ir pakartokite užklausą.

← cards · API žinynas