POST/v1/cards/archive

Încarcă o arhivă de documente

upload_card_archive

Trimiteți o arhivă ZIP în câmpul file al unui formular multipart/form-data. Fiecare fișier acceptat din interior devine un document separat, ca la încărcările individuale (POST /v1/cards). Containerele de semnătură ASiC (.asice, .sce, .bdoc, .asics) sunt și ele arhive: fișierele lor de date devin documente, META-INF/ este omis, iar semnătura nu este verificată. Câmpurile formularului sunt aceleași ca la încărcarea unui fișier (colecție, etichete, responsabil, categorie, sensibilitate), fără previzualizare.

Arhiva este verificată după semnătură (un document Office redenumit nu contează ca arhivă și returnează 415 files.type_mismatch), se aplică limita de încărcare a instalării, iar scanarea antivirus acoperă întreaga arhivă.

Cuprinsul arhivei este verificat sincron. Răspunsul conține planul (ce fișiere devin documente, care sunt omise și de ce) și jobul de extragere (job_id, batch_id). Jobul deschide arhivele imbricate (implicit până la 3 niveluri), verifică fiecare document după semnătură și cu antivirusul și îl pune în coadă pentru indexarea obișnuită, cu același batch_id (progresul documentelor: GET /v1/jobs?batch=). Rezultatul este disponibil prin GET /v1/archives/{job_id}.

Limite (valorile implicite ale instalării): cel mult 1.000 de fișiere în tot arborele (mai multe returnează 413 cards.archive_too_many_files), cel mult 2.048 MB după dezarhivare (mai mult returnează 413 cards.archive_too_large) și nu mai mult decât spațiul de stocare rămas al organizației conform planului (402 limits.storage), limita de încărcare per fișier pentru fiecare fișier din interior și un raport de compresie de cel mult 100:1 pe intrare. Intrările cu „..”, cu o cale absolută sau cu o literă de unitate, legăturile simbolice, intrările criptate și formatele neacceptate sunt omise, cu un motiv (skipped[].reason). Fișierele de sistem ale sistemului de operare, directoarele și fișierele goale sunt omise fără mesaj (ignored). Numele care nu sunt în UTF-8 sunt citite ca cp866 sau cp1251. Un fișier care nu este ZIP returnează 400 cards.archive_invalid, o arhivă criptată integral returnează 400 cards.archive_encrypted, iar o arhivă fără niciun document returnează 400 cards.archive_empty.

Fiecare document își ține minte arhiva: CardVersion.archive și Card.source_archive (fișa afișează arhiva versiunii ei curente).

În locul formularului, puteți trimite un corp application/json (ArchiveUploadFromUpload, începând cu 1.62.0): arhiva este o încărcare în părți gata finalizată, upload_id (scopul archive), câmpurile sunt aceleași ca în formular, iar tags este o listă de șiruri. Arhiva a fost deja verificată la complete, iar limita de dimensiune este cea a încărcării în părți, nu cea a încărcării într-o singură cerere. Încărcarea se folosește o singură dată, în aceeași tranzacție care pune în coadă jobul de extragere; codurile de eroare ale încărcării sunt aceleași ca pentru POST /v1/cards.

Autentificare

Trimiteți o cheie API în antetul Authorization: Authorization: Bearer <cheie>.

Parametri de antet

Idempotency-Keystring
Cheie pentru reîncercarea sigură a unei scrieri: 1–255 de caractere ASCII imprimabile; se recomandă un UUID v4 pentru fiecare operație logică. O reîncercare cu aceeași cheie în decurs de 24 de ore nu execută din nou operația: returnează răspunsul salvat (status, antete și corp) cu antetul Idempotency-Replayed: true. Aceeași cheie cu altă metodă, altă cale, alt Content-Type sau alt corp returnează 409 api.idempotency_mismatch; cât timp prima cerere încă rulează – 409 api.idempotency_in_progress cu Retry-After: 1. După un răspuns 5xx sau 429, cheia este eliberată, iar o reîncercare execută din nou operația. Cheia este valabilă în cadrul organizației și al apelantului (cheie API, utilizator sau cheie de sursă personalizată).
length ≥ 1, length ≤ 255
X-View-Asstring
Doar pentru cheile API cu rolul admin. Execută cererea cu profilul de date <profile>[:viewer|verifier|editor], de exemplu employee:viewer. Cheia de instalare nu poate folosi acest antet (403).

