Siirry sisältöön
Sursa Developers

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

Hae kortti ulkoisella tunnuksella

get_card_by_external_id

Palauttaa saman kortin samoin käyttöoikeustarkistuksin kuin GET /v1/cards/{card_id}, mutta kortti osoitetaan integroijan external_id-tunnuksella. Jos organisaatiolla ei ole korttia, jolla on tämä external_id, tai kortti ei näy kutsujalle, pyyntö palauttaa 404 cards.not_found.

Todennus

Lähetä API-avain Authorization-otsakkeessa: Authorization: Bearer <avain>.

Polkuparametrit

  • external_idstringpakollinen

    Kortin external_id: 1–512 merkin merkkijono, joka on yksilöllinen organisaatiossa.

    length ≥ 1, length ≤ 512

Kyselyparametrit

  • expand[]array of string

    Vastaukseen sisällytettävät liittyvät objektit (versiosta 1.62.0 alkaen): polku toiminnon x-expandable-luettelosta. Toista parametri enintään 10 kertaa. Polussa on enintään 2 pisteellä erotettua osaa (collection.default_owner). Listassa polku alkaa merkkijonolla data. ja koskee sivun jokaista kohdetta (expand[]=data.owner). Laajennettu objekti menee kohteen expanded-objektiin, ja tunnuskenttä säilyy. Objekti, jota kutsuja ei saa nähdä sen oman lukutoiminnon tarkistusten mukaan, laajennetaan arvoksi null. Tuntematon polku, yli 10 polkua tai yli 2 osan syvyinen polku palauttaa 400 api.expand_invalid.

    items ≤ 10

Otsakeparametrit

  • X-View-Asstring

    Vain API-avaimille, joilla on admin-rooli. Suorittaa pyynnön dataprofiilin <profile>[:viewer|verifier|editor] puolesta, esimerkiksi employee:viewer. Asennusavain ei voi käyttää tätä otsaketta (403).

Evästeparametrit

  • kb_view_asstring

    Istunnon ”View as” -tilan eväste. POST /auth/view-as asettaa sen ja DELETE /auth/view-as poistaa sen.

Vastaukset

200Onnistunut vastaus

Vastausotsakkeet

  • RateLimit-Policy

    Voimassa olevat rajat IETF-luonnoksen draft-ietf-httpapi-ratelimit-headers muodossa: pilkuin erotetut kohteet "<name>";q=<quota>;w=<window in seconds>. key on API-avaimen pyyntönopeus (kiintiö on purske, aikaikkuna on aika, jossa se täyttyy kokonaan; istunnolle se on user, ilman tunnistetietoja ip); minute, day ja month ovat organisaation kiintiöt UTC-ajan kalenteriminuutille, -päivälle ja -kuukaudelle.

  • RateLimit

    Mitä kustakin RateLimit-Policy-otsakkeen rajasta on jäljellä: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    RateLimit-Policy-otsakkeen tiukimman kohteen raja (sen, jossa pyyntöjä on jäljellä vähiten).

  • X-RateLimit-Remaining

    Tiukimman rajan puitteissa jäljellä olevat pyynnöt.

  • X-RateLimit-Reset

    Sekunteja siihen, kun tiukin raja nollautuu.

application/json

