POST/v1/cards

Učitavanje datoteke kao kartice

upload_card

Pošaljite dokument u polju file obrasca multipart/form-data. Prije spremanja Sursa provjerava podudaraju li se nastavak naziva datoteke, deklarirani Content-Type dijela i potpis sadržaja:
- PDF;
- DOCX, XLSX, XLSM, PPTX: ZIP s deklariranom vrstom glavnog dokumenta;
- ODS: ZIP sa stavkom mimetype;
- XLS: OLE2 dokument s tokom radne knjige;
- TXT, MD, CSV, TSV, HTML, AsciiDoc, EML: tekst bez nultih bajtova u UTF-8 ili u jednobajtnom kodiranju, a za e-poštu – zaglavlja na početku;
- PNG, JPEG, TIFF, WebP, BMP: prema potpisu.

Nepodudaranje vraća 415 files.type_mismatch; nastavak izvan popisa formata vraća 415 cards.unsupported_format. Datoteka veća od ograničenja učitavanja instalacije ili od ukupne pohrane organizacije prema njezinu planu vraća 413 files.too_large. Kad je uključena antivirusna provjera, zaražena datoteka vraća 422 files.infected, a ako antivirusni skener nije dostupan uz pravilo „reject”, zahtjev vraća 503 files.scan_unavailable. Svako odbijanje upisuje se u revizijski zapisnik kao file.rejected.

Umjesto obrasca možete poslati tijelo application/json (CardUploadFromUpload, od verzije 1.62.0): datoteka je dovršeno učitavanje u dijelovima upload_id (POST /v1/uploads s namjenom card_file), polja su ista kao u obrascu, a tags je popis nizova. Datoteka učitavanja već je provjerena pri complete (format, antivirusna provjera), a ograničenje veličine je ograničenje za učitavanje u dijelovima umjesto ograničenja za učitavanje jednim zahtjevom. Učitavanje se koristi jednom, u istoj transakciji u kojoj se stvara kartica: već iskorišteno učitavanje vraća 409 uploads.already_used, ono koje još nije spremno – 409 uploads.not_ready, odbijeno – 422 uploads.rejected, učitavanje s drugom namjenom – 422 uploads.purpose_mismatch, isteklo – 410 uploads.expired, a tuđe ili nepoznato učitavanje – 404 uploads.not_found. Ako provjere kartice ne uspiju (zbirka, kategorija, ograničenja), učitavanje se ne troši.

Autentifikacija

Pošaljite API ključ u zaglavlju Authorization: Authorization: Bearer <ključ>.

Parametri zaglavlja

Idempotency-Keystring
Ključ za siguran ponovni pokušaj upisa: od 1 do 255 ispisivih ASCII znakova; preporučuje se UUID v4 po logičkoj operaciji. Ponovni pokušaj s istim ključem unutar 24 sata ne izvodi operaciju ponovno: vraća spremljeni odgovor (status, zaglavlja i tijelo) sa zaglavljem Idempotency-Replayed: true. Isti ključ s drugom metodom, putanjom, Content-Type ili tijelom vraća 409 api.idempotency_mismatch; dok se prvi zahtjev još izvodi – 409 api.idempotency_in_progress s Retry-After: 1. Nakon odgovora 5xx ili 429 ključ se oslobađa i ponovni pokušaj ponovno izvodi operaciju. Ključ vrijedi u okviru organizacije i pozivatelja (API ključ, korisnik ili ključ vlastitog izvora).
length ≥ 1, length ≤ 255
X-View-Asstring
Samo za API ključeve s ulogom admin. Izvodi zahtjev kao podatkovni profil <profile>[:viewer|verifier|editor], na primjer employee:viewer. Ključ instalacije ne može koristiti ovo zaglavlje (403).

Parametri kolačića

kb_view_asstring
Kolačić načina „View as” za sesiju. Postavlja ga POST /auth/view-as, a briše DELETE /auth/view-as.

Tijelo zahtjeva

multipart/form-data

Objekt: CardUploadForm