Parametri cookie

kb_view_asstring
Cookie-ul modului „View as” (vizualizare ca alt utilizator) pentru o sesiune. POST /auth/view-as îl setează, iar DELETE /auth/view-as îl șterge.

Corpul cererii

multipart/form-data

Obiect: ArchiveUploadForm

filestring (application/zip)obligatoriu
collectionstring
Implicit: "default"
tagsstring
Implicit: ""
forceboolean
Implicit: false
owner_idinteger | null
verify_interval_daysinteger | null
categorystring | null
sensitiveboolean | null
folder_idstring | null
Dosarul din collection în care se pun toate documentele arhivei. Un dosar din altă colecție returnează 400 folders.card_collection_mismatch, un dosar inexistent returnează 404 folders.not_found, iar lipsa permisiunii COLLECTION_EDIT_CARDS pe dosar returnează 403 authz.forbidden. Verificarea are loc înainte de salvarea arhivei. Duplicatele fișierelor deja încărcate nu se mută în dosar.
length ≤ 64
collection_idinteger | null
Colecția după ID. Când se transmite și collection, are prioritate collection_id. O colecție care nu există în organizație sau nu este vizibilă returnează 404 collections.not_found.

application/json

Obiect: ArchiveUploadFromUpload

upload_idstringobligatoriu
O încărcare gata (ready) cu scopul archive; se folosește o singură dată.
collectionstring
Implicit: "default"
collection_idinteger | null
Colecția după ID. Când se transmite și collection, are prioritate collection_id. O colecție care nu există în organizație, nu este vizibilă sau se află în afara colecțiilor cheii returnează 404 collections.not_found.
tagsarray of string
items ≤ 30
forceboolean
Implicit: false
owner_idinteger | null
verify_interval_daysinteger | null
categorystring | null
sensitiveboolean | null
folder_idstring | null
length ≤ 64

Răspunsuri

200Planul de extragere și jobul

Antetele răspunsului

RateLimit-Policy
Limitele în vigoare, în formatul proiectului IETF draft-ietf-httpapi-ratelimit-headers: elemente separate prin virgulă "<name>";q=<quota>;w=<window in seconds>. key este frecvența cererilor cheii API (cota este rafala, fereastra este timpul în care rafala se reface complet; pentru o sesiune este user, fără date de autentificare ip); minute, day și month sunt cotele organizației pentru minutul, ziua și luna calendaristice în UTC.
RateLimit
Cât a rămas din fiecare limită din RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limita celei mai stricte intrări din RateLimit-Policy (cea cu cele mai puține cereri rămase).
X-RateLimit-Remaining
Cereri rămase în cadrul celei mai stricte limite.
X-RateLimit-Reset
Secunde până la resetarea celei mai stricte limite.
Idempotency-Replayed
true înseamnă că răspunsul a fost redat din cel salvat pentru această cheie Idempotency-Key: operația nu a rulat din nou.

application/json

Obiect: ArchiveUploadResult

job_idintegerobligatoriu
batch_idstringobligatoriu
Lotul de joburi de indexare pentru documentele arhivei (GET /v1/jobs?batch=).
statusstringobligatoriu
Valori permise: queued
archiveArchiveInfoobligatoriu
plannedarray of stringobligatoriu
Căile fișierelor de pe toate nivelurile care vor deveni documente, inclusiv fișierele din arhivele imbricate (b.zip/c.pdf).
documentsintegerobligatoriu
Numărul de documente de pe toate nivelurile, inclusiv fișierele din arhivele imbricate. Rezultatul extragerii dă același număr: create + duplicate + respinse la verificarea conținutului (ArchiveJob).
nested_archivesintegerobligatoriu
skippedarray of ArchiveSkipobligatoriu
ignoredintegerobligatoriu
Intrări de sistem (fișiere ale sistemului de operare, directoare, fișiere goale, semnături de container).

400Cererea este invalidă: valoarea unui parametru sau starea obiectului nu permite acțiunea (`detail` este un mesaj).

Antetele răspunsului