Objekti: Card

  • expandedCardExpanded
  • permissionsObjectPermissionList
  • accessstring

    Sallitut arvot: wholepartial

  • access_contactstring

    Keneen ottaa yhteyttä käyttöoikeuden saamiseksi (vain kun access=partial).

  • aclobject
    Kentät
    • verifybooleanpakollinen
    • writebooleanpakollinen
  • categorystringpakollinen
  • category_confidencenumber | nullpakollinen
  • category_lockedbooleanpakollinen
  • category_reviewbooleanpakollinen
  • category_sourceCategorySource | nullpakollinen
  • collectionstringpakollinen
  • collection_idintegerpakollinen
  • collection_titlestring
  • commentsarray of CardComment
  • content_jsonContentJSON | null

    Viimeisimmän julkaistun version sisältö editorin muodossa. Kenttä voi puuttua; silloin hae editorin sisältö luonnoksesta (POST /v1/drafts ja card_id).

  • editing_lockEditingLock | null

    Voimassa oleva muokkauslukitus. Kenttä voi puuttua; silloin editori saa tietää lukituksen haltijan 409 cards.locked-vastauksesta POST /v1/cards/{card_id}/lock-toiminnossa.

  • created_atstring (date-time)pakollinen
  • days_since_verifiedintegerpakollinen
  • errorstring | nullpakollinen
  • eventsarray of CardEvent
  • feedback_negintegerpakollinen
  • feedback_posintegerpakollinen
  • foldersarray of CardFolderRef

    Vain korttiluettelossa: kansiot, joissa kortti on (käyttäjälle näkyvät), polkuineen kokoelman juuresta. Tyhjä luettelo tarkoittaa, että kortti ei ole missään kansiossa.

  • has_tablesboolean

    Vain korttiluettelossa.

  • hidden_partsboolean
  • idstringpakollinen
  • jobJob | null
  • kindCardKindpakollinen
  • org_idintegerpakollinen
  • owner_activeboolean | null
  • owner_idinteger | nullpakollinen
  • owner_namestring | nullpakollinen
  • pagesinteger | nullpakollinen
  • parserstring | nullpakollinen

    Asiakirjan jäsennin neutraalina koodina: document (koko rakenne: sivut, otsikot, taulukot, skannatut sivut), pdf (PDF:n tekstikerros), docx, xlsx, csv, markdown, html, text. Luettelo voi laajentua.

  • partsarray of CardPartpakollinen
  • sensitivebooleanpakollinen
  • sha256string | nullpakollinen
  • sizeintegerpakollinen
  • snoozed_atstring (date-time) | null
  • snoozed_byinteger | null
  • snoozed_untilstring | null
  • source_changedbooleanpakollinen
  • source_pathstring | nullpakollinen
  • source_urlstring | nullpakollinen
  • statusstringpakollinen

    Sallitut arvot: processingreadyerrorarchived

  • tablesarray of CardTable
  • tagsarray of stringpakollinen
  • titlestringpakollinen
  • trustnumberpakollinen
  • trust_if_verifiednumber
  • trust_partsTrustPartspakollinen
  • updated_atstring (date-time)pakollinen
  • verificationVerificationpakollinen
  • verified_atstring (date-time) | nullpakollinen
  • verified_byinteger | nullpakollinen
  • verified_by_namestring | null
  • verifier_idsarray of integerpakollinen
  • verifiersarray of object
    Kentät
    • activebooleanpakollinen
    • idintegerpakollinen
    • namestringpakollinen
  • verify_interval_daysintegerpakollinen
  • versionintegerpakollinen
  • versionsarray of CardVersion
  • source_archiveArchiveSource
  • created_byinteger | null
  • manual_optionsobject

    Manuaaliset jäsennysasetukset (esikatselu).

  • doc_kindDocKind | null

    Asiakirjan tyyppi. null, jos tyyppiä ei ole määritetty (esimerkiksi korteilla, jotka indeksoitiin ennen asiakirjatyyppien käyttöönottoa).

  • doc_kind_confidencenumber | null

    Asiakirjan tyypin varmuustaso välillä 0–1.

  • doc_kind_sourcestring | null

    Mikä määritti tyypin: säännöt (rules), käyttäjä (manual) tai automaattinen luokittelu. Luettelo voi laajentua: käsittele tuntematon arvo automaattisena luokitteluna.

    Sallitut arvot: rulesmanualnull

  • invoiceDocInvoiceExtraction | null

    Laskun, hyvityslaskun tai kuitin kentät (vain näillä tyypeillä ja vain kortissa, ei luettelossa). null, jos sinulla ei ole pääsyä koko asiakirjaan, koska kentät poimitaan koko asiakirjasta.

  • warningsarray of ReviewWarning

    Asiakirjan jäsennyksen varoitukset (ReviewWarning; vain kortissa, ei luettelossa).

  • enrichmentCardEnrichmentStatus | null

    Rikastuksen tila (vain kortissa, ei luettelossa). Asiakirjan tyyppi, laskun kentät ja taloustietueet lisätään taustalla indeksoinnin jälkeen, ja ne voidaan laskea myöhemmin uudelleen; ne näkyvät kortissa, kun ne ovat valmiita. null tarkoittaa, ettei tilaa ole saatavilla (kortti indeksoitiin ilman taustarikastusta).

  • external_idstring | null

    Kortin tunnus integroijan järjestelmässä. Se on yksilöllinen organisaatiossa niiden korttien kesken, jotka eivät tule lähteistä; null tarkoittaa, ettei sitä ole asetettu. /v1/cards-by-external-id/{external_id} lukee ja korvaa kortin sen mukaan.

    length ≤ 512

  • metadataMetadata