filestring (application/octet-stream)obavezno
collectionstring
Zadano: "default"
tagsstring
Zadano: ""
forceboolean
Zadano: false
owner_idinteger | null
verify_interval_daysinteger | null
categorystring | null
sensitiveboolean | null
asyncboolean
Zadano: false
reviewboolean
Zadano: false
folder_idstring | null
Mapa zbirke collection u koju se stavlja nova kartica. Mapa druge zbirke vraća 400 folders.card_collection_mismatch, nepostojeća mapa vraća 404 folders.not_found, a bez dopuštenja COLLECTION_EDIT_CARDS na mapi vraća se 403 authz.forbidden. Provjera se izvodi prije spremanja datoteke. Duplikat već učitane datoteke (skipped) ne premješta se u mapu.
length ≤ 64
collection_idinteger | null
Zbirka prema ID-ju. Ako je proslijeđen i collection, prednost ima collection_id. Zbirka koja ne postoji u organizaciji ili nije vidljiva vraća 404 collections.not_found.
external_idstring | null
external_id nove kartice. Uz njega se kartica stvara čak i ako zbirka već ima istu datoteku. Ako ga koristi druga kartica organizacije, zahtjev vraća 409 cards.external_id_taken. Za stvaranje ili zamjenu kartice prema external_id koristite PUT /v1/cards-by-external-id/{external_id}.
length ≤ 512
metadatastring | null
metadata nove kartice: JSON objekt kao vrijednost polja obrasca. Vrijede pravila za MetadataPatch.

application/json

Objekt: CardUploadFromUpload

upload_idstringobavezno
Spremno učitavanje (ready) s namjenom card_file; koristi se jednom.
collectionstring
Zadano: "default"
collection_idinteger | null
Zbirka prema ID-ju. Ako je proslijeđen i collection, prednost ima collection_id. Zbirka koja ne postoji u organizaciji, nije vidljiva ili je izvan zbirki ključa vraća 404 collections.not_found.
tagsarray of string
items ≤ 30
forceboolean
Zadano: false
owner_idinteger | null
verify_interval_daysinteger | null
categorystring | null
sensitiveboolean | null
asyncboolean
Zadano: false
reviewboolean
Zadano: false
folder_idstring | null
length ≤ 64
external_idstring | null
external_id nove kartice, kao u polju obrasca. Uz njega se kartica stvara čak i ako zbirka već ima istu datoteku. Ako ga koristi neka druga kartica organizacije, zahtjev vraća 409 cards.external_id_taken.
length ≤ 512
metadataMetadataPatch

Odgovori

200`queued` (asinkrono), `skipped` (duplikat), `ready` ili `error` (sinkrono).

Zaglavlja odgovora

RateLimit-Policy
Ograničenja na snazi, u formatu IETF nacrta draft-ietf-httpapi-ratelimit-headers: stavke odvojene zarezima "<name>";q=<quota>;w=<window in seconds>. key je učestalost zahtjeva API ključa (kvota je nalet, prozor je vrijeme do njegova potpunog obnavljanja; za sesiju je to user, bez vjerodajnica ip); minute, day i month su kvote organizacije za kalendarsku minutu, dan i mjesec po UTC-u.
RateLimit
Što je preostalo od svakog ograničenja u RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Ograničenje najstrože stavke u RateLimit-Policy (one s najmanje preostalih zahtjeva).
X-RateLimit-Remaining
Preostali zahtjevi u okviru najstrožeg ograničenja.
X-RateLimit-Reset
Broj sekundi do obnove najstrožeg ograničenja.
Idempotency-Replayed
true znači da je odgovor ponovljen iz spremljenog odgovora za ovaj Idempotency-Key: operacija se nije ponovno izvela.

application/json

Objekt: UploadResult

statusstringobavezno
Dopuštene vrijednosti: queuedskippedreadyerror
job_idinteger
jobJob
cardCard | null
duplicatetrue
card_idstring | null
reasonstring
unchanged ili an identical file is already indexed.
tablesinteger
timingsobject
Polja
- total_snumber
errorstring

400Zahtjev nije valjan: vrijednost parametra ili stanje objekta ne dopušta radnju (`detail` je poruka).

Zaglavlja odgovora

RateLimit-Policy
Ograničenja na snazi, u formatu IETF nacrta draft-ietf-httpapi-ratelimit-headers: stavke odvojene zarezima "<name>";q=<quota>;w=<window in seconds>. key je učestalost zahtjeva API ključa (kvota je nalet, prozor je vrijeme do njegova potpunog obnavljanja; za sesiju je to user, bez vjerodajnica ip); minute, day i month su kvote organizacije za kalendarsku minutu, dan i mjesec po UTC-u.
RateLimit
Što je preostalo od svakog ograničenja u RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Ograničenje najstrože stavke u RateLimit-Policy (one s najmanje preostalih zahtjeva).
X-RateLimit-Remaining
Preostali zahtjevi u okviru najstrožeg ograničenja.
X-RateLimit-Reset
Broj sekundi do obnove najstrožeg ograničenja.

