POST/v1/cards

Upload en fil som et kort

upload_card

Send dokumentet i feltet file i en formular af typen multipart/form-data. Før filen gemmes, kontrollerer Sursa, at filnavnets endelse, delens angivne Content-Type og indholdets signatur stemmer overens:
- PDF;
- DOCX, XLSX, XLSM, PPTX: en ZIP med den angivne hoveddokumenttype;
- ODS: en ZIP med en post mimetype;
- XLS: et OLE2-dokument med en stream til projektmappen;
- TXT, MD, CSV, TSV, HTML, AsciiDoc, EML: tekst uden nulbytes i UTF-8 eller en enkeltbyte-tegnkodning og, for e-mail, headere i starten;
- PNG, JPEG, TIFF, WebP, BMP: efter signatur.

Manglende overensstemmelse returnerer 415 files.type_mismatch; en endelse uden for listen over formater returnerer 415 cards.unsupported_format. En fil, der er større end installationens grænse for upload eller organisationens samlede lagerplads i prisplanen, returnerer 413 files.too_large. Når antivirusscanning er slået til, returnerer en inficeret fil 422 files.infected, og er scanneren utilgængelig under politikken »reject« (afvis), returnerer anmodningen 503 files.scan_unavailable. Hver afvisning skrives i revisionsloggen som file.rejected.

I stedet for formularen kan du sende en brødtekst af typen application/json (CardUploadFromUpload, fra 1.62.0): filen er en færdig multipart-upload upload_id (POST /v1/uploads med formålet card_file), felterne er de samme som i formularen, og tags er en liste af strenge. Uploadens fil blev allerede kontrolleret ved complete (format, antivirus), 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 opretter kortet: en upload, der allerede er brugt, returnerer 409 uploads.already_used, en, der endnu ikke er klar, returnerer 409 uploads.not_ready, en afvist upload returnerer 422 uploads.rejected, en med et andet formål returnerer 422 uploads.purpose_mismatch, en udløbet returnerer 410 uploads.expired, og en anden kaldende parts upload eller en ukendt upload returnerer 404 uploads.not_found. Mislykkes kontrollerne af kortet (samling, kategori, grænser), bruges uploaden ikke op.

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: CardUploadForm

filestring (application/octet-stream)påkrævet
collectionstring
Standard: "default"
tagsstring
Standard: ""
forceboolean
Standard: false
owner_idinteger | null
verify_interval_daysinteger | null
categorystring | null
sensitiveboolean | null
asyncboolean
Standard: false
reviewboolean
Standard: false
folder_idstring | null
Mappe i collection, som det nye kort 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 filen gemmes. En dublet af en fil, der allerede er uploadet (skipped), 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.
external_idstring | null
external_id for det nye kort. Med det oprettes kortet, også selvom samlingen allerede har den samme fil. Bruger et andet kort i organisationen det, returnerer anmodningen 409 cards.external_id_taken. Brug PUT /v1/cards-by-external-id/{external_id} for at oprette eller erstatte et kort efter external_id.
length ≤ 512
metadatastring | null
metadata for det nye kort: et JSON-objekt som værdien af formularfeltet. Reglerne er de samme som for MetadataPatch.

application/json

Objekt: CardUploadFromUpload

upload_idstringpåkrævet
En færdig upload (ready) med formålet card_file; 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
asyncboolean
Standard: false
reviewboolean
Standard: false
folder_idstring | null
length ≤ 64
external_idstring | null
Det nye korts external_id som i formularfeltet. Med det oprettes kortet, selv om samlingen allerede har den samme fil. Bruger et andet kort i organisationen det, returnerer anmodningen 409 cards.external_id_taken.
length ≤ 512
metadataMetadataPatch

Svar

200`queued` (asynkront), `skipped` (dublet), `ready` eller `error` (synkront).

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: UploadResult

statusstringpåkrævet
Tilladte værdier: queuedskippedreadyerror
job_idinteger
jobJob
cardCard | null
duplicatetrue
card_idstring | null
reasonstring
unchanged eller an identical file is already indexed (en identisk fil er allerede indekseret).
tablesinteger
timingsobject
Felter
- total_snumber
errorstring

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' \
  -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)