POST/v1/cards/archive

Archief met documenten uploaden

upload_card_archive

Stuur een ZIP-archief in het veld file van een multipart/form-data-formulier. Elk ondersteund bestand erin wordt een afzonderlijk document, net als bij losse uploads (POST /v1/cards). ASiC-handtekeningcontainers (.asice, .sce, .bdoc, .asics) zijn ook archieven: hun gegevensbestanden worden documenten, META-INF/ wordt overgeslagen en de handtekening wordt niet geverifieerd. De velden van het formulier zijn dezelfde als bij een bestandsupload (collectie, tags, eigenaar, categorie, gevoeligheid), zonder voorbeeld.

Het archief wordt op signatuur gecontroleerd (een hernoemd Office-document telt niet als archief en geeft 415 files.type_mismatch), de uploadlimiet van de installatie geldt, en de virusscan dekt het hele archief.

De inhoudsopgave wordt synchroon gecontroleerd. De response bevat het plan (welke bestanden documenten worden, welke worden overgeslagen en waarom) en de uitpakjob (job_id, batch_id). De job opent geneste archieven (standaard tot 3 niveaus), controleert elk document op signatuur en met de virusscan, en zet het in de wachtrij voor de gewone indexering met dezelfde batch_id (voortgang van de documenten: GET /v1/jobs?batch=). Het resultaat is beschikbaar via GET /v1/archives/{job_id}.

Limieten (standaardwaarden van de installatie): maximaal 1000 bestanden in de hele boom (meer geeft 413 cards.archive_too_many_files), maximaal 2048 MB uitgepakt (meer geeft 413 cards.archive_too_large) en niet meer dan de resterende opslag van de organisatie volgens haar abonnement (402 limits.storage), de uploadlimiet per bestand voor elk bestand erin, en een compressieverhouding van maximaal 100:1 per item. Items met “..”, een absoluut pad of een stationsletter, symbolische links, versleutelde items en niet-ondersteunde formaten worden met een reden overgeslagen (skipped[].reason). Systeembestanden van het besturingssysteem, mappen en lege bestanden worden zonder melding overgeslagen (ignored). Namen die niet in UTF-8 zijn, worden gelezen als cp866 of cp1251. Een bestand dat geen ZIP is, geeft 400 cards.archive_invalid, een volledig versleuteld archief geeft 400 cards.archive_encrypted, en een archief zonder één document geeft 400 cards.archive_empty.

Elk document onthoudt zijn archief: CardVersion.archive en Card.source_archive (de kaart toont het archief van zijn huidige versie).

In plaats van het formulier kun je een application/json-body sturen (ArchiveUploadFromUpload, sinds 1.62.0): het archief is een voltooide upload in delen upload_id (het doel archive), de velden zijn dezelfde als in het formulier en tags is een lijst met strings. Het archief is al gecontroleerd bij complete, en de groottelimiet is die voor uploads in delen in plaats van die voor uploads in één request. De upload wordt één keer gebruikt, in dezelfde transactie die de uitpakjob in de wachtrij zet; de foutcodes voor uploads zijn dezelfde als bij POST /v1/cards.

Authenticatie

Stuur een API-sleutel mee in de header Authorization: Authorization: Bearer <sleutel>.

Headerparameters

Idempotency-Keystring
Sleutel om een schrijfactie veilig opnieuw te proberen: 1 tot 255 afdrukbare ASCII-tekens; een UUID v4 per logische bewerking wordt aanbevolen. Een nieuwe poging met dezelfde sleutel binnen 24 uur voert de bewerking niet opnieuw uit: Sursa geeft de opgeslagen response terug (status, headers en body) met de header Idempotency-Replayed: true. Dezelfde sleutel met een andere methode, een ander pad, een andere Content-Type of een andere body geeft 409 api.idempotency_mismatch; zolang het eerste request nog loopt, 409 api.idempotency_in_progress met Retry-After: 1. Na een 5xx- of 429-response wordt de sleutel vrijgegeven en voert een nieuwe poging de bewerking opnieuw uit. De sleutel geldt per organisatie en per aanroeper (API-sleutel, gebruiker of bronsleutel).
length ≥ 1, length ≤ 255
X-View-Asstring
Alleen voor API-sleutels met de rol admin. Voert het request uit als het dataprofiel <profile>[:viewer|verifier|editor], bijvoorbeeld employee:viewer. De installatiesleutel kan deze header niet gebruiken (403).

