POST/v1/cards/archive

Upload et arkiv med dokumenter

upload_card_archive

Send et ZIP-arkiv i feltet file i en formular af typen multipart/form-data. Hver understøttet fil i arkivet bliver et separat dokument som ved enkeltuploads (POST /v1/cards). ASiC-signaturcontainere (.asice, .sce, .bdoc, .asics) er også arkiver: deres datafiler bliver dokumenter, META-INF/ springes over, og signaturen valideres ikke. Formularens felter er de samme som ved upload af en fil (samling, tags, ejer, kategori, følsomhed), uden forhåndsvisning.

Arkivet kontrolleres efter signatur (et omdøbt Office-dokument tæller ikke som et arkiv og returnerer 415 files.type_mismatch), installationens grænse for upload gælder, og antivirusscanningen omfatter hele arkivet.

Indholdsfortegnelsen kontrolleres synkront. Svaret indeholder planen (hvilke filer der bliver dokumenter, hvilke der springes over og hvorfor) og jobbet til udpakning af arkivet (job_id, batch_id). Jobbet åbner underarkiver (som standard op til 3 niveauer), kontrollerer hvert dokument efter signatur og antivirus og sætter det i kø til almindelig indeksering med samme batch_id (dokumenternes fremdrift: GET /v1/jobs?batch=). Resultatet kan hentes med GET /v1/archives/{job_id}.

Grænser (installationens standarder): op til 1000 filer i hele træet (flere returnerer 413 cards.archive_too_many_files), op til 2048 MB udpakket (mere returnerer 413 cards.archive_too_large) og ikke mere end organisationens resterende lagerplads i prisplanen (402 limits.storage), grænsen for upload pr. fil for hver fil i arkivet og et komprimeringsforhold på højst 100:1 pr. post. Poster med »..«, en absolut sti eller et drevbogstav, symbolske links, krypterede poster og formater, der ikke understøttes, springes over med en begrundelse (skipped[].reason). Systemfiler fra styresystemet, mapper og tomme filer springes over uden besked (ignored). Navne, der ikke er i UTF-8, læses som cp866 eller cp1251. En fil, der ikke er en ZIP, returnerer 400 cards.archive_invalid, et fuldt krypteret arkiv returnerer 400 cards.archive_encrypted, og et arkiv uden ét eneste dokument returnerer 400 cards.archive_empty.

Hvert dokument husker sit arkiv: CardVersion.archive og Card.source_archive (kortet viser arkivet for sin aktuelle version).

I stedet for formularen kan du sende en brødtekst af typen application/json (ArchiveUploadFromUpload, fra 1.62.0): arkivet er en færdig multipart-upload upload_id (formålet archive), felterne er de samme som i formularen, og tags er en liste af strenge. Arkivet blev allerede kontrolleret ved complete, og størrelsesgrænsen er grænsen for multipart-upload i stedet for grænsen for upload i én anmodning. Uploaden bruges én gang, i den samme transaktion, som sætter jobbet til udpakning af arkivet i kø; fejlkoderne for uploads er de samme som for POST /v1/cards.

Autentificering

Send en API-nøgle i headeren Authorization: Authorization: Bearer <nøgle>.

Headerparametre

Idempotency-Keystring
Nøgle til et sikkert nyt forsøg på en skrivning: 1 til 255 printbare ASCII-tegn; en UUID v4 pr. logisk operation anbefales. Et nyt forsøg med samme nøgle inden for 24 timer udfører ikke operationen igen: det returnerer det gemte svar (status, headere og brødtekst) med headeren Idempotency-Replayed: true. Samme nøgle med en anden metode, sti, Content-Type eller brødtekst returnerer 409 api.idempotency_mismatch; mens den første anmodning stadig kører, 409 api.idempotency_in_progress med Retry-After: 1. Efter et 5xx- eller 429-svar frigives nøglen, og et nyt forsøg udfører operationen igen. Nøglen gælder for organisationen og den kaldende part (API-nøgle, bruger eller nøgle til en brugerdefineret kilde).
length ≥ 1, length ≤ 255
X-View-Asstring
Kun for API-nøgler med rollen admin. Udfører anmodningen som dataprofilen <profile>[:viewer|verifier|editor], fx employee:viewer. Installationsnøglen kan ikke bruge denne header (403).

