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

Kaardi pärimine välise ID järgi

get_card_by_external_id

Tagastab sama kaardi samade juurdepääsukontrollidega nagu GET /v1/cards/{card_id}, kuid integraatori external_id järgi. Kui organisatsioonis pole selle external_id väärtusega kaarti või kaart ei ole päringu tegijale nähtav, tagastab päring 404 cards.not_found.

Autentimine

Saatke API-võti päises Authorization: Authorization: Bearer <võti>.

Teeparameetrid

external_idstringkohustuslik
Kaardi external_id: 1–512 märgi pikkune string, organisatsioonis unikaalne.
length ≥ 1, length ≤ 512

Päringuparameetrid

expand[]array of string
Vastusesse lisatavad seotud objektid (alates versioonist 1.62.0): tee toimingu loendist x-expandable. Korrake parameetrit kuni 10 korda. Tee koosneb kuni 2 punktiga eraldatud lõigust (collection.default_owner). Loendis algab tee eesliitega data. ja kehtib lehe iga elemendi kohta (expand[]=data.owner). Laiendatud objekt läheb elemendi objekti expanded ja ID-väli jääb alles. Objekt, mida päringu tegija selle enda lugemistoimingu kontrollide järgi näha ei tohi, laiendatakse väärtusena null. Kui tee on tundmatu, teid on üle 10 või tee on sügavam kui 2 lõiku, tagastatakse 400 api.expand_invalid.
items ≤ 10

Päiseparameetrid

X-View-Asstring
Ainult rolliga admin API-võtmetele. Teeb päringu andmeprofiili <profile>[:viewer|verifier|editor] nimel, näiteks employee:viewer. Paigaldusvõti seda päist kasutada ei saa (403).

Küpsiseparameetrid

kb_view_asstring
Seansi režiimi „View as“ küpsis. POST /auth/view-as määrab selle ja DELETE /auth/view-as kustutab selle.

Vastused

200Edukas vastus

Vastuse päised

RateLimit-Policy
Kehtivad piirangud IETF-i mustandi draft-ietf-httpapi-ratelimit-headers vormingus: komadega eraldatud elemendid "<name>";q=<quota>;w=<window in seconds>. key on API-võtme päringusagedus (kvoot on tipuvaru, ajaaken on aeg selle täielikuks taastumiseks; seansi puhul on see user, ilma autentimisandmeteta ip); minute, day ja month on organisatsiooni kvoodid kalendriminutile, -päevale ja -kuule UTC järgi.
RateLimit
Iga päises RateLimit-Policy oleva piirangu jääk: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Päises RateLimit-Policy oleva rangeima kirje limiit (selle, millel on kõige vähem päringuid järel).
X-RateLimit-Remaining
Rangeima piirangu järgi järelejäänud päringud.
X-RateLimit-Reset
Sekundid rangeima piirangu lähtestumiseni.

application/json

Objekt: Card