Cookieparameters

kb_view_asstring
Cookie van de modus “View as” voor een sessie. POST /auth/view-as zet hem en DELETE /auth/view-as wist hem.

Request-body

multipart/form-data

Object: ArchiveUploadForm

filestring (application/zip)verplicht
collectionstring
Standaard: "default"
tagsstring
Standaard: ""
forceboolean
Standaard: false
owner_idinteger | null
verify_interval_daysinteger | null
categorystring | null
sensitiveboolean | null
folder_idstring | null
Map van de collection waarin alle documenten van het archief komen. Een map van een andere collectie geeft 400 folders.card_collection_mismatch, een ontbrekende map geeft 404 folders.not_found, en zonder het recht COLLECTION_EDIT_CARDS op de map volgt 403 authz.forbidden. De controle gebeurt voordat het archief wordt opgeslagen. Duplicaten van bestanden die al zijn geüpload, worden niet naar de map verplaatst.
length ≤ 64
collection_idinteger | null
Collectie op ID. Wordt collection ook meegegeven, dan heeft collection_id voorrang. Een collectie die niet in de organisatie bestaat of niet zichtbaar is, geeft 404 collections.not_found.

application/json

Object: ArchiveUploadFromUpload

upload_idstringverplicht
Een gereedstaande upload (ready) met het doel archive; die wordt één keer gebruikt.
collectionstring
Standaard: "default"
collection_idinteger | null
Collectie op ID. Wordt ook collection meegegeven, dan heeft collection_id voorrang. Een collectie die niet bestaat in de organisatie, niet zichtbaar is of buiten de collecties van de sleutel valt, geeft 404 collections.not_found.
tagsarray of string
items ≤ 30
forceboolean
Standaard: false
owner_idinteger | null
verify_interval_daysinteger | null
categorystring | null
sensitiveboolean | null
folder_idstring | null
length ≤ 64

Responses

200Uitpakplan en job

Responseheaders

RateLimit-Policy
Geldende limieten, in het formaat van het IETF-concept draft-ietf-httpapi-ratelimit-headers: items gescheiden door komma’s, "<name>";q=<quota>;w=<window in seconds>. key is de requestsnelheid van de API-sleutel (het quotum is de piek, het venster de tijd om die volledig aan te vullen; voor een sessie is het user, zonder authenticatiegegevens ip); minute, day en month zijn de quota van de organisatie voor de kalenderminuut, -dag en -maand in UTC.
RateLimit
Wat er over is van elke limiet in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limiet van de strengste regel in RateLimit-Policy (die met de minste resterende requests).
X-RateLimit-Remaining
Resterende requests onder de strengste limiet.
X-RateLimit-Reset
Seconden tot de strengste limiet wordt teruggezet.
Idempotency-Replayed
true: de response is opnieuw afgespeeld uit de opgeslagen response voor deze Idempotency-Key; de bewerking is niet opnieuw uitgevoerd.

application/json

Object: ArchiveUploadResult

job_idintegerverplicht
batch_idstringverplicht
Batch van indexeringsjobs voor de documenten van het archief (GET /v1/jobs?batch=).
statusstringverplicht
Toegestane waarden: queued
archiveArchiveInfoverplicht
plannedarray of stringverplicht
Paden van de bestanden op alle niveaus die documenten worden, inclusief bestanden in geneste archieven (b.zip/c.pdf).
documentsintegerverplicht
Aantal documenten op alle niveaus, inclusief bestanden in geneste archieven. Het resultaat van het uitpakken telt op tot hetzelfde aantal: aangemaakt + duplicaten + afgewezen door de inhoudscontrole (ArchiveJob).
nested_archivesintegerverplicht
skippedarray of ArchiveSkipverplicht
ignoredintegerverplicht
Systeemitems (bestanden van het besturingssysteem, mappen, lege bestanden, containerhandtekeningen).

400Het request is ongeldig: een parameterwaarde of de toestand van het object staat de actie niet toe (`detail` is een melding).

Responseheaders

