Pāriet uz saturu
Sursa Developers

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

Iegūt kartīti pēc ārējā ID

get_card_by_external_id

Atgriež to pašu kartīti ar tām pašām piekļuves pārbaudēm kā GET /v1/cards/{card_id}, adresējot to ar integratora external_id. Ja organizācijā nav kartītes ar šo external_id vai kartīte izsaucējam nav redzama, pieprasījums atgriež 404 cards.not_found.

Autentifikācija

Nosūtiet API atslēgu galvenē Authorization: Authorization: Bearer <atslēga>.

Ceļa parametri

  • external_idstringobligāts

    Kartītes external_id: 1–512 rakstzīmju virkne, unikāla organizācijā.

    length ≥ 1, length ≤ 512

Vaicājuma parametri

  • expand[]array of string

    Saistītie objekti, ko iekļaut atbildē (kopš 1.62.0): ceļš no operācijas saraksta x-expandable. Parametru var atkārtot līdz 10 reizēm. Ceļā ir līdz 2 segmentiem, kas atdalīti ar punktu (collection.default_owner). Sarakstā ceļš sākas ar data. un attiecas uz katru lapas elementu (expand[]=data.owner). Izvērstais objekts tiek ievietots elementa objektā expanded, un ID lauks paliek. Objekts, ko izsaucējs nedrīkst redzēt saskaņā ar tā lasīšanas operācijas pārbaudēm, tiek izvērsts kā null. Nezināms ceļš, vairāk nekā 10 ceļi vai ceļš, kas garāks par 2 segmentiem, atgriež 400 api.expand_invalid.

    items ≤ 10

Galvenes parametri

  • X-View-Asstring

    Tikai API atslēgām ar lomu admin. Izpilda pieprasījumu datu profila <profile>[:viewer|verifier|editor] vārdā, piemēram, employee:viewer. Instalācijas atslēga šo galveni lietot nevar (403).

Sīkdatņu parametri

  • kb_view_asstring

    Režīma „View as“ (skatīt kā) sīkdatne sesijai. POST /auth/view-as to iestata, un DELETE /auth/view-as to notīra.

Atbildes

200Veiksmīga atbilde

Atbildes galvenes

  • RateLimit-Policy

    Spēkā esošie limiti IETF dokumenta projekta draft-ietf-httpapi-ratelimit-headers formātā: ar komatiem atdalīti elementi "<name>";q=<quota>;w=<window in seconds>. key ir API atslēgas pieprasījumu biežums (kvota ir īslaicīgais pīķis, laika logs – laiks, kurā kvota pilnībā atjaunojas; sesijai tas ir user, bez akreditācijas datiem – ip); minute, day un month ir organizācijas kvotas kalendārajai minūtei, dienai un mēnesim pēc UTC.

  • RateLimit

    Cik atlicis no katra RateLimit-Policy limita: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Stingrākā RateLimit-Policy ieraksta limits (tā, kurā atlicis vismazāk pieprasījumu).

  • X-RateLimit-Remaining

    Atlikušo pieprasījumu skaits stingrākā limita ietvaros.

  • X-RateLimit-Reset

    Sekundes līdz stingrākā limita atiestatīšanai.

application/json