Cookieparametre

kb_view_asstring
Cookie for tilstanden »View as« i en session. POST /auth/view-as sætter den, og DELETE /auth/view-as fjerner den.

Anmodningens brødtekst

multipart/form-data

Objekt: ArchiveUploadForm

filestring (application/zip)påkrævet
collectionstring
Standard: "default"
tagsstring
Standard: ""
forceboolean
Standard: false
owner_idinteger | null
verify_interval_daysinteger | null
categorystring | null
sensitiveboolean | null
folder_idstring | null
Mappe i collection, som alle arkivets dokumenter skal placeres i. En mappe i en anden samling returnerer 400 folders.card_collection_mismatch, en manglende mappe returnerer 404 folders.not_found, og uden tilladelsen COLLECTION_EDIT_CARDS på mappen returneres 403 authz.forbidden. Kontrollen køres, før arkivet gemmes. Dubletter af filer, der allerede er uploadet, flyttes ikke til mappen.
length ≤ 64
collection_idinteger | null
Samling efter id. Angives collection også, har collection_id forrang. En samling, der ikke findes i organisationen eller ikke er synlig, returnerer 404 collections.not_found.

application/json

Objekt: ArchiveUploadFromUpload

upload_idstringpåkrævet
En færdig upload (ready) med formålet archive; den bruges én gang.
collectionstring
Standard: "default"
collection_idinteger | null
Samling efter id. Sendes collection også, har collection_id forrang. En samling, der ikke findes i organisationen, ikke er synlig eller ligger uden for nøglens samlinger, returnerer 404 collections.not_found.
tagsarray of string
items ≤ 30
forceboolean
Standard: false
owner_idinteger | null
verify_interval_daysinteger | null
categorystring | null
sensitiveboolean | null
folder_idstring | null
length ≤ 64

Svar

200Plan for udpakning og job

Svarets headere

RateLimit-Policy
Gældende grænser i formatet fra IETF-udkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerede elementer "<name>";q=<quota>;w=<window in seconds>. key er API-nøglens anmodningshastighed (kvoten er burst, vinduet er tiden til fuld genopfyldning; for en session er det user, uden legitimationsoplysninger ip); minute, day og month er organisationens kvoter for kalenderminuttet, kalenderdagen og kalendermåneden i UTC.
RateLimit
Hvad der er tilbage af hver grænse i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Grænsen for den strengeste post i RateLimit-Policy (den med færrest resterende anmodninger).
X-RateLimit-Remaining
Resterende anmodninger under den strengeste grænse.
X-RateLimit-Reset
Sekunder, til den strengeste grænse nulstilles.
Idempotency-Replayed
true betyder, at svaret blev afspillet igen fra det gemte svar for denne Idempotency-Key: operationen blev ikke udført igen.

application/json

Objekt: ArchiveUploadResult

job_idintegerpåkrævet
batch_idstringpåkrævet
Batch af indekseringsjob for arkivets dokumenter (GET /v1/jobs?batch=).
statusstringpåkrævet
Tilladte værdier: queued
archiveArchiveInfopåkrævet
plannedarray of stringpåkrævet
Stier til filerne på alle niveauer, der bliver til dokumenter, herunder filer i underarkiver (b.zip/c.pdf).
documentsintegerpåkrævet
Antal dokumenter på alle niveauer, herunder filer i underarkiver. Resultatet af udpakningen giver samme antal: oprettede + dubletter + afvist af indholdskontrollen (ArchiveJob).
nested_archivesintegerpåkrævet
skippedarray of ArchiveSkippåkrævet
ignoredintegerpåkrævet
Systemposter (styresystemets filer, mapper, tomme filer, containersignaturer).

400Anmodningen er ugyldig: en parameterværdi eller objektets tilstand tillader ikke handlingen (`detail` er en meddelelse).

Svarets headere