expandedCardExpanded
permissionsObjectPermissionList
accessstring
Lubatud väärtused: wholepartial
access_contactstring
Kelle poole juurdepääsu saamiseks pöörduda (ainult kui access=partial).
aclobject
Väljad
- verifybooleankohustuslik
- writebooleankohustuslik
categorystringkohustuslik
category_confidencenumber | nullkohustuslik
category_lockedbooleankohustuslik
category_reviewbooleankohustuslik
category_sourceCategorySource | nullkohustuslik
collectionstringkohustuslik
collection_idintegerkohustuslik
collection_titlestring
commentsarray of CardComment
content_jsonContentJSON | null
Viimase avaldatud versiooni redaktori sisu. Väli võib puududa; sel juhul saate redaktori sisu mustandist (POST /v1/drafts koos väljaga card_id).
editing_lockEditingLock | null
Aktiivne redigeerimislukk. Väli võib puududa; sel juhul saab redaktor teada, kellel lukk on, vastusest 409 cards.locked toimingule POST /v1/cards/{card_id}/lock.
created_atstring (date-time)kohustuslik
days_since_verifiedintegerkohustuslik
errorstring | nullkohustuslik
eventsarray of CardEvent
feedback_negintegerkohustuslik
feedback_posintegerkohustuslik
foldersarray of CardFolderRef
Ainult kaartide loendis: kaustad, mis kaarti sisaldavad (kasutajale nähtavad), koos nende teedega kogu juurest. Tühi loend tähendab, et kaart ei ole üheski kaustas.
has_tablesboolean
Ainult kaartide loendis.
hidden_partsboolean
idstringkohustuslik
jobJob | null
kindCardKindkohustuslik
org_idintegerkohustuslik
owner_activeboolean | null
owner_idinteger | nullkohustuslik
owner_namestring | nullkohustuslik
pagesinteger | nullkohustuslik
parserstring | nullkohustuslik
Dokumendi parser neutraalse koodina: document (täielik struktuur: lehed, pealkirjad, tabelid, skannitud lehed), pdf (PDF-i tekstikiht), docx, xlsx, csv, markdown, html, text. Loend võib täieneda.
partsarray of CardPartkohustuslik
sensitivebooleankohustuslik
sha256string | nullkohustuslik
sizeintegerkohustuslik
snoozed_atstring (date-time) | null
snoozed_byinteger | null
snoozed_untilstring | null
source_changedbooleankohustuslik
source_pathstring | nullkohustuslik
source_urlstring | nullkohustuslik
statusstringkohustuslik
Lubatud väärtused: processingreadyerrorarchived
tablesarray of CardTable
tagsarray of stringkohustuslik
titlestringkohustuslik
trustnumberkohustuslik
trust_if_verifiednumber
trust_partsTrustPartskohustuslik
updated_atstring (date-time)kohustuslik
verificationVerificationkohustuslik
verified_atstring (date-time) | nullkohustuslik
verified_byinteger | nullkohustuslik
verified_by_namestring | null
verifier_idsarray of integerkohustuslik
verifiersarray of object
Väljad
- activebooleankohustuslik
- idintegerkohustuslik
- namestringkohustuslik
verify_interval_daysintegerkohustuslik
versionintegerkohustuslik
versionsarray of CardVersion
source_archiveArchiveSource
created_byinteger | null
manual_optionsobject
Parsimise käsitsi seaded (eelvaade).
doc_kindDocKind | null
Dokumendi tüüp. null, kui tüüp ei ole määratud (näiteks kaartidel, mis indekseeriti enne dokumenditüüpide kasutuselevõttu).
doc_kind_confidencenumber | null
Dokumendi tüübi kindlusaste vahemikus 0 kuni 1.
doc_kind_sourcestring | null
Mis tüübi määras: reeglid (rules), kasutaja (manual) või automaatne liigitamine. Loend võib täieneda: käsitlege tundmatut väärtust automaatse liigitamisena.
Lubatud väärtused: rulesmanualnull
invoiceDocInvoiceExtraction | null
Arve, kreeditarve või kviitungi väljad (ainult nende tüüpide puhul ja ainult kaardil, mitte loendis). null, kui teil puudub juurdepääs kogu dokumendile, sest väljad eraldatakse kogu dokumendist.
warningsarray of ReviewWarning
Dokumendi parsimise hoiatused (ReviewWarning; ainult kaardil, mitte loendis).
enrichmentCardEnrichmentStatus | null
Rikastamise olek (ainult kaardil, mitte loendis). Dokumendi tüüp, arve väljad ja finantskirjed lisatakse taustal pärast indekseerimist ning neid võidakse hiljem uuesti arvutada; need ilmuvad kaardile, kui on valmis. null tähendab, et olek ei ole saadaval (kaart indekseeriti ilma taustal rikastamiseta).
external_idstring | null
Kaardi ID integraatori süsteemis. See on organisatsioonis unikaalne kaartide seas, mis ei pärine allikatest; null tähendab, et see ei ole määratud. /v1/cards-by-external-id/{external_id} loeb ja asendab kaardi selle järgi.
length ≤ 512
metadataMetadata