Objekts: Card

  • expandedCardExpanded
  • permissionsObjectPermissionList
  • accessstring

    Atļautās vērtības: wholepartial

  • access_contactstring

    Pie kā vērsties pēc piekļuves (tikai tad, ja access=partial).

  • aclobject
    Lauki
    • verifybooleanobligāts
    • writebooleanobligāts
  • categorystringobligāts
  • category_confidencenumber | nullobligāts
  • category_lockedbooleanobligāts
  • category_reviewbooleanobligāts
  • category_sourceCategorySource | nullobligāts
  • collectionstringobligāts
  • collection_idintegerobligāts
  • collection_titlestring
  • commentsarray of CardComment
  • content_jsonContentJSON | null

    Pēdējās publicētās versijas redaktora saturs. Lauka var nebūt; tādā gadījumā redaktora saturu iegūstiet no melnraksta (POST /v1/drafts ar card_id).

  • editing_lockEditingLock | null

    Aktīvā rediģēšanas bloķēšana. Lauka var nebūt; tādā gadījumā redaktors uzzina, kam pieder bloķēšana, no 409 cards.locked atbildē uz POST /v1/cards/{card_id}/lock.

  • created_atstring (date-time)obligāts
  • days_since_verifiedintegerobligāts
  • errorstring | nullobligāts
  • eventsarray of CardEvent
  • feedback_negintegerobligāts
  • feedback_posintegerobligāts
  • foldersarray of CardFolderRef

    Tikai kartīšu sarakstā: mapes, kurās ir kartīte (lietotājam redzamās), ar to ceļiem no kolekcijas saknes. Tukšs saraksts nozīmē, ka kartīte nav nevienā mapē.

  • has_tablesboolean

    Tikai kartīšu sarakstā.

  • hidden_partsboolean
  • idstringobligāts
  • jobJob | null
  • kindCardKindobligāts
  • org_idintegerobligāts
  • owner_activeboolean | null
  • owner_idinteger | nullobligāts
  • owner_namestring | nullobligāts
  • pagesinteger | nullobligāts
  • parserstring | nullobligāts

    Dokumenta nolasīšanas veids kā neitrāls kods: document (pilna struktūra: lappuses, virsraksti, tabulas, skenētas lappuses), pdf (PDF teksta slānis), docx, xlsx, csv, markdown, html, text. Saraksts var paplašināties.

  • partsarray of CardPartobligāts
  • sensitivebooleanobligāts
  • sha256string | nullobligāts
  • sizeintegerobligāts
  • snoozed_atstring (date-time) | null
  • snoozed_byinteger | null
  • snoozed_untilstring | null
  • source_changedbooleanobligāts
  • source_pathstring | nullobligāts
  • source_urlstring | nullobligāts
  • statusstringobligāts

    Atļautās vērtības: processingreadyerrorarchived

  • tablesarray of CardTable
  • tagsarray of stringobligāts
  • titlestringobligāts
  • trustnumberobligāts
  • trust_if_verifiednumber
  • trust_partsTrustPartsobligāts
  • updated_atstring (date-time)obligāts
  • verificationVerificationobligāts
  • verified_atstring (date-time) | nullobligāts
  • verified_byinteger | nullobligāts
  • verified_by_namestring | null
  • verifier_idsarray of integerobligāts
  • verifiersarray of object
    Lauki
    • activebooleanobligāts
    • idintegerobligāts
    • namestringobligāts
  • verify_interval_daysintegerobligāts
  • versionintegerobligāts
  • versionsarray of CardVersion
  • source_archiveArchiveSource
  • created_byinteger | null
  • manual_optionsobject

    Manuālie nolasīšanas iestatījumi (priekšskatījums).

  • doc_kindDocKind | null

    Dokumenta tips. null, ja tips nav noteikts (piemēram, kartītēm, kas indeksētas pirms dokumentu tipu ieviešanas).

  • doc_kind_confidencenumber | null

    Pārliecības līmenis par dokumenta tipu, no 0 līdz 1.

  • doc_kind_sourcestring | null

    Kas noteica tipu: noteikumi (rules), lietotājs (manual) vai automātiska klasifikācija. Saraksts var paplašināties: nezināmu vērtību uzskatiet par automātisku klasifikāciju.

    Atļautās vērtības: rulesmanualnull

  • invoiceDocInvoiceExtraction | null

    Rēķina, kredītrēķina vai čeka lauki (tikai šiem tipiem un tikai kartītē, ne sarakstā). null, ja jums nav piekļuves visam dokumentam, jo lauki tiek iegūti no visa dokumenta.

  • warningsarray of ReviewWarning

    Dokumenta nolasīšanas brīdinājumi (ReviewWarning; tikai kartītē, ne sarakstā).

  • enrichmentCardEnrichmentStatus | null

    Bagātināšanas statuss (tikai kartītē, ne sarakstā). Dokumenta tips, rēķina lauki un finanšu ieraksti tiek pievienoti fonā pēc indeksēšanas un vēlāk var tikt pārrēķināti; tie parādās kartītē, kad ir gatavi. null nozīmē, ka statuss nav pieejams (kartīte indeksēta bez bagātināšanas fonā).

  • external_idstring | null

    Kartītes ID integratora sistēmā. Tas ir unikāls organizācijā starp kartītēm, kas nenāk no avotiem; null nozīmē, ka tas nav iestatīts. /v1/cards-by-external-id/{external_id} pēc tā nolasa un aizstāj kartīti.

    length ≤ 512

  • metadataMetadata