RateLimit-Policy
Gældende grænser i formatet fra IETF-udkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerede elementer "<name>";q=<quota>;w=<window in seconds>. key er API-nøglens anmodningshastighed (kvoten er burst, vinduet er tiden til fuld genopfyldning; for en session er det user, uden legitimationsoplysninger ip); minute, day og month er organisationens kvoter for kalenderminuttet, kalenderdagen og kalendermåneden i UTC.
RateLimit
Hvad der er tilbage af hver grænse i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Grænsen for den strengeste post i RateLimit-Policy (den med færrest resterende anmodninger).
X-RateLimit-Remaining
Resterende anmodninger under den strengeste grænse.
X-RateLimit-Reset
Sekunder, til den strengeste grænse nulstilles.

application/json

Objekt: Error

401Der blev ikke sendt legitimationsoplysninger (hverken en sessionscookie eller en API-nøgle), eller nøglen blev ikke fundet.

Svarets headere

RateLimit-Policy
Gældende grænser i formatet fra IETF-udkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerede elementer "<name>";q=<quota>;w=<window in seconds>. key er API-nøglens anmodningshastighed (kvoten er burst, vinduet er tiden til fuld genopfyldning; for en session er det user, uden legitimationsoplysninger ip); minute, day og month er organisationens kvoter for kalenderminuttet, kalenderdagen og kalendermåneden i UTC.
RateLimit
Hvad der er tilbage af hver grænse i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Grænsen for den strengeste post i RateLimit-Policy (den med færrest resterende anmodninger).
X-RateLimit-Remaining
Resterende anmodninger under den strengeste grænse.
X-RateLimit-Reset
Sekunder, til den strengeste grænse nulstilles.

application/json

Objekt: Error

402Organisationen har nået en grænse i prisplanen (kort, lagerplads eller brugere). `error.details` indeholder `kind`, `limit` og `used`.

Svarets headere

RateLimit-Policy
Gældende grænser i formatet fra IETF-udkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerede elementer "<name>";q=<quota>;w=<window in seconds>. key er API-nøglens anmodningshastighed (kvoten er burst, vinduet er tiden til fuld genopfyldning; for en session er det user, uden legitimationsoplysninger ip); minute, day og month er organisationens kvoter for kalenderminuttet, kalenderdagen og kalendermåneden i UTC.
RateLimit
Hvad der er tilbage af hver grænse i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Grænsen for den strengeste post i RateLimit-Policy (den med færrest resterende anmodninger).
X-RateLimit-Remaining
Resterende anmodninger under den strengeste grænse.
X-RateLimit-Reset
Sekunder, til den strengeste grænse nulstilles.

application/json

Objekt: Error

403Handlingen er ikke tilladt: rollen er utilstrækkelig, der er ingen adgang til samlingen eller kortet, anmodningen kører i tilstanden »View as«, eller organisationen er suspenderet eller slettet (`detail` er et objekt med `code: org_suspended | org_deleted`).

Svarets headere

RateLimit-Policy
Gældende grænser i formatet fra IETF-udkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerede elementer "<name>";q=<quota>;w=<window in seconds>. key er API-nøglens anmodningshastighed (kvoten er burst, vinduet er tiden til fuld genopfyldning; for en session er det user, uden legitimationsoplysninger ip); minute, day og month er organisationens kvoter for kalenderminuttet, kalenderdagen og kalendermåneden i UTC.
RateLimit
Hvad der er tilbage af hver grænse i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Grænsen for den strengeste post i RateLimit-Policy (den med færrest resterende anmodninger).
X-RateLimit-Remaining
Resterende anmodninger under den strengeste grænse.
X-RateLimit-Reset
Sekunder, til den strengeste grænse nulstilles.

application/json

Objekt: Error

404Objektet findes ikke eller er ikke tilgængeligt for dig. API’et bekræfter ikke, at et begrænset objekt findes.

Svarets headere

RateLimit-Policy
Gældende grænser i formatet fra IETF-udkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerede elementer "<name>";q=<quota>;w=<window in seconds>. key er API-nøglens anmodningshastighed (kvoten er burst, vinduet er tiden til fuld genopfyldning; for en session er det user, uden legitimationsoplysninger ip); minute, day og month er organisationens kvoter for kalenderminuttet, kalenderdagen og kalendermåneden i UTC.
RateLimit
Hvad der er tilbage af hver grænse i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Grænsen for den strengeste post i RateLimit-Policy (den med færrest resterende anmodninger).
X-RateLimit-Remaining
Resterende anmodninger under den strengeste grænse.
X-RateLimit-Reset
Sekunder, til den strengeste grænse nulstilles.

