POST/v1/cards/archive

Įkelti dokumentų archyvą

upload_card_archive

Siųskite ZIP archyvą multipart/form-data formos lauke file. Kiekvienas palaikomas failas archyve tampa atskiru dokumentu, kaip ir įkeliant po vieną (POST /v1/cards). ASiC parašų konteineriai (.asice, .sce, .bdoc, .asics) taip pat yra archyvai: jų duomenų failai tampa dokumentais, META-INF/ praleidžiamas, o parašas netikrinamas. Formos laukai tokie patys kaip įkeliant failą (rinkinys, žymos, atsakingas asmuo, kategorija, jautrumas), be peržiūros.

Archyvas tikrinamas pagal signatūrą (pervadintas Office dokumentas archyvu nelaikomas ir grąžina 415 files.type_mismatch), taikomas diegimo įkėlimo limitas, o antivirusinė patikra apima visą archyvą.

Turinio sąrašas tikrinamas sinchroniškai. Atsake pateikiamas planas (kurie failai tampa dokumentais, kurie praleidžiami ir kodėl) ir išskleidimo darbas (job_id, batch_id). Darbas atidaro įdėtuosius archyvus (pagal numatytuosius nustatymus iki 3 lygių), kiekvieną dokumentą tikrina pagal signatūrą ir antivirusine patikra ir įtraukia į įprastą indeksavimo eilę su tuo pačiu batch_id (dokumentų pažanga: GET /v1/jobs?batch=). Rezultatą galima gauti per GET /v1/archives/{job_id}.

Limitai (numatytieji diegimo nustatymai): iki 1000 failų visame medyje (daugiau grąžina 413 cards.archive_too_many_files), iki 2048 MB išskleidus (daugiau grąžina 413 cards.archive_too_large) ir ne daugiau nei organizacijai pagal planą likusi saugyklos vieta (402 limits.storage), kiekvienam archyvo failui – vieno failo įkėlimo limitas, o kiekvieno įrašo glaudinimo santykis – ne daugiau kaip 100:1. Įrašai su „..“, absoliučiu keliu arba disko raide, simbolinės nuorodos, šifruoti įrašai ir nepalaikomi formatai praleidžiami nurodant priežastį (skipped[].reason). OS sistemos failai, katalogai ir tušti failai praleidžiami tyliai (ignored). Pavadinimai ne UTF-8 koduote skaitomi kaip cp866 arba cp1251. Failas, kuris nėra ZIP, grąžina 400 cards.archive_invalid, visiškai šifruotas archyvas – 400 cards.archive_encrypted, o archyvas be nė vieno dokumento – 400 cards.archive_empty.

Kiekvienas dokumentas įsimena savo archyvą: CardVersion.archive ir Card.source_archive (kortelė rodo dabartinės versijos archyvą).

Vietoj formos galite siųsti application/json turinį (ArchiveUploadFromUpload, nuo 1.62.0): archyvas – paruoštas įkėlimas dalimis upload_id (paskirtis archive), laukai tokie patys kaip formoje, o tags – eilučių sąrašas. Archyvas jau buvo patikrintas atliekant complete, o dydžio limitas yra įkėlimo dalimis limitas, o ne vienos užklausos įkėlimo limitas. Įkėlimas panaudojamas vieną kartą, toje pačioje transakcijoje, kuri įtraukia išskleidimo darbą į eilę; įkėlimo klaidų kodai tokie patys kaip POST /v1/cards.

Autentifikavimas

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

Antraštės parametrai

Idempotency-Keystring
Raktas saugiam rašymo operacijos pakartojimui: nuo 1 iki 255 spausdinamų ASCII simbolių; rekomenduojamas atskiras UUID v4 kiekvienai loginei operacijai. Pakartojus užklausą su tuo pačiu raktu per 24 valandas, operacija iš naujo nevykdoma: grąžinamas išsaugotas atsakas (būsena, antraštės ir turinys) su antrašte Idempotency-Replayed: true. Tas pats raktas su kitu metodu, keliu, Content-Type ar turiniu grąžina 409 api.idempotency_mismatch; kol pirmoji užklausa dar vykdoma – 409 api.idempotency_in_progress su Retry-After: 1. Po 5xx ar 429 atsako raktas atlaisvinamas, ir pakartojimas operaciją vykdo iš naujo. Raktas galioja organizacijos ir iškvietėjo (API rakto, naudotojo arba pasirinktinio šaltinio rakto) ribose.
length ≥ 1, length ≤ 255
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.

Užklausos turinys

multipart/form-data

Objektas: ArchiveUploadForm