400Päring on vigane: parameetri väärtus või objekti olek ei võimalda toimingut (`detail` on teade).

Vastuse päised

RateLimit-Policy
Kehtivad piirangud IETF-i mustandi draft-ietf-httpapi-ratelimit-headers vormingus: komadega eraldatud elemendid "<name>";q=<quota>;w=<window in seconds>. key on API-võtme päringusagedus (kvoot on tipuvaru, ajaaken on aeg selle täielikuks taastumiseks; seansi puhul on see user, ilma autentimisandmeteta ip); minute, day ja month on organisatsiooni kvoodid kalendriminutile, -päevale ja -kuule UTC järgi.
RateLimit
Iga päises RateLimit-Policy oleva piirangu jääk: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Päises RateLimit-Policy oleva rangeima kirje limiit (selle, millel on kõige vähem päringuid järel).
X-RateLimit-Remaining
Rangeima piirangu järgi järelejäänud päringud.
X-RateLimit-Reset
Sekundid rangeima piirangu lähtestumiseni.

application/json

Objekt: Error

401Autentimisandmeid ei saadetud (ei seansiküpsist ega API-võtit) või võtit ei leitud.

Vastuse päised

RateLimit-Policy
Kehtivad piirangud IETF-i mustandi draft-ietf-httpapi-ratelimit-headers vormingus: komadega eraldatud elemendid "<name>";q=<quota>;w=<window in seconds>. key on API-võtme päringusagedus (kvoot on tipuvaru, ajaaken on aeg selle täielikuks taastumiseks; seansi puhul on see user, ilma autentimisandmeteta ip); minute, day ja month on organisatsiooni kvoodid kalendriminutile, -päevale ja -kuule UTC järgi.
RateLimit
Iga päises RateLimit-Policy oleva piirangu jääk: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Päises RateLimit-Policy oleva rangeima kirje limiit (selle, millel on kõige vähem päringuid järel).
X-RateLimit-Remaining
Rangeima piirangu järgi järelejäänud päringud.
X-RateLimit-Reset
Sekundid rangeima piirangu lähtestumiseni.

application/json

Objekt: Error

403Toiming ei ole lubatud: rollist ei piisa, puudub juurdepääs kogule või kaardile, päring töötab režiimis „View as“ või organisatsioon on peatatud või kustutatud (`detail` on objekt väärtusega `code: org_suspended | org_deleted`).

Vastuse päised

RateLimit-Policy
Kehtivad piirangud IETF-i mustandi draft-ietf-httpapi-ratelimit-headers vormingus: komadega eraldatud elemendid "<name>";q=<quota>;w=<window in seconds>. key on API-võtme päringusagedus (kvoot on tipuvaru, ajaaken on aeg selle täielikuks taastumiseks; seansi puhul on see user, ilma autentimisandmeteta ip); minute, day ja month on organisatsiooni kvoodid kalendriminutile, -päevale ja -kuule UTC järgi.
RateLimit
Iga päises RateLimit-Policy oleva piirangu jääk: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Päises RateLimit-Policy oleva rangeima kirje limiit (selle, millel on kõige vähem päringuid järel).
X-RateLimit-Remaining
Rangeima piirangu järgi järelejäänud päringud.
X-RateLimit-Reset
Sekundid rangeima piirangu lähtestumiseni.

application/json

Objekt: Error

404Objekti ei ole olemas või see ei ole teile kättesaadav. API ei kinnita piiratud juurdepääsuga objekti olemasolu.

Vastuse päised