application/json

Objekt: Error

401Vjerodajnice nisu poslane (ni kolačić sesije ni API ključ) ili ključ nije pronađen.

Zaglavlja odgovora

RateLimit-Policy
Ograničenja na snazi, u formatu IETF nacrta draft-ietf-httpapi-ratelimit-headers: stavke odvojene zarezima "<name>";q=<quota>;w=<window in seconds>. key je učestalost zahtjeva API ključa (kvota je nalet, prozor je vrijeme do njegova potpunog obnavljanja; za sesiju je to user, bez vjerodajnica ip); minute, day i month su kvote organizacije za kalendarsku minutu, dan i mjesec po UTC-u.
RateLimit
Što je preostalo od svakog ograničenja u RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Ograničenje najstrože stavke u RateLimit-Policy (one s najmanje preostalih zahtjeva).
X-RateLimit-Remaining
Preostali zahtjevi u okviru najstrožeg ograničenja.
X-RateLimit-Reset
Broj sekundi do obnove najstrožeg ograničenja.

application/json

Objekt: Error

402Organizacija je dosegla ograničenje plana (kartice, pohrana ili korisnici). `error.details` sadrži `kind`, `limit` i `used`.

Zaglavlja odgovora

RateLimit-Policy
Ograničenja na snazi, u formatu IETF nacrta draft-ietf-httpapi-ratelimit-headers: stavke odvojene zarezima "<name>";q=<quota>;w=<window in seconds>. key je učestalost zahtjeva API ključa (kvota je nalet, prozor je vrijeme do njegova potpunog obnavljanja; za sesiju je to user, bez vjerodajnica ip); minute, day i month su kvote organizacije za kalendarsku minutu, dan i mjesec po UTC-u.
RateLimit
Što je preostalo od svakog ograničenja u RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Ograničenje najstrože stavke u RateLimit-Policy (one s najmanje preostalih zahtjeva).
X-RateLimit-Remaining
Preostali zahtjevi u okviru najstrožeg ograničenja.
X-RateLimit-Reset
Broj sekundi do obnove najstrožeg ograničenja.

application/json

Objekt: Error

403Radnja nije dopuštena: uloga nije dovoljna, nema pristupa zbirci ili kartici, zahtjev se izvodi u načinu „View as” ili je organizacija suspendirana ili izbrisana (`detail` je objekt s `code: org_suspended | org_deleted`).

Zaglavlja odgovora

RateLimit-Policy
Ograničenja na snazi, u formatu IETF nacrta draft-ietf-httpapi-ratelimit-headers: stavke odvojene zarezima "<name>";q=<quota>;w=<window in seconds>. key je učestalost zahtjeva API ključa (kvota je nalet, prozor je vrijeme do njegova potpunog obnavljanja; za sesiju je to user, bez vjerodajnica ip); minute, day i month su kvote organizacije za kalendarsku minutu, dan i mjesec po UTC-u.
RateLimit
Što je preostalo od svakog ograničenja u RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Ograničenje najstrože stavke u RateLimit-Policy (one s najmanje preostalih zahtjeva).
X-RateLimit-Remaining
Preostali zahtjevi u okviru najstrožeg ograničenja.
X-RateLimit-Reset
Broj sekundi do obnove najstrožeg ograničenja.

application/json

Objekt: Error

404Objekt ne postoji ili vam nije dostupan. API ne potvrđuje postojanje ograničenog objekta.

Zaglavlja odgovora

RateLimit-Policy
Ograničenja na snazi, u formatu IETF nacrta draft-ietf-httpapi-ratelimit-headers: stavke odvojene zarezima "<name>";q=<quota>;w=<window in seconds>. key je učestalost zahtjeva API ključa (kvota je nalet, prozor je vrijeme do njegova potpunog obnavljanja; za sesiju je to user, bez vjerodajnica ip); minute, day i month su kvote organizacije za kalendarsku minutu, dan i mjesec po UTC-u.
RateLimit
Što je preostalo od svakog ograničenja u RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Ograničenje najstrože stavke u RateLimit-Policy (one s najmanje preostalih zahtjeva).
X-RateLimit-Remaining
Preostali zahtjevi u okviru najstrožeg ograničenja.
X-RateLimit-Reset
Broj sekundi do obnove najstrožeg ograničenja.