filestring (application/zip)privalomas
collectionstring
Numatytoji reikšmė: "default"
tagsstring
Numatytoji reikšmė: ""
forceboolean
Numatytoji reikšmė: false
owner_idinteger | null
verify_interval_daysinteger | null
categorystring | null
sensitiveboolean | null
folder_idstring | null
Rinkinio collection aplankas, į kurį dedami visi archyvo dokumentai. Kito rinkinio aplankas grąžina 400 folders.card_collection_mismatch, neegzistuojantis aplankas – 404 folders.not_found, o be leidimo COLLECTION_EDIT_CARDS aplankui grąžinama 403 authz.forbidden. Patikra atliekama prieš išsaugant archyvą. Jau įkeltų failų dublikatai į aplanką neperkeliami.
length ≤ 64
collection_idinteger | null
Rinkinys pagal ID. Kai perduodamas ir collection, pirmenybė teikiama collection_id. Rinkinys, kurio organizacijoje nėra arba kuris nematomas, grąžina 404 collections.not_found.

application/json

Objektas: ArchiveUploadFromUpload

upload_idstringprivalomas
Paruoštas įkėlimas (ready) su paskirtimi archive; naudojamas vieną kartą.
collectionstring
Numatytoji reikšmė: "default"
collection_idinteger | null
Rinkinys pagal ID. Jei perduodamas ir collection, pirmenybė teikiama collection_id. Jei rinkinio organizacijoje nėra, jis nematomas arba nepatenka į rakto rinkinius, grąžinama 404 collections.not_found.
tagsarray of string
items ≤ 30
forceboolean
Numatytoji reikšmė: false
owner_idinteger | null
verify_interval_daysinteger | null
categorystring | null
sensitiveboolean | null
folder_idstring | null
length ≤ 64

Atsakai

200Išskleidimo planas ir darbas

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.
Idempotency-Replayed
true – atsakas pakartotas iš šiam Idempotency-Key išsaugoto atsako: operacija iš naujo nevykdyta.

application/json

Objektas: ArchiveUploadResult

job_idintegerprivalomas
batch_idstringprivalomas
Archyvo dokumentų indeksavimo darbų partija (GET /v1/jobs?batch=).
statusstringprivalomas
Leidžiamos reikšmės: queued
archiveArchiveInfoprivalomas
plannedarray of stringprivalomas
Visų lygių failų, kurie taps dokumentais, keliai, įskaitant failus įdėtuosiuose archyvuose (b.zip/c.pdf).
documentsintegerprivalomas
Visų lygių dokumentų skaičius, įskaitant failus įdėtuosiuose archyvuose. Išskleidimo rezultatas sudaro tą patį skaičių: sukurti + dublikatai + atmesti turinio patikros (ArchiveJob).
nested_archivesintegerprivalomas
skippedarray of ArchiveSkipprivalomas
ignoredintegerprivalomas
Sisteminiai įrašai (OS failai, katalogai, tušti failai, konteinerių signatūros).

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

402Organizacija pasiekė plano limitą (kortelių, saugyklos ar naudotojų). `error.details` pateikia `kind`, `limit` ir `used`.

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

409Objekto būsena neleidžia atlikti veiksmo, pvz., dublikatas, vyksta indeksavimas arba darbas jau apdorotas.

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

410Objektas buvo, bet nebepasiekiamas: nuoroda jau panaudota arba nebegalioja, arba failas ištrintas pasibaigus jo saugojimo laikotarpiui.

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

413Užklausos turinys viršija leistiną dydį.

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

415Failo formatas nepalaikomas.

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

503Paslauga, nuo kurios priklauso ši užklausa, laikinai nepasiekiama. Pakartokite vėliau.

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

Klaidų kodai

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

Saugūs pakartojimai

Su kiekviena POST ir PATCH užklausa siųskite antraštę Idempotency-Key (pavyzdžiui, UUID). Pakartojus užklausą su tuo pačiu raktu per 24 valandas, grąžinamas išsaugotas atsakas, o užklausa iš naujo nevykdoma.

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

curl -X POST 'https://api.sursa.com/v1/cards/archive' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"upload_id":"upl_0123456789abcdef0123456789abcdef"}' \
  -H "Authorization: Bearer $SURSA_API_KEY"

Išbandyti

API raktas

Raktas laikomas tik šio skirtuko atmintyje ir siunčiamas tik į https://api.sursa.com.

Užklausos vykdomos su tikrais jūsų organizacijos duomenimis.

Idempotency-Key header

X-View-As header

Idempotency-Key

Jei laukas tuščias, kiekvienai užklausai sugeneruojamas naujas raktas.

Užklausos turinys (JSON)