application/json

Objekt: Error

409Objektets tilstand tillader ikke handlingen, fx en dublet, en igangværende indeksering eller et job, der allerede er behandlet.

Svarets headere

RateLimit-Policy
Gældende grænser i formatet fra IETF-udkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerede elementer "<name>";q=<quota>;w=<window in seconds>. key er API-nøglens anmodningshastighed (kvoten er burst, vinduet er tiden til fuld genopfyldning; for en session er det user, uden legitimationsoplysninger ip); minute, day og month er organisationens kvoter for kalenderminuttet, kalenderdagen og kalendermåneden i UTC.
RateLimit
Hvad der er tilbage af hver grænse i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Grænsen for den strengeste post i RateLimit-Policy (den med færrest resterende anmodninger).
X-RateLimit-Remaining
Resterende anmodninger under den strengeste grænse.
X-RateLimit-Reset
Sekunder, til den strengeste grænse nulstilles.

application/json

Objekt: Error

410Objektet fandtes, men er ikke længere tilgængeligt: linket er brugt eller udløbet, eller filen blev slettet ved udgangen af dens opbevaringsperiode.

Svarets headere

RateLimit-Policy
Gældende grænser i formatet fra IETF-udkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerede elementer "<name>";q=<quota>;w=<window in seconds>. key er API-nøglens anmodningshastighed (kvoten er burst, vinduet er tiden til fuld genopfyldning; for en session er det user, uden legitimationsoplysninger ip); minute, day og month er organisationens kvoter for kalenderminuttet, kalenderdagen og kalendermåneden i UTC.
RateLimit
Hvad der er tilbage af hver grænse i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Grænsen for den strengeste post i RateLimit-Policy (den med færrest resterende anmodninger).
X-RateLimit-Remaining
Resterende anmodninger under den strengeste grænse.
X-RateLimit-Reset
Sekunder, til den strengeste grænse nulstilles.

application/json

Objekt: Error

413Anmodningens brødtekst overskrider den tilladte størrelse.

Svarets headere

RateLimit-Policy
Gældende grænser i formatet fra IETF-udkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerede elementer "<name>";q=<quota>;w=<window in seconds>. key er API-nøglens anmodningshastighed (kvoten er burst, vinduet er tiden til fuld genopfyldning; for en session er det user, uden legitimationsoplysninger ip); minute, day og month er organisationens kvoter for kalenderminuttet, kalenderdagen og kalendermåneden i UTC.
RateLimit
Hvad der er tilbage af hver grænse i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Grænsen for den strengeste post i RateLimit-Policy (den med færrest resterende anmodninger).
X-RateLimit-Remaining
Resterende anmodninger under den strengeste grænse.
X-RateLimit-Reset
Sekunder, til den strengeste grænse nulstilles.

application/json

Objekt: Error

415Filformatet understøttes ikke.

Svarets headere

RateLimit-Policy
Gældende grænser i formatet fra IETF-udkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerede elementer "<name>";q=<quota>;w=<window in seconds>. key er API-nøglens anmodningshastighed (kvoten er burst, vinduet er tiden til fuld genopfyldning; for en session er det user, uden legitimationsoplysninger ip); minute, day og month er organisationens kvoter for kalenderminuttet, kalenderdagen og kalendermåneden i UTC.
RateLimit
Hvad der er tilbage af hver grænse i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Grænsen for den strengeste post i RateLimit-Policy (den med færrest resterende anmodninger).
X-RateLimit-Remaining
Resterende anmodninger under den strengeste grænse.
X-RateLimit-Reset
Sekunder, til den strengeste grænse nulstilles.

application/json

Objekt: Error

422Valideringsfejl: brødteksten eller parametrene svarer ikke til skemaet (`detail` er en liste over valideringsfejl), eller en parameterværdi ligger uden for det tilladte interval (`detail` er en meddelelse).