RateLimit-Policy
Limitele în vigoare, în formatul proiectului IETF draft-ietf-httpapi-ratelimit-headers: elemente separate prin virgulă "<name>";q=<quota>;w=<window in seconds>. key este frecvența cererilor cheii API (cota este rafala, fereastra este timpul în care rafala se reface complet; pentru o sesiune este user, fără date de autentificare ip); minute, day și month sunt cotele organizației pentru minutul, ziua și luna calendaristice în UTC.
RateLimit
Cât a rămas din fiecare limită din RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limita celei mai stricte intrări din RateLimit-Policy (cea cu cele mai puține cereri rămase).
X-RateLimit-Remaining
Cereri rămase în cadrul celei mai stricte limite.
X-RateLimit-Reset
Secunde până la resetarea celei mai stricte limite.

application/json

Obiect: Error

401Nu au fost trimise date de autentificare (nici cookie de sesiune, nici cheie API) sau cheia nu a fost găsită.

Antetele răspunsului

RateLimit-Policy
Limitele în vigoare, în formatul proiectului IETF draft-ietf-httpapi-ratelimit-headers: elemente separate prin virgulă "<name>";q=<quota>;w=<window in seconds>. key este frecvența cererilor cheii API (cota este rafala, fereastra este timpul în care rafala se reface complet; pentru o sesiune este user, fără date de autentificare ip); minute, day și month sunt cotele organizației pentru minutul, ziua și luna calendaristice în UTC.
RateLimit
Cât a rămas din fiecare limită din RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limita celei mai stricte intrări din RateLimit-Policy (cea cu cele mai puține cereri rămase).
X-RateLimit-Remaining
Cereri rămase în cadrul celei mai stricte limite.
X-RateLimit-Reset
Secunde până la resetarea celei mai stricte limite.

application/json

Obiect: Error

402Organizația a atins o limită a planului (fișe, spațiu de stocare sau utilizatori). `error.details` conține `kind`, `limit` și `used`.

Antetele răspunsului

RateLimit-Policy
Limitele în vigoare, în formatul proiectului IETF draft-ietf-httpapi-ratelimit-headers: elemente separate prin virgulă "<name>";q=<quota>;w=<window in seconds>. key este frecvența cererilor cheii API (cota este rafala, fereastra este timpul în care rafala se reface complet; pentru o sesiune este user, fără date de autentificare ip); minute, day și month sunt cotele organizației pentru minutul, ziua și luna calendaristice în UTC.
RateLimit
Cât a rămas din fiecare limită din RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limita celei mai stricte intrări din RateLimit-Policy (cea cu cele mai puține cereri rămase).
X-RateLimit-Remaining
Cereri rămase în cadrul celei mai stricte limite.
X-RateLimit-Reset
Secunde până la resetarea celei mai stricte limite.

application/json

Obiect: Error

403Acțiunea nu este permisă: rolul este insuficient, nu există acces la colecție sau la fișă, cererea rulează în modul „View as” (vizualizare ca alt utilizator) sau organizația este suspendată ori ștearsă (`detail` este un obiect cu `code: org_suspended | org_deleted`).

Antetele răspunsului

RateLimit-Policy
Limitele în vigoare, în formatul proiectului IETF draft-ietf-httpapi-ratelimit-headers: elemente separate prin virgulă "<name>";q=<quota>;w=<window in seconds>. key este frecvența cererilor cheii API (cota este rafala, fereastra este timpul în care rafala se reface complet; pentru o sesiune este user, fără date de autentificare ip); minute, day și month sunt cotele organizației pentru minutul, ziua și luna calendaristice în UTC.
RateLimit
Cât a rămas din fiecare limită din RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limita celei mai stricte intrări din RateLimit-Policy (cea cu cele mai puține cereri rămase).
X-RateLimit-Remaining
Cereri rămase în cadrul celei mai stricte limite.
X-RateLimit-Reset
Secunde până la resetarea celei mai stricte limite.

application/json

Obiect: Error

404Obiectul nu există sau nu vă este disponibil. API-ul nu confirmă existența unui obiect restricționat.

Antetele răspunsului

RateLimit-Policy
Limitele în vigoare, în formatul proiectului IETF draft-ietf-httpapi-ratelimit-headers: elemente separate prin virgulă "<name>";q=<quota>;w=<window in seconds>. key este frecvența cererilor cheii API (cota este rafala, fereastra este timpul în care rafala se reface complet; pentru o sesiune este user, fără date de autentificare ip); minute, day și month sunt cotele organizației pentru minutul, ziua și luna calendaristice în UTC.
RateLimit
Cât a rămas din fiecare limită din RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limita celei mai stricte intrări din RateLimit-Policy (cea cu cele mai puține cereri rămase).
X-RateLimit-Remaining
Cereri rămase în cadrul celei mai stricte limite.
X-RateLimit-Reset
Secunde până la resetarea celei mai stricte limite.