RateLimit-Policy
Geldende limieten, in het formaat van het IETF-concept draft-ietf-httpapi-ratelimit-headers: items gescheiden door komma’s, "<name>";q=<quota>;w=<window in seconds>. key is de requestsnelheid van de API-sleutel (het quotum is de piek, het venster de tijd om die volledig aan te vullen; voor een sessie is het user, zonder authenticatiegegevens ip); minute, day en month zijn de quota van de organisatie voor de kalenderminuut, -dag en -maand in UTC.
RateLimit
Wat er over is van elke limiet in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limiet van de strengste regel in RateLimit-Policy (die met de minste resterende requests).
X-RateLimit-Remaining
Resterende requests onder de strengste limiet.
X-RateLimit-Reset
Seconden tot de strengste limiet wordt teruggezet.

application/json

Object: Error

401Er zijn geen authenticatiegegevens meegestuurd (geen sessiecookie en geen API-sleutel), of de sleutel is niet gevonden.

Responseheaders

RateLimit-Policy
Geldende limieten, in het formaat van het IETF-concept draft-ietf-httpapi-ratelimit-headers: items gescheiden door komma’s, "<name>";q=<quota>;w=<window in seconds>. key is de requestsnelheid van de API-sleutel (het quotum is de piek, het venster de tijd om die volledig aan te vullen; voor een sessie is het user, zonder authenticatiegegevens ip); minute, day en month zijn de quota van de organisatie voor de kalenderminuut, -dag en -maand in UTC.
RateLimit
Wat er over is van elke limiet in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limiet van de strengste regel in RateLimit-Policy (die met de minste resterende requests).
X-RateLimit-Remaining
Resterende requests onder de strengste limiet.
X-RateLimit-Reset
Seconden tot de strengste limiet wordt teruggezet.

application/json

Object: Error

402De organisatie heeft een abonnementslimiet bereikt (kaarten, opslag of gebruikers). `error.details` bevat `kind`, `limit` en `used`.

Responseheaders

RateLimit-Policy
Geldende limieten, in het formaat van het IETF-concept draft-ietf-httpapi-ratelimit-headers: items gescheiden door komma’s, "<name>";q=<quota>;w=<window in seconds>. key is de requestsnelheid van de API-sleutel (het quotum is de piek, het venster de tijd om die volledig aan te vullen; voor een sessie is het user, zonder authenticatiegegevens ip); minute, day en month zijn de quota van de organisatie voor de kalenderminuut, -dag en -maand in UTC.
RateLimit
Wat er over is van elke limiet in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limiet van de strengste regel in RateLimit-Policy (die met de minste resterende requests).
X-RateLimit-Remaining
Resterende requests onder de strengste limiet.
X-RateLimit-Reset
Seconden tot de strengste limiet wordt teruggezet.

application/json

Object: Error

403De actie is niet toegestaan: de rol volstaat niet, er is geen toegang tot de collectie of kaart, het request draait in de modus “View as”, of de organisatie is opgeschort of verwijderd (`detail` is een object met `code: org_suspended | org_deleted`).

Responseheaders

RateLimit-Policy
Geldende limieten, in het formaat van het IETF-concept draft-ietf-httpapi-ratelimit-headers: items gescheiden door komma’s, "<name>";q=<quota>;w=<window in seconds>. key is de requestsnelheid van de API-sleutel (het quotum is de piek, het venster de tijd om die volledig aan te vullen; voor een sessie is het user, zonder authenticatiegegevens ip); minute, day en month zijn de quota van de organisatie voor de kalenderminuut, -dag en -maand in UTC.
RateLimit
Wat er over is van elke limiet in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limiet van de strengste regel in RateLimit-Policy (die met de minste resterende requests).
X-RateLimit-Remaining
Resterende requests onder de strengste limiet.
X-RateLimit-Reset
Seconden tot de strengste limiet wordt teruggezet.

application/json

Object: Error

404Het object bestaat niet of is niet voor jou beschikbaar. De API bevestigt niet dat een afgeschermd object bestaat.

Responseheaders

RateLimit-Policy
Geldende limieten, in het formaat van het IETF-concept draft-ietf-httpapi-ratelimit-headers: items gescheiden door komma’s, "<name>";q=<quota>;w=<window in seconds>. key is de requestsnelheid van de API-sleutel (het quotum is de piek, het venster de tijd om die volledig aan te vullen; voor een sessie is het user, zonder authenticatiegegevens ip); minute, day en month zijn de quota van de organisatie voor de kalenderminuut, -dag en -maand in UTC.
RateLimit
Wat er over is van elke limiet in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limiet van de strengste regel in RateLimit-Policy (die met de minste resterende requests).
X-RateLimit-Remaining
Resterende requests onder de strengste limiet.
X-RateLimit-Reset
Seconden tot de strengste limiet wordt teruggezet.