Svarets headere

RateLimit-Policy
Gældende grænser i formatet fra IETF-udkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerede elementer "<name>";q=<quota>;w=<window in seconds>. key er API-nøglens anmodningshastighed (kvoten er burst, vinduet er tiden til fuld genopfyldning; for en session er det user, uden legitimationsoplysninger ip); minute, day og month er organisationens kvoter for kalenderminuttet, kalenderdagen og kalendermåneden i UTC.
RateLimit
Hvad der er tilbage af hver grænse i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Grænsen for den strengeste post i RateLimit-Policy (den med færrest resterende anmodninger).
X-RateLimit-Remaining
Resterende anmodninger under den strengeste grænse.
X-RateLimit-Reset
Sekunder, til den strengeste grænse nulstilles.

application/json

Objekt: Error

429For mange anmodninger (`api.rate_limited`), organisationens kvote for minuttet, dagen eller måneden er brugt op (`api.quota_exceeded`; `error.details` indeholder `quota`, `limit` og `reset_at`), organisationens grænse er nået, eller svartjenesten er optaget (`answers.engine_busy`). Vent den tid, der står i headeren `Retry-After`.

Svarets headere

Retry-After
Antal sekunder, du skal vente, før du prøver anmodningen igen.
RateLimit-Policy
Gældende grænser i formatet fra IETF-udkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerede elementer "<name>";q=<quota>;w=<window in seconds>. key er API-nøglens anmodningshastighed (kvoten er burst, vinduet er tiden til fuld genopfyldning; for en session er det user, uden legitimationsoplysninger ip); minute, day og month er organisationens kvoter for kalenderminuttet, kalenderdagen og kalendermåneden i UTC.
RateLimit
Hvad der er tilbage af hver grænse i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Grænsen for den strengeste post i RateLimit-Policy (den med færrest resterende anmodninger).
X-RateLimit-Remaining
Resterende anmodninger under den strengeste grænse.
X-RateLimit-Reset
Sekunder, til den strengeste grænse nulstilles.

application/json

Objekt: Error

503En tjeneste, som denne anmodning afhænger af, er midlertidigt utilgængelig. Prøv igen senere.

Svarets headere

RateLimit-Policy
Gældende grænser i formatet fra IETF-udkastet draft-ietf-httpapi-ratelimit-headers: kommaseparerede elementer "<name>";q=<quota>;w=<window in seconds>. key er API-nøglens anmodningshastighed (kvoten er burst, vinduet er tiden til fuld genopfyldning; for en session er det user, uden legitimationsoplysninger ip); minute, day og month er organisationens kvoter for kalenderminuttet, kalenderdagen og kalendermåneden i UTC.
RateLimit
Hvad der er tilbage af hver grænse i RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Grænsen for den strengeste post i RateLimit-Policy (den med færrest resterende anmodninger).
X-RateLimit-Remaining
Resterende anmodninger under den strengeste grænse.
X-RateLimit-Reset
Sekunder, til den strengeste grænse nulstilles.

application/json

Objekt: Error

Fejlkoder

Koder, som denne operation kan returnere i error.code, ud over de generelle koder for alle anmodninger.

Sikre nye forsøg

Send en Idempotency-Key-header (fx et UUID) med hver POST og PATCH. Et nyt forsøg med den samme nøgle inden for 24 timer returnerer det gemte svar i stedet for at køre anmodningen igen.

Hastighedsgrænser

Svarene har headerne RateLimit og RateLimit-Policy samt de tidligere X-RateLimit-Limit, X-RateLimit-Remaining og X-RateLimit-Reset. Et 429-svar har Retry-After i sekunder: Vent, og forsøg igen.

← cards · API-reference

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"

Afprøv

API-nøgle

Nøglen gemmes kun i denne fanes hukommelse og sendes kun til https://api.sursa.com.

Anmodningerne udføres på din organisations rigtige data.

Idempotency-Key header

X-View-As header

Idempotency-Key

Er feltet tomt, genereres en ny nøgle for hver anmodning.

Anmodningens brødtekst (JSON)