application/json

Obiect: Error

409Starea obiectului nu permite acțiunea, de exemplu o dublură, o indexare în curs sau un job deja procesat.

Antetele răspunsului

RateLimit-Policy
Limitele în vigoare, în formatul proiectului IETF draft-ietf-httpapi-ratelimit-headers: elemente separate prin virgulă "<name>";q=<quota>;w=<window in seconds>. key este frecvența cererilor cheii API (cota este rafala, fereastra este timpul în care rafala se reface complet; pentru o sesiune este user, fără date de autentificare ip); minute, day și month sunt cotele organizației pentru minutul, ziua și luna calendaristice în UTC.
RateLimit
Cât a rămas din fiecare limită din RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limita celei mai stricte intrări din RateLimit-Policy (cea cu cele mai puține cereri rămase).
X-RateLimit-Remaining
Cereri rămase în cadrul celei mai stricte limite.
X-RateLimit-Reset
Secunde până la resetarea celei mai stricte limite.

application/json

Obiect: Error

410Obiectul a existat, dar nu mai este disponibil: linkul a fost folosit sau a expirat ori fișierul a fost șters la sfârșitul perioadei de păstrare.

Antetele răspunsului

RateLimit-Policy
Limitele în vigoare, în formatul proiectului IETF draft-ietf-httpapi-ratelimit-headers: elemente separate prin virgulă "<name>";q=<quota>;w=<window in seconds>. key este frecvența cererilor cheii API (cota este rafala, fereastra este timpul în care rafala se reface complet; pentru o sesiune este user, fără date de autentificare ip); minute, day și month sunt cotele organizației pentru minutul, ziua și luna calendaristice în UTC.
RateLimit
Cât a rămas din fiecare limită din RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limita celei mai stricte intrări din RateLimit-Policy (cea cu cele mai puține cereri rămase).
X-RateLimit-Remaining
Cereri rămase în cadrul celei mai stricte limite.
X-RateLimit-Reset
Secunde până la resetarea celei mai stricte limite.

application/json

Obiect: Error

413Corpul cererii depășește dimensiunea permisă.

Antetele răspunsului

RateLimit-Policy
Limitele în vigoare, în formatul proiectului IETF draft-ietf-httpapi-ratelimit-headers: elemente separate prin virgulă "<name>";q=<quota>;w=<window in seconds>. key este frecvența cererilor cheii API (cota este rafala, fereastra este timpul în care rafala se reface complet; pentru o sesiune este user, fără date de autentificare ip); minute, day și month sunt cotele organizației pentru minutul, ziua și luna calendaristice în UTC.
RateLimit
Cât a rămas din fiecare limită din RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limita celei mai stricte intrări din RateLimit-Policy (cea cu cele mai puține cereri rămase).
X-RateLimit-Remaining
Cereri rămase în cadrul celei mai stricte limite.
X-RateLimit-Reset
Secunde până la resetarea celei mai stricte limite.

application/json

Obiect: Error

415Formatul fișierului nu este acceptat.

Antetele răspunsului

RateLimit-Policy
Limitele în vigoare, în formatul proiectului IETF draft-ietf-httpapi-ratelimit-headers: elemente separate prin virgulă "<name>";q=<quota>;w=<window in seconds>. key este frecvența cererilor cheii API (cota este rafala, fereastra este timpul în care rafala se reface complet; pentru o sesiune este user, fără date de autentificare ip); minute, day și month sunt cotele organizației pentru minutul, ziua și luna calendaristice în UTC.
RateLimit
Cât a rămas din fiecare limită din RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limita celei mai stricte intrări din RateLimit-Policy (cea cu cele mai puține cereri rămase).
X-RateLimit-Remaining
Cereri rămase în cadrul celei mai stricte limite.
X-RateLimit-Reset
Secunde până la resetarea celei mai stricte limite.

application/json

Obiect: Error