application/json

Object: Error

409De toestand van het object staat de actie niet toe, bijvoorbeeld een duplicaat, een lopende indexering of een job die al is verwerkt.

Responseheaders

RateLimit-Policy
Geldende limieten, in het formaat van het IETF-concept draft-ietf-httpapi-ratelimit-headers: items gescheiden door komma’s, "<name>";q=<quota>;w=<window in seconds>. key is de requestsnelheid van de API-sleutel (het quotum is de piek, het venster de tijd om die volledig aan te vullen; voor een sessie is het user, zonder authenticatiegegevens ip); minute, day en month zijn de quota van de organisatie voor de kalenderminuut, -dag en -maand in UTC.
RateLimit
Wat er over is van elke limiet in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limiet van de strengste regel in RateLimit-Policy (die met de minste resterende requests).
X-RateLimit-Remaining
Resterende requests onder de strengste limiet.
X-RateLimit-Reset
Seconden tot de strengste limiet wordt teruggezet.

application/json

Object: Error

410Het object bestond, maar is niet meer beschikbaar: de link is al gebruikt of verlopen, of het bestand is aan het einde van de bewaartermijn verwijderd.

Responseheaders

RateLimit-Policy
Geldende limieten, in het formaat van het IETF-concept draft-ietf-httpapi-ratelimit-headers: items gescheiden door komma’s, "<name>";q=<quota>;w=<window in seconds>. key is de requestsnelheid van de API-sleutel (het quotum is de piek, het venster de tijd om die volledig aan te vullen; voor een sessie is het user, zonder authenticatiegegevens ip); minute, day en month zijn de quota van de organisatie voor de kalenderminuut, -dag en -maand in UTC.
RateLimit
Wat er over is van elke limiet in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limiet van de strengste regel in RateLimit-Policy (die met de minste resterende requests).
X-RateLimit-Remaining
Resterende requests onder de strengste limiet.
X-RateLimit-Reset
Seconden tot de strengste limiet wordt teruggezet.

application/json

Object: Error

413De request-body overschrijdt de toegestane grootte.

Responseheaders

RateLimit-Policy
Geldende limieten, in het formaat van het IETF-concept draft-ietf-httpapi-ratelimit-headers: items gescheiden door komma’s, "<name>";q=<quota>;w=<window in seconds>. key is de requestsnelheid van de API-sleutel (het quotum is de piek, het venster de tijd om die volledig aan te vullen; voor een sessie is het user, zonder authenticatiegegevens ip); minute, day en month zijn de quota van de organisatie voor de kalenderminuut, -dag en -maand in UTC.
RateLimit
Wat er over is van elke limiet in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limiet van de strengste regel in RateLimit-Policy (die met de minste resterende requests).
X-RateLimit-Remaining
Resterende requests onder de strengste limiet.
X-RateLimit-Reset
Seconden tot de strengste limiet wordt teruggezet.

application/json

Object: Error

415Het bestandsformaat wordt niet ondersteund.

Responseheaders

RateLimit-Policy
Geldende limieten, in het formaat van het IETF-concept draft-ietf-httpapi-ratelimit-headers: items gescheiden door komma’s, "<name>";q=<quota>;w=<window in seconds>. key is de requestsnelheid van de API-sleutel (het quotum is de piek, het venster de tijd om die volledig aan te vullen; voor een sessie is het user, zonder authenticatiegegevens ip); minute, day en month zijn de quota van de organisatie voor de kalenderminuut, -dag en -maand in UTC.
RateLimit
Wat er over is van elke limiet in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limiet van de strengste regel in RateLimit-Policy (die met de minste resterende requests).
X-RateLimit-Remaining
Resterende requests onder de strengste limiet.
X-RateLimit-Reset
Seconden tot de strengste limiet wordt teruggezet.

application/json

Object: Error

422Validatiefout: de body of de parameters komen niet overeen met het schema (`detail` is een lijst met validatiefouten), of een parameterwaarde valt buiten het bereik (`detail` is een melding).

