POST/v1/cards

Faili üleslaadimine kaardina

upload_card

Saatke dokument vormi multipart/form-data väljal file. Enne salvestamist kontrollib Sursa, et failinime laiend, osa deklareeritud Content-Type ja sisu signatuur on omavahel kooskõlas:
- PDF;
- DOCX, XLSX, XLSM, PPTX: ZIP deklareeritud põhidokumendi tüübiga;
- ODS: ZIP kirjega mimetype;
- XLS: OLE2-dokument töövihiku vooga;
- TXT, MD, CSV, TSV, HTML, AsciiDoc, EML: tekst ilma nullbaitideta, UTF-8 või ühebaidises kodeeringus, e-kirja puhul päised alguses;
- PNG, JPEG, TIFF, WebP, BMP: signatuuri järgi.

Mittevastavuse korral tagastatakse 415 files.type_mismatch; vormingute loendist väljas oleva laiendi korral 415 cards.unsupported_format. Fail, mis on suurem kui paigalduse üleslaadimislimiit või organisatsiooni paketijärgne kogu salvestusruum, tagastab 413 files.too_large. Kui viirusskannimine on sisse lülitatud, tagastab nakatunud fail 422 files.infected ja kui skanner ei ole poliitika „reject“ korral kättesaadav, tagastab päring 503 files.scan_unavailable. Iga tagasilükkamine kirjutatakse auditilogisse kujul file.rejected.

Vormi asemel võite saata application/json keha (CardUploadFromUpload, alates versioonist 1.62.0): fail on valmis mitmeosaline üleslaadimine upload_id (POST /v1/uploads otstarbega card_file), väljad on samad mis vormis ja tags on stringide loend. Üleslaadimise fail on juba kontrollitud sammus complete (vorming, viirusskannimine) ning suuruse limiit on mitmeosalise üleslaadimise limiit, mitte ühe päringuga üleslaadimise limiit. Üleslaadimist kasutatakse üks kord, samas tehingus, mis loob kaardi: juba kasutatud üleslaadimine tagastab 409 uploads.already_used, veel mittevalmis üleslaadimine 409 uploads.not_ready, tagasi lükatud üleslaadimine 422 uploads.rejected, teise otstarbega üleslaadimine 422 uploads.purpose_mismatch, kehtivuse kaotanud üleslaadimine 410 uploads.expired ning teise päringu tegija või tundmatu üleslaadimine 404 uploads.not_found. Kui kaardi kontrollimine nurjub (kogu, kategooria, limiidid), siis üleslaadimist ära ei kasutata.

Autentimine

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

Päiseparameetrid

Idempotency-Keystring
Võti kirjutamistoimingu turvaliseks kordamiseks: 1–255 prinditavat ASCII-märki; soovitatav on UUID v4 iga loogilise toimingu kohta. Kordus sama võtmega 24 tunni jooksul ei käivita toimingut uuesti: tagastatakse salvestatud vastus (olek, päised ja keha) päisega Idempotency-Replayed: true. Sama võti teise meetodi, tee, Content-Type või kehaga tagastab 409 api.idempotency_mismatch; kuni esimene päring veel töötab, tagastatakse 409 api.idempotency_in_progress koos päisega Retry-After: 1. Pärast vastust 5xx või 429 võti vabastatakse ja kordus käivitab toimingu uuesti. Võti kehtib organisatsiooni ja päringu tegija piires (API-võti, kasutaja või kohandatud allika võti).
length ≥ 1, length ≤ 255
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.

Päringu keha

multipart/form-data

Objekt: CardUploadForm