422Eroare de validare: corpul sau parametrii nu corespund schemei (`detail` este o listă de erori de validare) ori valoarea unui parametru este în afara intervalului permis (`detail` este un mesaj).

Antetele răspunsului

RateLimit-Policy
Limitele în vigoare, în formatul proiectului IETF draft-ietf-httpapi-ratelimit-headers: elemente separate prin virgulă "<name>";q=<quota>;w=<window in seconds>. key este frecvența cererilor cheii API (cota este rafala, fereastra este timpul în care rafala se reface complet; pentru o sesiune este user, fără date de autentificare ip); minute, day și month sunt cotele organizației pentru minutul, ziua și luna calendaristice în UTC.
RateLimit
Cât a rămas din fiecare limită din RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limita celei mai stricte intrări din RateLimit-Policy (cea cu cele mai puține cereri rămase).
X-RateLimit-Remaining
Cereri rămase în cadrul celei mai stricte limite.
X-RateLimit-Reset
Secunde până la resetarea celei mai stricte limite.

application/json

Obiect: Error

429Prea multe cereri (`api.rate_limited`), cota organizației pentru minut, zi sau lună este epuizată (`api.quota_exceeded`; `error.details` conține `quota`, `limit` și `reset_at`), limita organizației este atinsă sau serviciul de răspunsuri este ocupat (`answers.engine_busy`). Așteptați timpul indicat în antetul `Retry-After`.

Antetele răspunsului

Retry-After
Numărul de secunde de așteptat înainte de a reîncerca cererea.
RateLimit-Policy
Limitele în vigoare, în formatul proiectului IETF draft-ietf-httpapi-ratelimit-headers: elemente separate prin virgulă "<name>";q=<quota>;w=<window in seconds>. key este frecvența cererilor cheii API (cota este rafala, fereastra este timpul în care rafala se reface complet; pentru o sesiune este user, fără date de autentificare ip); minute, day și month sunt cotele organizației pentru minutul, ziua și luna calendaristice în UTC.
RateLimit
Cât a rămas din fiecare limită din RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limita celei mai stricte intrări din RateLimit-Policy (cea cu cele mai puține cereri rămase).
X-RateLimit-Remaining
Cereri rămase în cadrul celei mai stricte limite.
X-RateLimit-Reset
Secunde până la resetarea celei mai stricte limite.

application/json

Obiect: Error

503Un serviciu de care depinde această cerere este temporar indisponibil. Reîncercați mai târziu.

Antetele răspunsului

RateLimit-Policy
Limitele în vigoare, în formatul proiectului IETF draft-ietf-httpapi-ratelimit-headers: elemente separate prin virgulă "<name>";q=<quota>;w=<window in seconds>. key este frecvența cererilor cheii API (cota este rafala, fereastra este timpul în care rafala se reface complet; pentru o sesiune este user, fără date de autentificare ip); minute, day și month sunt cotele organizației pentru minutul, ziua și luna calendaristice în UTC.
RateLimit
Cât a rămas din fiecare limită din RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limita celei mai stricte intrări din RateLimit-Policy (cea cu cele mai puține cereri rămase).
X-RateLimit-Remaining
Cereri rămase în cadrul celei mai stricte limite.
X-RateLimit-Reset
Secunde până la resetarea celei mai stricte limite.

application/json

Obiect: Error

Coduri de eroare

Codurile pe care acest endpoint le poate returna în error.code, pe lângă codurile generale ale oricărei cereri.

Reîncercări sigure

Trimiteți un antet Idempotency-Key (de exemplu, un UUID) cu fiecare POST și PATCH. O reîncercare cu aceeași cheie în decurs de 24 de ore returnează răspunsul salvat, fără să execute din nou cererea.

Limite de frecvență

Răspunsurile conțin antetele RateLimit și RateLimit-Policy, precum și antetele anterioare X-RateLimit-Limit, X-RateLimit-Remaining și X-RateLimit-Reset. Un răspuns 429 conține Retry-After în secunde: așteptați și reîncercați.

← cards · Referința API

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"

Încercați

Cheie API

Cheia rămâne în memoria acestei file a browserului și este trimisă doar către https://api.sursa.com.

Cererile se execută pe datele reale ale organizației.

Idempotency-Key header

X-View-As header

Idempotency-Key

Dacă acest câmp este gol, pentru fiecare cerere se generează o cheie nouă.

Corpul cererii (JSON)