Responseheaders

RateLimit-Policy
Geldende limieten, in het formaat van het IETF-concept draft-ietf-httpapi-ratelimit-headers: items gescheiden door komma’s, "<name>";q=<quota>;w=<window in seconds>. key is de requestsnelheid van de API-sleutel (het quotum is de piek, het venster de tijd om die volledig aan te vullen; voor een sessie is het user, zonder authenticatiegegevens ip); minute, day en month zijn de quota van de organisatie voor de kalenderminuut, -dag en -maand in UTC.
RateLimit
Wat er over is van elke limiet in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limiet van de strengste regel in RateLimit-Policy (die met de minste resterende requests).
X-RateLimit-Remaining
Resterende requests onder de strengste limiet.
X-RateLimit-Reset
Seconden tot de strengste limiet wordt teruggezet.

application/json

Object: Error

429Te veel requests (`api.rate_limited`), het quotum van de organisatie voor de minuut, dag of maand is op (`api.quota_exceeded`; `error.details` bevat `quota`, `limit` en `reset_at`), de limiet van de organisatie is bereikt, of de antwoorddienst is bezet (`answers.engine_busy`). Wacht de tijd af die in de header `Retry-After` staat.

Responseheaders

Retry-After
Aantal seconden dat je moet wachten voordat je het request opnieuw probeert.
RateLimit-Policy
Geldende limieten, in het formaat van het IETF-concept draft-ietf-httpapi-ratelimit-headers: items gescheiden door komma’s, "<name>";q=<quota>;w=<window in seconds>. key is de requestsnelheid van de API-sleutel (het quotum is de piek, het venster de tijd om die volledig aan te vullen; voor een sessie is het user, zonder authenticatiegegevens ip); minute, day en month zijn de quota van de organisatie voor de kalenderminuut, -dag en -maand in UTC.
RateLimit
Wat er over is van elke limiet in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limiet van de strengste regel in RateLimit-Policy (die met de minste resterende requests).
X-RateLimit-Remaining
Resterende requests onder de strengste limiet.
X-RateLimit-Reset
Seconden tot de strengste limiet wordt teruggezet.

application/json

Object: Error

503Een dienst waarvan dit request afhangt, is tijdelijk niet beschikbaar. Probeer het later opnieuw.

Responseheaders

RateLimit-Policy
Geldende limieten, in het formaat van het IETF-concept draft-ietf-httpapi-ratelimit-headers: items gescheiden door komma’s, "<name>";q=<quota>;w=<window in seconds>. key is de requestsnelheid van de API-sleutel (het quotum is de piek, het venster de tijd om die volledig aan te vullen; voor een sessie is het user, zonder authenticatiegegevens ip); minute, day en month zijn de quota van de organisatie voor de kalenderminuut, -dag en -maand in UTC.
RateLimit
Wat er over is van elke limiet in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limiet van de strengste regel in RateLimit-Policy (die met de minste resterende requests).
X-RateLimit-Remaining
Resterende requests onder de strengste limiet.
X-RateLimit-Reset
Seconden tot de strengste limiet wordt teruggezet.

application/json

Object: Error

Foutcodes

Codes die dit endpoint in error.code kan teruggeven, naast de algemene codes van elk request.

Veilig opnieuw proberen

Stuur bij elke POST en PATCH een header Idempotency-Key mee (bijvoorbeeld een UUID). Een nieuwe poging met dezelfde sleutel binnen 24 uur geeft de opgeslagen response terug, zonder het request opnieuw uit te voeren.

Snelheidslimieten

Responses bevatten de headers RateLimit en RateLimit-Policy en de eerdere X-RateLimit-Limit, X-RateLimit-Remaining en X-RateLimit-Reset. Een response met status 429 bevat Retry-After in seconden: wacht en probeer het daarna opnieuw.

← cards · API-referentie

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"

Uitproberen

API-sleutel

De sleutel blijft in het geheugen van dit tabblad en wordt alleen naar https://api.sursa.com gestuurd.

Requests werken met de echte gegevens van je organisatie.

Idempotency-Key header

X-View-As header

Idempotency-Key

Is dit veld leeg, dan wordt voor elk request een nieuwe sleutel gegenereerd.

Request-body (JSON)