RateLimit-Policy
Kehtivad piirangud IETF-i mustandi draft-ietf-httpapi-ratelimit-headers vormingus: komadega eraldatud elemendid "<name>";q=<quota>;w=<window in seconds>. key on API-võtme päringusagedus (kvoot on tipuvaru, ajaaken on aeg selle täielikuks taastumiseks; seansi puhul on see user, ilma autentimisandmeteta ip); minute, day ja month on organisatsiooni kvoodid kalendriminutile, -päevale ja -kuule UTC järgi.
RateLimit
Iga päises RateLimit-Policy oleva piirangu jääk: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Päises RateLimit-Policy oleva rangeima kirje limiit (selle, millel on kõige vähem päringuid järel).
X-RateLimit-Remaining
Rangeima piirangu järgi järelejäänud päringud.
X-RateLimit-Reset
Sekundid rangeima piirangu lähtestumiseni.

application/json

Objekt: Error

422Valideerimisviga: keha või parameetrid ei vasta skeemile (`detail` on valideerimisvigade loend) või parameetri väärtus on lubatud vahemikust väljas (`detail` on teade).

Vastuse päised

RateLimit-Policy
Kehtivad piirangud IETF-i mustandi draft-ietf-httpapi-ratelimit-headers vormingus: komadega eraldatud elemendid "<name>";q=<quota>;w=<window in seconds>. key on API-võtme päringusagedus (kvoot on tipuvaru, ajaaken on aeg selle täielikuks taastumiseks; seansi puhul on see user, ilma autentimisandmeteta ip); minute, day ja month on organisatsiooni kvoodid kalendriminutile, -päevale ja -kuule UTC järgi.
RateLimit
Iga päises RateLimit-Policy oleva piirangu jääk: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Päises RateLimit-Policy oleva rangeima kirje limiit (selle, millel on kõige vähem päringuid järel).
X-RateLimit-Remaining
Rangeima piirangu järgi järelejäänud päringud.
X-RateLimit-Reset
Sekundid rangeima piirangu lähtestumiseni.

application/json

Objekt: Error

429Liiga palju päringuid (`api.rate_limited`), organisatsiooni minuti-, päeva- või kuukvoot on ära kasutatud (`api.quota_exceeded`; `error.details` sisaldab välju `quota`, `limit` ja `reset_at`), organisatsiooni limiit on täis või vastuseteenus on hõivatud (`answers.engine_busy`). Oodake päises `Retry-After` antud aeg.

Vastuse päised

Retry-After
Sekundite arv, mida oodata enne päringu kordamist.
RateLimit-Policy
Kehtivad piirangud IETF-i mustandi draft-ietf-httpapi-ratelimit-headers vormingus: komadega eraldatud elemendid "<name>";q=<quota>;w=<window in seconds>. key on API-võtme päringusagedus (kvoot on tipuvaru, ajaaken on aeg selle täielikuks taastumiseks; seansi puhul on see user, ilma autentimisandmeteta ip); minute, day ja month on organisatsiooni kvoodid kalendriminutile, -päevale ja -kuule UTC järgi.
RateLimit
Iga päises RateLimit-Policy oleva piirangu jääk: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Päises RateLimit-Policy oleva rangeima kirje limiit (selle, millel on kõige vähem päringuid järel).
X-RateLimit-Remaining
Rangeima piirangu järgi järelejäänud päringud.
X-RateLimit-Reset
Sekundid rangeima piirangu lähtestumiseni.

application/json

Objekt: Error

Veakoodid

Koodid, mida see lõpp-punkt võib lisaks iga päringu üldistele koodidele tagastada väljal error.code.

Sageduspiirangud

Vastustes on päised RateLimit ja RateLimit-Policy ning varasemad X-RateLimit-Limit, X-RateLimit-Remaining ja X-RateLimit-Reset. Vastuses 429 on päis Retry-After sekundites: oodake ja proovige uuesti.

← cards · API teatmik

curl 'https://api.sursa.com/v1/cards-by-external-id/EXTERNAL_ID' \
  -H "Authorization: Bearer $SURSA_API_KEY"

Proovi

API-võti

Võti jääb ainult selle vahekaardi mällu ja see saadetakse üksnes aadressile https://api.sursa.com.

Päringud muudavad teie organisatsiooni päris andmeid.

X-View-As header

external_id path *

expand[] query