400Pieprasījums nav derīgs: parametra vērtība vai objekta stāvoklis neļauj veikt darbību (`detail` ir ziņojums).

Atbildes galvenes

  • RateLimit-Policy

    Spēkā esošie limiti IETF dokumenta projekta draft-ietf-httpapi-ratelimit-headers formātā: ar komatiem atdalīti elementi "<name>";q=<quota>;w=<window in seconds>. key ir API atslēgas pieprasījumu biežums (kvota ir īslaicīgais pīķis, laika logs – laiks, kurā kvota pilnībā atjaunojas; sesijai tas ir user, bez akreditācijas datiem – ip); minute, day un month ir organizācijas kvotas kalendārajai minūtei, dienai un mēnesim pēc UTC.

  • RateLimit

    Cik atlicis no katra RateLimit-Policy limita: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Stingrākā RateLimit-Policy ieraksta limits (tā, kurā atlicis vismazāk pieprasījumu).

  • X-RateLimit-Remaining

    Atlikušo pieprasījumu skaits stingrākā limita ietvaros.

  • X-RateLimit-Reset

    Sekundes līdz stingrākā limita atiestatīšanai.

application/json

Objekts: Error

401Nav nosūtīti akreditācijas dati (ne sesijas sīkdatne, ne API atslēga), vai atslēga nav atrasta.

Atbildes galvenes

  • RateLimit-Policy

    Spēkā esošie limiti IETF dokumenta projekta draft-ietf-httpapi-ratelimit-headers formātā: ar komatiem atdalīti elementi "<name>";q=<quota>;w=<window in seconds>. key ir API atslēgas pieprasījumu biežums (kvota ir īslaicīgais pīķis, laika logs – laiks, kurā kvota pilnībā atjaunojas; sesijai tas ir user, bez akreditācijas datiem – ip); minute, day un month ir organizācijas kvotas kalendārajai minūtei, dienai un mēnesim pēc UTC.

  • RateLimit

    Cik atlicis no katra RateLimit-Policy limita: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Stingrākā RateLimit-Policy ieraksta limits (tā, kurā atlicis vismazāk pieprasījumu).

  • X-RateLimit-Remaining

    Atlikušo pieprasījumu skaits stingrākā limita ietvaros.

  • X-RateLimit-Reset

    Sekundes līdz stingrākā limita atiestatīšanai.

application/json

Objekts: Error

403Darbība nav atļauta: loma nav pietiekama, nav piekļuves kolekcijai vai kartītei, pieprasījums izpildās režīmā „View as“ vai organizācija ir apturēta vai dzēsta (`detail` ir objekts ar `code: org_suspended | org_deleted`).

Atbildes galvenes

  • RateLimit-Policy

    Spēkā esošie limiti IETF dokumenta projekta draft-ietf-httpapi-ratelimit-headers formātā: ar komatiem atdalīti elementi "<name>";q=<quota>;w=<window in seconds>. key ir API atslēgas pieprasījumu biežums (kvota ir īslaicīgais pīķis, laika logs – laiks, kurā kvota pilnībā atjaunojas; sesijai tas ir user, bez akreditācijas datiem – ip); minute, day un month ir organizācijas kvotas kalendārajai minūtei, dienai un mēnesim pēc UTC.

  • RateLimit

    Cik atlicis no katra RateLimit-Policy limita: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Stingrākā RateLimit-Policy ieraksta limits (tā, kurā atlicis vismazāk pieprasījumu).

  • X-RateLimit-Remaining

    Atlikušo pieprasījumu skaits stingrākā limita ietvaros.

  • X-RateLimit-Reset

    Sekundes līdz stingrākā limita atiestatīšanai.

application/json

Objekts: Error

404Objekts neeksistē vai jums nav pieejams. API neapstiprina, ka ierobežotas piekļuves objekts eksistē.