400Pyyntö on virheellinen: parametrin arvo tai objektin tila ei salli toimenpidettä (`detail` on viesti).

Vastausotsakkeet

  • RateLimit-Policy

    Voimassa olevat rajat IETF-luonnoksen draft-ietf-httpapi-ratelimit-headers muodossa: pilkuin erotetut kohteet "<name>";q=<quota>;w=<window in seconds>. key on API-avaimen pyyntönopeus (kiintiö on purske, aikaikkuna on aika, jossa se täyttyy kokonaan; istunnolle se on user, ilman tunnistetietoja ip); minute, day ja month ovat organisaation kiintiöt UTC-ajan kalenteriminuutille, -päivälle ja -kuukaudelle.

  • RateLimit

    Mitä kustakin RateLimit-Policy-otsakkeen rajasta on jäljellä: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    RateLimit-Policy-otsakkeen tiukimman kohteen raja (sen, jossa pyyntöjä on jäljellä vähiten).

  • X-RateLimit-Remaining

    Tiukimman rajan puitteissa jäljellä olevat pyynnöt.

  • X-RateLimit-Reset

    Sekunteja siihen, kun tiukin raja nollautuu.

application/json

Objekti: Error

401Tunnistetietoja ei lähetetty (ei istuntoevästettä eikä API-avainta), tai avainta ei löytynyt.

Vastausotsakkeet

  • RateLimit-Policy

    Voimassa olevat rajat IETF-luonnoksen draft-ietf-httpapi-ratelimit-headers muodossa: pilkuin erotetut kohteet "<name>";q=<quota>;w=<window in seconds>. key on API-avaimen pyyntönopeus (kiintiö on purske, aikaikkuna on aika, jossa se täyttyy kokonaan; istunnolle se on user, ilman tunnistetietoja ip); minute, day ja month ovat organisaation kiintiöt UTC-ajan kalenteriminuutille, -päivälle ja -kuukaudelle.

  • RateLimit

    Mitä kustakin RateLimit-Policy-otsakkeen rajasta on jäljellä: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    RateLimit-Policy-otsakkeen tiukimman kohteen raja (sen, jossa pyyntöjä on jäljellä vähiten).

  • X-RateLimit-Remaining

    Tiukimman rajan puitteissa jäljellä olevat pyynnöt.

  • X-RateLimit-Reset

    Sekunteja siihen, kun tiukin raja nollautuu.

application/json

Objekti: Error

403Toimenpide ei ole sallittu: rooli ei riitä, kokoelmaan tai korttiin ei ole käyttöoikeutta, pyyntö suoritetaan ”View as” -tilassa, tai organisaation toiminta on keskeytetty tai organisaatio on poistettu (`detail` on objekti, jossa on `code: org_suspended | org_deleted`).

Vastausotsakkeet

  • RateLimit-Policy

    Voimassa olevat rajat IETF-luonnoksen draft-ietf-httpapi-ratelimit-headers muodossa: pilkuin erotetut kohteet "<name>";q=<quota>;w=<window in seconds>. key on API-avaimen pyyntönopeus (kiintiö on purske, aikaikkuna on aika, jossa se täyttyy kokonaan; istunnolle se on user, ilman tunnistetietoja ip); minute, day ja month ovat organisaation kiintiöt UTC-ajan kalenteriminuutille, -päivälle ja -kuukaudelle.

  • RateLimit

    Mitä kustakin RateLimit-Policy-otsakkeen rajasta on jäljellä: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    RateLimit-Policy-otsakkeen tiukimman kohteen raja (sen, jossa pyyntöjä on jäljellä vähiten).

  • X-RateLimit-Remaining

    Tiukimman rajan puitteissa jäljellä olevat pyynnöt.

  • X-RateLimit-Reset

    Sekunteja siihen, kun tiukin raja nollautuu.

application/json

Objekti: Error

404Objektia ei ole tai se ei ole saatavillasi. API ei paljasta, onko rajoitettu objekti olemassa.