filestring (application/octet-stream)kohustuslik
collectionstring
Vaikimisi: "default"
tagsstring
Vaikimisi: ""
forceboolean
Vaikimisi: false
owner_idinteger | null
verify_interval_daysinteger | null
categorystring | null
sensitiveboolean | null
asyncboolean
Vaikimisi: false
reviewboolean
Vaikimisi: false
folder_idstring | null
Kogu collection kaust, kuhu uus kaart paigutatakse. Teise kogu kaust tagastab vastuse 400 folders.card_collection_mismatch, puuduv kaust vastuse 404 folders.not_found ja õiguse COLLECTION_EDIT_CARDS puudumine kaustal vastuse 403 authz.forbidden. Kontroll tehakse enne faili salvestamist. Juba üles laaditud faili duplikaati (skipped) kausta ei teisaldata.
length ≤ 64
collection_idinteger | null
Kogu ID järgi. Kui edastatakse ka collection, kehtib collection_id. Kogu, mida organisatsioonis ei ole või mis ei ole nähtav, tagastab vastuse 404 collections.not_found.
external_idstring | null
Uue kaardi external_id. Sellega luuakse kaart ka siis, kui kogus on juba sama fail. Kui seda kasutab organisatsiooni teine kaart, tagastab päring vastuse 409 cards.external_id_taken. Kaardi loomiseks või asendamiseks välja external_id järgi kasutage toimingut PUT /v1/cards-by-external-id/{external_id}.
length ≤ 512
metadatastring | null
Uue kaardi metadata: JSON-objekt vormivälja väärtusena. Reeglid on samad mis skeemil MetadataPatch.

application/json

Objekt: CardUploadFromUpload

upload_idstringkohustuslik
Valmis üleslaadimine (ready) otstarbega card_file; seda kasutatakse üks kord.
collectionstring
Vaikimisi: "default"
collection_idinteger | null
Kogu ID järgi. Kui edastatakse ka collection, on ülimuslik collection_id. Kogu, mida organisatsioonis ei ole, mis ei ole nähtav või mis on väljaspool võtme kogusid, tagastab 404 collections.not_found.
tagsarray of string
items ≤ 30
forceboolean
Vaikimisi: false
owner_idinteger | null
verify_interval_daysinteger | null
categorystring | null
sensitiveboolean | null
asyncboolean
Vaikimisi: false
reviewboolean
Vaikimisi: false
folder_idstring | null
length ≤ 64
external_idstring | null
Uue kaardi external_id, nagu vormiväljal. Sellega luuakse kaart ka siis, kui kogus on juba sama fail. Kui seda kasutab organisatsiooni mõni teine kaart, tagastab päring 409 cards.external_id_taken.
length ≤ 512
metadataMetadataPatch

Vastused

200`queued` (asünkroonne), `skipped` (duplikaat), `ready` või `error` (sünkroonne).

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.
Idempotency-Replayed
true tähendab, et vastus esitati uuesti selle Idempotency-Key jaoks salvestatud vastusest: toimingut uuesti ei käivitatud.

application/json

Objekt: UploadResult

statusstringkohustuslik
Lubatud väärtused: queuedskippedreadyerror
job_idinteger
jobJob
cardCard | null
duplicatetrue
card_idstring | null
reasonstring
unchanged või an identical file is already indexed.
tablesinteger
timingsobject
Väljad
- total_snumber
errorstring

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

402Organisatsioon on jõudnud paketi limiidini (kaardid, salvestusruum või kasutajad). `error.details` sisaldab välju `kind`, `limit` ja `used`.

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

409Objekti olek ei võimalda toimingut, näiteks duplikaat, käimasolev indekseerimine või juba töödeldud töö.

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

410Objekt oli olemas, kuid ei ole enam kättesaadav: link on kasutatud või selle kehtivus on lõppenud või fail kustutati säilitusaja lõpus.

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

413Päringu keha ületab lubatud suuruse.

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

415Failivormingut ei toetata.

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

503Teenus, millest see päring sõltub, ei ole ajutiselt kättesaadav. Proovige hiljem uuesti.

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

Veakoodid

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

Turvalised korduskatsed

Saatke iga POST- ja PATCH-päringuga päis Idempotency-Key (näiteks UUID). Sama võtmega korduskatse 24 tunni jooksul tagastab salvestatud vastuse ega käivita päringut uuesti.

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 -X POST 'https://api.sursa.com/v1/cards' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"upload_id":"upl_0123456789abcdef0123456789abcdef"}' \
  -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.

Idempotency-Key header

X-View-As header

Idempotency-Key

Kui väli on tühi, luuakse iga päringu jaoks uus võti.

Päringu keha (JSON)