application/json

Objekt: Error

409Stanje objekta ne dopušta radnju, na primjer duplikat, indeksiranje u tijeku ili posao koji je već obrađen.

Zaglavlja odgovora

RateLimit-Policy
Ograničenja na snazi, u formatu IETF nacrta draft-ietf-httpapi-ratelimit-headers: stavke odvojene zarezima "<name>";q=<quota>;w=<window in seconds>. key je učestalost zahtjeva API ključa (kvota je nalet, prozor je vrijeme do njegova potpunog obnavljanja; za sesiju je to user, bez vjerodajnica ip); minute, day i month su kvote organizacije za kalendarsku minutu, dan i mjesec po UTC-u.
RateLimit
Što je preostalo od svakog ograničenja u RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Ograničenje najstrože stavke u RateLimit-Policy (one s najmanje preostalih zahtjeva).
X-RateLimit-Remaining
Preostali zahtjevi u okviru najstrožeg ograničenja.
X-RateLimit-Reset
Broj sekundi do obnove najstrožeg ograničenja.

application/json

Objekt: Error

410Objekt je postojao, ali više nije dostupan: poveznica je iskorištena ili je istekla, ili je datoteka izbrisana na kraju razdoblja čuvanja.

Zaglavlja odgovora

RateLimit-Policy
Ograničenja na snazi, u formatu IETF nacrta draft-ietf-httpapi-ratelimit-headers: stavke odvojene zarezima "<name>";q=<quota>;w=<window in seconds>. key je učestalost zahtjeva API ključa (kvota je nalet, prozor je vrijeme do njegova potpunog obnavljanja; za sesiju je to user, bez vjerodajnica ip); minute, day i month su kvote organizacije za kalendarsku minutu, dan i mjesec po UTC-u.
RateLimit
Što je preostalo od svakog ograničenja u RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Ograničenje najstrože stavke u RateLimit-Policy (one s najmanje preostalih zahtjeva).
X-RateLimit-Remaining
Preostali zahtjevi u okviru najstrožeg ograničenja.
X-RateLimit-Reset
Broj sekundi do obnove najstrožeg ograničenja.

application/json

Objekt: Error

413Tijelo zahtjeva premašuje dopuštenu veličinu.

Zaglavlja odgovora

RateLimit-Policy
Ograničenja na snazi, u formatu IETF nacrta draft-ietf-httpapi-ratelimit-headers: stavke odvojene zarezima "<name>";q=<quota>;w=<window in seconds>. key je učestalost zahtjeva API ključa (kvota je nalet, prozor je vrijeme do njegova potpunog obnavljanja; za sesiju je to user, bez vjerodajnica ip); minute, day i month su kvote organizacije za kalendarsku minutu, dan i mjesec po UTC-u.
RateLimit
Što je preostalo od svakog ograničenja u RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Ograničenje najstrože stavke u RateLimit-Policy (one s najmanje preostalih zahtjeva).
X-RateLimit-Remaining
Preostali zahtjevi u okviru najstrožeg ograničenja.
X-RateLimit-Reset
Broj sekundi do obnove najstrožeg ograničenja.

application/json

Objekt: Error

415Format datoteke nije podržan.

Zaglavlja odgovora

RateLimit-Policy
Ograničenja na snazi, u formatu IETF nacrta draft-ietf-httpapi-ratelimit-headers: stavke odvojene zarezima "<name>";q=<quota>;w=<window in seconds>. key je učestalost zahtjeva API ključa (kvota je nalet, prozor je vrijeme do njegova potpunog obnavljanja; za sesiju je to user, bez vjerodajnica ip); minute, day i month su kvote organizacije za kalendarsku minutu, dan i mjesec po UTC-u.
RateLimit
Što je preostalo od svakog ograničenja u RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Ograničenje najstrože stavke u RateLimit-Policy (one s najmanje preostalih zahtjeva).
X-RateLimit-Remaining
Preostali zahtjevi u okviru najstrožeg ograničenja.
X-RateLimit-Reset
Broj sekundi do obnove najstrožeg ograničenja.

application/json

Objekt: Error

422Pogreška provjere valjanosti: tijelo ili parametri ne odgovaraju shemi (`detail` je popis pogrešaka provjere valjanosti) ili je vrijednost parametra izvan raspona (`detail` je poruka).

Zaglavlja odgovora