Atbildes galvenes

  • RateLimit-Policy

    Spēkā esošie limiti IETF dokumenta projekta draft-ietf-httpapi-ratelimit-headers formātā: ar komatiem atdalīti elementi "<name>";q=<quota>;w=<window in seconds>. key ir API atslēgas pieprasījumu biežums (kvota ir īslaicīgais pīķis, laika logs – laiks, kurā kvota pilnībā atjaunojas; sesijai tas ir user, bez akreditācijas datiem – ip); minute, day un month ir organizācijas kvotas kalendārajai minūtei, dienai un mēnesim pēc UTC.

  • RateLimit

    Cik atlicis no katra RateLimit-Policy limita: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Stingrākā RateLimit-Policy ieraksta limits (tā, kurā atlicis vismazāk pieprasījumu).

  • X-RateLimit-Remaining

    Atlikušo pieprasījumu skaits stingrākā limita ietvaros.

  • X-RateLimit-Reset

    Sekundes līdz stingrākā limita atiestatīšanai.

application/json

Objekts: Error

422Validācijas kļūda: saturs vai parametri neatbilst shēmai (`detail` ir validācijas kļūdu saraksts), vai parametra vērtība ir ārpus pieļaujamā diapazona (`detail` ir ziņojums).

Atbildes galvenes

  • RateLimit-Policy

    Spēkā esošie limiti IETF dokumenta projekta draft-ietf-httpapi-ratelimit-headers formātā: ar komatiem atdalīti elementi "<name>";q=<quota>;w=<window in seconds>. key ir API atslēgas pieprasījumu biežums (kvota ir īslaicīgais pīķis, laika logs – laiks, kurā kvota pilnībā atjaunojas; sesijai tas ir user, bez akreditācijas datiem – ip); minute, day un month ir organizācijas kvotas kalendārajai minūtei, dienai un mēnesim pēc UTC.

  • RateLimit

    Cik atlicis no katra RateLimit-Policy limita: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Stingrākā RateLimit-Policy ieraksta limits (tā, kurā atlicis vismazāk pieprasījumu).

  • X-RateLimit-Remaining

    Atlikušo pieprasījumu skaits stingrākā limita ietvaros.

  • X-RateLimit-Reset

    Sekundes līdz stingrākā limita atiestatīšanai.

application/json

Objekts: Error

429Pārāk daudz pieprasījumu (`api.rate_limited`), organizācijas minūtes, dienas vai mēneša kvota ir izlietota (`api.quota_exceeded`; `error.details` satur `quota`, `limit` un `reset_at`), sasniegts organizācijas limits vai atbilžu pakalpojums ir aizņemts (`answers.engine_busy`). Pagaidiet galvenē `Retry-After` norādīto laiku.

Atbildes galvenes

  • Retry-After

    Sekunžu skaits, kas jāpagaida, pirms atkārtojat pieprasījumu.

  • RateLimit-Policy

    Spēkā esošie limiti IETF dokumenta projekta draft-ietf-httpapi-ratelimit-headers formātā: ar komatiem atdalīti elementi "<name>";q=<quota>;w=<window in seconds>. key ir API atslēgas pieprasījumu biežums (kvota ir īslaicīgais pīķis, laika logs – laiks, kurā kvota pilnībā atjaunojas; sesijai tas ir user, bez akreditācijas datiem – ip); minute, day un month ir organizācijas kvotas kalendārajai minūtei, dienai un mēnesim pēc UTC.

  • RateLimit

    Cik atlicis no katra RateLimit-Policy limita: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Stingrākā RateLimit-Policy ieraksta limits (tā, kurā atlicis vismazāk pieprasījumu).

  • X-RateLimit-Remaining

    Atlikušo pieprasījumu skaits stingrākā limita ietvaros.

  • X-RateLimit-Reset

    Sekundes līdz stingrākā limita atiestatīšanai.

application/json

Objekts: Error

Kļūdu kodi

Kodi, ko šī operācija var atgriezt laukā error.code papildus vispārīgajiem kodiem, kas iespējami jebkuram pieprasījumam.

Pieprasījumu biežuma limiti

Atbildēs ir galvenes RateLimit un RateLimit-Policy, kā arī agrākās X-RateLimit-Limit, X-RateLimit-Remaining un X-RateLimit-Reset. Atbildē 429 ir galvene Retry-After sekundēs: nogaidiet un atkārtojiet pieprasījumu.

← cards · API rokasgrāmata