Vastausotsakkeet

  • RateLimit-Policy

    Voimassa olevat rajat IETF-luonnoksen draft-ietf-httpapi-ratelimit-headers muodossa: pilkuin erotetut kohteet "<name>";q=<quota>;w=<window in seconds>. key on API-avaimen pyyntönopeus (kiintiö on purske, aikaikkuna on aika, jossa se täyttyy kokonaan; istunnolle se on user, ilman tunnistetietoja ip); minute, day ja month ovat organisaation kiintiöt UTC-ajan kalenteriminuutille, -päivälle ja -kuukaudelle.

  • RateLimit

    Mitä kustakin RateLimit-Policy-otsakkeen rajasta on jäljellä: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    RateLimit-Policy-otsakkeen tiukimman kohteen raja (sen, jossa pyyntöjä on jäljellä vähiten).

  • X-RateLimit-Remaining

    Tiukimman rajan puitteissa jäljellä olevat pyynnöt.

  • X-RateLimit-Reset

    Sekunteja siihen, kun tiukin raja nollautuu.

application/json

Objekti: Error

422Validointivirhe: runko tai parametrit eivät vastaa skeemaa (`detail` on validointivirheiden lista), tai parametrin arvo on sallitun alueen ulkopuolella (`detail` on viesti).

Vastausotsakkeet

  • RateLimit-Policy

    Voimassa olevat rajat IETF-luonnoksen draft-ietf-httpapi-ratelimit-headers muodossa: pilkuin erotetut kohteet "<name>";q=<quota>;w=<window in seconds>. key on API-avaimen pyyntönopeus (kiintiö on purske, aikaikkuna on aika, jossa se täyttyy kokonaan; istunnolle se on user, ilman tunnistetietoja ip); minute, day ja month ovat organisaation kiintiöt UTC-ajan kalenteriminuutille, -päivälle ja -kuukaudelle.

  • RateLimit

    Mitä kustakin RateLimit-Policy-otsakkeen rajasta on jäljellä: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    RateLimit-Policy-otsakkeen tiukimman kohteen raja (sen, jossa pyyntöjä on jäljellä vähiten).

  • X-RateLimit-Remaining

    Tiukimman rajan puitteissa jäljellä olevat pyynnöt.

  • X-RateLimit-Reset

    Sekunteja siihen, kun tiukin raja nollautuu.

application/json

Objekti: Error

429Liian monta pyyntöä (`api.rate_limited`), organisaation minuutti-, päivä- tai kuukausikiintiö on käytetty (`api.quota_exceeded`; `error.details` sisältää kentät `quota`, `limit` ja `reset_at`), organisaation raja on saavutettu tai vastauspalvelu on kuormitettu (`answers.engine_busy`). Odota `Retry-After`-otsakkeen ilmoittama aika.

Vastausotsakkeet

  • Retry-After

    Kuinka monta sekuntia odotetaan ennen pyynnön uusintayritystä.

  • RateLimit-Policy

    Voimassa olevat rajat IETF-luonnoksen draft-ietf-httpapi-ratelimit-headers muodossa: pilkuin erotetut kohteet "<name>";q=<quota>;w=<window in seconds>. key on API-avaimen pyyntönopeus (kiintiö on purske, aikaikkuna on aika, jossa se täyttyy kokonaan; istunnolle se on user, ilman tunnistetietoja ip); minute, day ja month ovat organisaation kiintiöt UTC-ajan kalenteriminuutille, -päivälle ja -kuukaudelle.

  • RateLimit

    Mitä kustakin RateLimit-Policy-otsakkeen rajasta on jäljellä: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    RateLimit-Policy-otsakkeen tiukimman kohteen raja (sen, jossa pyyntöjä on jäljellä vähiten).

  • X-RateLimit-Remaining

    Tiukimman rajan puitteissa jäljellä olevat pyynnöt.

  • X-RateLimit-Reset

    Sekunteja siihen, kun tiukin raja nollautuu.

application/json

Objekti: Error

Virhekoodit

Koodit, jotka tämä päätepiste voi palauttaa error.code-kentässä kaikkien pyyntöjen yleisten koodien lisäksi.

Nopeusrajoitukset

Vastauksissa ovat RateLimit- ja RateLimit-Policy-otsakkeet sekä aiemmat X-RateLimit-Limit, X-RateLimit-Remaining ja X-RateLimit-Reset. 429-vastauksessa on Retry-After sekunteina: odota ja yritä uudelleen.

← cards · API-viite