RateLimit-Policy
Ograničenja na snazi, u formatu IETF nacrta draft-ietf-httpapi-ratelimit-headers: stavke odvojene zarezima "<name>";q=<quota>;w=<window in seconds>. key je učestalost zahtjeva API ključa (kvota je nalet, prozor je vrijeme do njegova potpunog obnavljanja; za sesiju je to user, bez vjerodajnica ip); minute, day i month su kvote organizacije za kalendarsku minutu, dan i mjesec po UTC-u.
RateLimit
Što je preostalo od svakog ograničenja u RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Ograničenje najstrože stavke u RateLimit-Policy (one s najmanje preostalih zahtjeva).
X-RateLimit-Remaining
Preostali zahtjevi u okviru najstrožeg ograničenja.
X-RateLimit-Reset
Broj sekundi do obnove najstrožeg ograničenja.

application/json

Objekt: Error

429Previše zahtjeva (`api.rate_limited`), kvota organizacije za minutu, dan ili mjesec je potrošena (`api.quota_exceeded`; `error.details` sadrži `quota`, `limit` i `reset_at`), dosegnuto je ograničenje organizacije ili je usluga odgovora zauzeta (`answers.engine_busy`). Pričekajte vrijeme navedeno u zaglavlju `Retry-After`.

Zaglavlja odgovora

Retry-After
Broj sekundi koje treba pričekati prije ponovnog pokušaja zahtjeva.
RateLimit-Policy
Ograničenja na snazi, u formatu IETF nacrta draft-ietf-httpapi-ratelimit-headers: stavke odvojene zarezima "<name>";q=<quota>;w=<window in seconds>. key je učestalost zahtjeva API ključa (kvota je nalet, prozor je vrijeme do njegova potpunog obnavljanja; za sesiju je to user, bez vjerodajnica ip); minute, day i month su kvote organizacije za kalendarsku minutu, dan i mjesec po UTC-u.
RateLimit
Što je preostalo od svakog ograničenja u RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Ograničenje najstrože stavke u RateLimit-Policy (one s najmanje preostalih zahtjeva).
X-RateLimit-Remaining
Preostali zahtjevi u okviru najstrožeg ograničenja.
X-RateLimit-Reset
Broj sekundi do obnove najstrožeg ograničenja.

application/json

Objekt: Error

503Usluga o kojoj ovaj zahtjev ovisi privremeno nije dostupna. Pokušajte ponovno kasnije.

Zaglavlja odgovora

RateLimit-Policy
Ograničenja na snazi, u formatu IETF nacrta draft-ietf-httpapi-ratelimit-headers: stavke odvojene zarezima "<name>";q=<quota>;w=<window in seconds>. key je učestalost zahtjeva API ključa (kvota je nalet, prozor je vrijeme do njegova potpunog obnavljanja; za sesiju je to user, bez vjerodajnica ip); minute, day i month su kvote organizacije za kalendarsku minutu, dan i mjesec po UTC-u.
RateLimit
Što je preostalo od svakog ograničenja u RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Ograničenje najstrože stavke u RateLimit-Policy (one s najmanje preostalih zahtjeva).
X-RateLimit-Remaining
Preostali zahtjevi u okviru najstrožeg ograničenja.
X-RateLimit-Reset
Broj sekundi do obnove najstrožeg ograničenja.

application/json

Objekt: Error

Kodovi pogrešaka

Kodovi koje ova operacija može vratiti u error.code, uz opće kodove svakog zahtjeva.

Sigurni ponovni pokušaji

Uz svaki POST i PATCH pošaljite zaglavlje Idempotency-Key (na primjer UUID). Ponovni pokušaj s istim ključem unutar 24 sata vraća spremljeni odgovor umjesto da ponovno izvrši zahtjev.

Ograničenja učestalosti

Odgovori sadrže zaglavlja RateLimit i RateLimit-Policy te ranija zaglavlja X-RateLimit-Limit, X-RateLimit-Remaining i X-RateLimit-Reset. Odgovor 429 sadrži zaglavlje Retry-After u sekundama: pričekajte i pokušajte ponovno.

← cards · Referenca API-ja

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"

Isprobajte

API ključ

Ključ ostaje u memoriji ove kartice preglednika i šalje se samo na https://api.sursa.com.

Zahtjevi djeluju na stvarne podatke vaše organizacije.

Idempotency-Key header

X-View-As header

Idempotency-Key

Ako je polje prazno, za svaki se zahtjev stvara novi ključ.

Tijelo zahtjeva (JSON)