POST/v1/cards

Nahrát soubor jako kartu

upload_card

Odešlete dokument v poli file formuláře multipart/form-data. Před uložením Sursa zkontroluje, že přípona názvu souboru, deklarovaný Content-Type části a signatura obsahu si odpovídají:
- PDF;
- DOCX, XLSX, XLSM, PPTX: ZIP s deklarovaným typem hlavního dokumentu;
- ODS: ZIP s položkou mimetype;
- XLS: dokument OLE2 se streamem sešitu;
- TXT, MD, CSV, TSV, HTML, AsciiDoc, EML: text bez nulových bajtů v UTF-8 nebo v jednobajtovém kódování, u e-mailu s hlavičkami na začátku;
- PNG, JPEG, TIFF, WebP, BMP: podle signatury.

Neshoda vrací 415 files.type_mismatch; přípona mimo seznam formátů vrací 415 cards.unsupported_format. Soubor větší než limit nahrávání instalace nebo než celkové úložiště organizace podle jejího tarifu vrací 413 files.too_large. Je-li zapnutá antivirová kontrola, infikovaný soubor vrací 422 files.infected, a pokud je antivirová kontrola nedostupná a platí zásada „reject“, požadavek vrací 503 files.scan_unavailable. Každé odmítnutí se zapíše do auditního protokolu jako file.rejected.

Místo formuláře lze odeslat tělo application/json (CardUploadFromUpload, od verze 1.62.0): souborem je hotové vícedílné nahrávání upload_id (POST /v1/uploads s účelem card_file), pole jsou stejná jako ve formuláři a tags je seznam řetězců. Soubor nahrávání už byl zkontrolován při complete (formát, antivirus) a limitem velikosti je limit vícedílného nahrávání místo limitu nahrávání jedním požadavkem. Nahrávání se použije jednou, ve stejné transakci, která vytváří kartu: již použité nahrávání vrací 409 uploads.already_used, dosud nepřipravené 409 uploads.not_ready, odmítnuté 422 uploads.rejected, nahrávání s jiným účelem 422 uploads.purpose_mismatch, nahrávání s vypršelou platností 410 uploads.expired a nahrávání jiného volajícího nebo neznámé nahrávání 404 uploads.not_found. Pokud kontroly karty selžou (kolekce, kategorie, limity), nahrávání se nespotřebuje.

Autentizace

Odešlete klíč API v hlavičce Authorization: Authorization: Bearer <klíč>.

Parametry hlavičky

Idempotency-Keystring
Klíč pro bezpečné opakování zápisu: 1 až 255 tisknutelných znaků ASCII; doporučuje se UUID v4 pro každou logickou operaci. Opakování se stejným klíčem do 24 hodin operaci znovu nespustí: vrátí uloženou odpověď (stav, hlavičky a tělo) s hlavičkou Idempotency-Replayed: true. Stejný klíč s jinou metodou, cestou, Content-Type nebo tělem vrací 409 api.idempotency_mismatch; dokud první požadavek ještě běží, vrací 409 api.idempotency_in_progress s Retry-After: 1. Po odpovědi 5xx nebo 429 se klíč uvolní a opakování operaci spustí znovu. Klíč platí v rámci organizace a volajícího (klíč API, uživatel nebo klíč vlastního zdroje).
length ≥ 1, length ≤ 255
X-View-Asstring
Jen pro klíče API s rolí admin. Provede požadavek jako datový profil <profile>[:viewer|verifier|editor], například employee:viewer. Instalační klíč tuto hlavičku použít nemůže (403).

Parametry cookie

kb_view_asstring
Cookie režimu „View as“ pro relaci. POST /auth/view-as ji nastaví a DELETE /auth/view-as ji smaže.

Tělo požadavku

multipart/form-data

Objekt: CardUploadForm

filestring (application/octet-stream)povinné
collectionstring
Výchozí: "default"
tagsstring
Výchozí: ""
forceboolean
Výchozí: false
owner_idinteger | null
verify_interval_daysinteger | null
categorystring | null
sensitiveboolean | null
asyncboolean
Výchozí: false
reviewboolean
Výchozí: false
folder_idstring | null
Složka kolekce collection, do které se nová karta vloží. Složka jiné kolekce vrací 400 folders.card_collection_mismatch, chybějící složka vrací 404 folders.not_found a chybějící oprávnění COLLECTION_EDIT_CARDS ke složce vrací 403 authz.forbidden. Kontrola proběhne před uložením souboru. Duplikát již nahraného souboru (skipped) se do složky nepřesouvá.
length ≤ 64
collection_idinteger | null
Kolekce podle ID. Pokud je předáno i collection, má přednost collection_id. Kolekce, která v organizaci neexistuje nebo není viditelná, vrací 404 collections.not_found.
external_idstring | null
external_id nové karty. S ním se karta vytvoří, i když kolekce už stejný soubor obsahuje. Pokud ho používá jiná karta organizace, požadavek vrací 409 cards.external_id_taken. K vytvoření nebo nahrazení karty podle external_id použijte PUT /v1/cards-by-external-id/{external_id}.
length ≤ 512
metadatastring | null
metadata nové karty: objekt JSON jako hodnota pole formuláře. Platí pravidla MetadataPatch.

application/json

Objekt: CardUploadFromUpload

upload_idstringpovinné
Připravené nahrávání (ready) s účelem card_file; použije se jen jednou.
collectionstring
Výchozí: "default"
collection_idinteger | null
Kolekce podle ID. Pokud je předáno i collection, má přednost collection_id. Kolekce, která v organizaci neexistuje, není viditelná nebo je mimo kolekce klíče, vrací 404 collections.not_found.
tagsarray of string
items ≤ 30
forceboolean
Výchozí: false
owner_idinteger | null
verify_interval_daysinteger | null
categorystring | null
sensitiveboolean | null
asyncboolean
Výchozí: false
reviewboolean
Výchozí: false
folder_idstring | null
length ≤ 64
external_idstring | null
external_id nové karty, stejně jako ve formulářovém poli. S ním se karta vytvoří, i když kolekce už stejný soubor obsahuje. Pokud ho používá jiná karta organizace, požadavek vrací 409 cards.external_id_taken.
length ≤ 512
metadataMetadataPatch

Odpovědi

200`queued` (asynchronně), `skipped` (duplicita), `ready` nebo `error` (synchronně).

Hlavičky odpovědi

RateLimit-Policy
Platné limity ve formátu návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddělené čárkou "<name>";q=<quota>;w=<window in seconds>. key je četnost požadavků klíče API (kvóta je nárazová špička, okno je doba jejího úplného obnovení; pro relaci je to user, bez přihlašovacích údajů ip); minute, day a month jsou kvóty organizace na kalendářní minutu, den a měsíc v UTC.
RateLimit
Kolik zbývá z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limit nejpřísnější položky v RateLimit-Policy (té, ve které zbývá nejméně požadavků).
X-RateLimit-Remaining
Počet požadavků, které zbývají v rámci nejpřísnějšího limitu.
X-RateLimit-Reset
Počet sekund do obnovení nejpřísnějšího limitu.
Idempotency-Replayed
true znamená, že jde o znovu vrácenou uloženou odpověď pro tento Idempotency-Key: operace se znovu nespustila.

application/json

Objekt: UploadResult

statusstringpovinné
Povolené hodnoty: queuedskippedreadyerror
job_idinteger
jobJob
cardCard | null
duplicatetrue
card_idstring | null
reasonstring
unchanged nebo an identical file is already indexed.
tablesinteger
timingsobject
Pole
- total_snumber
errorstring

400Požadavek je neplatný: hodnota parametru nebo stav objektu akci neumožňuje (`detail` je zpráva).

Hlavičky odpovědi

RateLimit-Policy
Platné limity ve formátu návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddělené čárkou "<name>";q=<quota>;w=<window in seconds>. key je četnost požadavků klíče API (kvóta je nárazová špička, okno je doba jejího úplného obnovení; pro relaci je to user, bez přihlašovacích údajů ip); minute, day a month jsou kvóty organizace na kalendářní minutu, den a měsíc v UTC.
RateLimit
Kolik zbývá z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limit nejpřísnější položky v RateLimit-Policy (té, ve které zbývá nejméně požadavků).
X-RateLimit-Remaining
Počet požadavků, které zbývají v rámci nejpřísnějšího limitu.
X-RateLimit-Reset
Počet sekund do obnovení nejpřísnějšího limitu.

application/json

Objekt: Error

401Nebyly odeslány žádné přihlašovací údaje (ani cookie relace, ani klíč API), nebo klíč nebyl nalezen.

Hlavičky odpovědi

RateLimit-Policy
Platné limity ve formátu návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddělené čárkou "<name>";q=<quota>;w=<window in seconds>. key je četnost požadavků klíče API (kvóta je nárazová špička, okno je doba jejího úplného obnovení; pro relaci je to user, bez přihlašovacích údajů ip); minute, day a month jsou kvóty organizace na kalendářní minutu, den a měsíc v UTC.
RateLimit
Kolik zbývá z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limit nejpřísnější položky v RateLimit-Policy (té, ve které zbývá nejméně požadavků).
X-RateLimit-Remaining
Počet požadavků, které zbývají v rámci nejpřísnějšího limitu.
X-RateLimit-Reset
Počet sekund do obnovení nejpřísnějšího limitu.

application/json

Objekt: Error

402Organizace dosáhla limitu tarifu (karty, úložiště nebo uživatelé). `error.details` obsahuje `kind`, `limit` a `used`.

Hlavičky odpovědi

RateLimit-Policy
Platné limity ve formátu návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddělené čárkou "<name>";q=<quota>;w=<window in seconds>. key je četnost požadavků klíče API (kvóta je nárazová špička, okno je doba jejího úplného obnovení; pro relaci je to user, bez přihlašovacích údajů ip); minute, day a month jsou kvóty organizace na kalendářní minutu, den a měsíc v UTC.
RateLimit
Kolik zbývá z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limit nejpřísnější položky v RateLimit-Policy (té, ve které zbývá nejméně požadavků).
X-RateLimit-Remaining
Počet požadavků, které zbývají v rámci nejpřísnějšího limitu.
X-RateLimit-Reset
Počet sekund do obnovení nejpřísnějšího limitu.

application/json

Objekt: Error

403Akce není povolena: role nestačí, chybí přístup ke kolekci nebo kartě, požadavek běží v režimu „View as“, nebo je organizace pozastavená či smazaná (`detail` je objekt s `code: org_suspended | org_deleted`).

Hlavičky odpovědi

RateLimit-Policy
Platné limity ve formátu návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddělené čárkou "<name>";q=<quota>;w=<window in seconds>. key je četnost požadavků klíče API (kvóta je nárazová špička, okno je doba jejího úplného obnovení; pro relaci je to user, bez přihlašovacích údajů ip); minute, day a month jsou kvóty organizace na kalendářní minutu, den a měsíc v UTC.
RateLimit
Kolik zbývá z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limit nejpřísnější položky v RateLimit-Policy (té, ve které zbývá nejméně požadavků).
X-RateLimit-Remaining
Počet požadavků, které zbývají v rámci nejpřísnějšího limitu.
X-RateLimit-Reset
Počet sekund do obnovení nejpřísnějšího limitu.

application/json

Objekt: Error

404Objekt neexistuje nebo vám není dostupný. API nepotvrzuje, že objekt s omezeným přístupem existuje.

Hlavičky odpovědi

RateLimit-Policy
Platné limity ve formátu návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddělené čárkou "<name>";q=<quota>;w=<window in seconds>. key je četnost požadavků klíče API (kvóta je nárazová špička, okno je doba jejího úplného obnovení; pro relaci je to user, bez přihlašovacích údajů ip); minute, day a month jsou kvóty organizace na kalendářní minutu, den a měsíc v UTC.
RateLimit
Kolik zbývá z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limit nejpřísnější položky v RateLimit-Policy (té, ve které zbývá nejméně požadavků).
X-RateLimit-Remaining
Počet požadavků, které zbývají v rámci nejpřísnějšího limitu.
X-RateLimit-Reset
Počet sekund do obnovení nejpřísnějšího limitu.

application/json

Objekt: Error

409Stav objektu akci neumožňuje, například kvůli duplicitě, probíhajícímu indexování nebo úloze, která už je zpracovaná.

Hlavičky odpovědi

RateLimit-Policy
Platné limity ve formátu návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddělené čárkou "<name>";q=<quota>;w=<window in seconds>. key je četnost požadavků klíče API (kvóta je nárazová špička, okno je doba jejího úplného obnovení; pro relaci je to user, bez přihlašovacích údajů ip); minute, day a month jsou kvóty organizace na kalendářní minutu, den a měsíc v UTC.
RateLimit
Kolik zbývá z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limit nejpřísnější položky v RateLimit-Policy (té, ve které zbývá nejméně požadavků).
X-RateLimit-Remaining
Počet požadavků, které zbývají v rámci nejpřísnějšího limitu.
X-RateLimit-Reset
Počet sekund do obnovení nejpřísnějšího limitu.

application/json

Objekt: Error

410Objekt existoval, ale už není dostupný: odkaz byl použit nebo vypršel, nebo byl soubor smazán po uplynutí doby uchovávání.

Hlavičky odpovědi

RateLimit-Policy
Platné limity ve formátu návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddělené čárkou "<name>";q=<quota>;w=<window in seconds>. key je četnost požadavků klíče API (kvóta je nárazová špička, okno je doba jejího úplného obnovení; pro relaci je to user, bez přihlašovacích údajů ip); minute, day a month jsou kvóty organizace na kalendářní minutu, den a měsíc v UTC.
RateLimit
Kolik zbývá z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limit nejpřísnější položky v RateLimit-Policy (té, ve které zbývá nejméně požadavků).
X-RateLimit-Remaining
Počet požadavků, které zbývají v rámci nejpřísnějšího limitu.
X-RateLimit-Reset
Počet sekund do obnovení nejpřísnějšího limitu.

application/json

Objekt: Error

413Tělo požadavku překračuje povolenou velikost.

Hlavičky odpovědi

RateLimit-Policy
Platné limity ve formátu návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddělené čárkou "<name>";q=<quota>;w=<window in seconds>. key je četnost požadavků klíče API (kvóta je nárazová špička, okno je doba jejího úplného obnovení; pro relaci je to user, bez přihlašovacích údajů ip); minute, day a month jsou kvóty organizace na kalendářní minutu, den a měsíc v UTC.
RateLimit
Kolik zbývá z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limit nejpřísnější položky v RateLimit-Policy (té, ve které zbývá nejméně požadavků).
X-RateLimit-Remaining
Počet požadavků, které zbývají v rámci nejpřísnějšího limitu.
X-RateLimit-Reset
Počet sekund do obnovení nejpřísnějšího limitu.

application/json

Objekt: Error

415Formát souboru není podporován.

Hlavičky odpovědi

RateLimit-Policy
Platné limity ve formátu návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddělené čárkou "<name>";q=<quota>;w=<window in seconds>. key je četnost požadavků klíče API (kvóta je nárazová špička, okno je doba jejího úplného obnovení; pro relaci je to user, bez přihlašovacích údajů ip); minute, day a month jsou kvóty organizace na kalendářní minutu, den a měsíc v UTC.
RateLimit
Kolik zbývá z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limit nejpřísnější položky v RateLimit-Policy (té, ve které zbývá nejméně požadavků).
X-RateLimit-Remaining
Počet požadavků, které zbývají v rámci nejpřísnějšího limitu.
X-RateLimit-Reset
Počet sekund do obnovení nejpřísnějšího limitu.

application/json

Objekt: Error

422Chyba validace: tělo nebo parametry neodpovídají schématu (`detail` je seznam chyb validace), nebo je hodnota parametru mimo povolený rozsah (`detail` je zpráva).

Hlavičky odpovědi

RateLimit-Policy
Platné limity ve formátu návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddělené čárkou "<name>";q=<quota>;w=<window in seconds>. key je četnost požadavků klíče API (kvóta je nárazová špička, okno je doba jejího úplného obnovení; pro relaci je to user, bez přihlašovacích údajů ip); minute, day a month jsou kvóty organizace na kalendářní minutu, den a měsíc v UTC.
RateLimit
Kolik zbývá z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limit nejpřísnější položky v RateLimit-Policy (té, ve které zbývá nejméně požadavků).
X-RateLimit-Remaining
Počet požadavků, které zbývají v rámci nejpřísnějšího limitu.
X-RateLimit-Reset
Počet sekund do obnovení nejpřísnějšího limitu.

application/json

Objekt: Error

429Příliš mnoho požadavků (`api.rate_limited`), kvóta organizace na minutu, den nebo měsíc je vyčerpána (`api.quota_exceeded`; `error.details` obsahuje `quota`, `limit` a `reset_at`), organizace dosáhla svého limitu nebo je služba odpovědí vytížená (`answers.engine_busy`). Počkejte dobu uvedenou v hlavičce `Retry-After`.

Hlavičky odpovědi

Retry-After
Počet sekund, které je třeba počkat před opakováním požadavku.
RateLimit-Policy
Platné limity ve formátu návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddělené čárkou "<name>";q=<quota>;w=<window in seconds>. key je četnost požadavků klíče API (kvóta je nárazová špička, okno je doba jejího úplného obnovení; pro relaci je to user, bez přihlašovacích údajů ip); minute, day a month jsou kvóty organizace na kalendářní minutu, den a měsíc v UTC.
RateLimit
Kolik zbývá z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limit nejpřísnější položky v RateLimit-Policy (té, ve které zbývá nejméně požadavků).
X-RateLimit-Remaining
Počet požadavků, které zbývají v rámci nejpřísnějšího limitu.
X-RateLimit-Reset
Počet sekund do obnovení nejpřísnějšího limitu.

application/json

Objekt: Error

503Služba, na které tento požadavek závisí, je dočasně nedostupná. Zopakujte požadavek později.

Hlavičky odpovědi

RateLimit-Policy
Platné limity ve formátu návrhu IETF draft-ietf-httpapi-ratelimit-headers: položky oddělené čárkou "<name>";q=<quota>;w=<window in seconds>. key je četnost požadavků klíče API (kvóta je nárazová špička, okno je doba jejího úplného obnovení; pro relaci je to user, bez přihlašovacích údajů ip); minute, day a month jsou kvóty organizace na kalendářní minutu, den a měsíc v UTC.
RateLimit
Kolik zbývá z každého limitu v RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limit nejpřísnější položky v RateLimit-Policy (té, ve které zbývá nejméně požadavků).
X-RateLimit-Remaining
Počet požadavků, které zbývají v rámci nejpřísnějšího limitu.
X-RateLimit-Reset
Počet sekund do obnovení nejpřísnějšího limitu.

application/json

Objekt: Error

Chybové kódy

Kódy, které tato operace může vrátit v error.code, kromě obecných kódů každého požadavku.

Bezpečné opakování

S každým požadavkem POST a PATCH odešlete hlavičku Idempotency-Key (například UUID). Opakování se stejným klíčem do 24 hodin vrátí uloženou odpověď, místo aby se požadavek provedl znovu.

Limity četnosti

Odpovědi obsahují hlavičky RateLimit a RateLimit-Policy a starší X-RateLimit-Limit, X-RateLimit-Remaining a X-RateLimit-Reset. Odpověď 429 má hlavičku Retry-After v sekundách: počkejte a požadavek zopakujte.

← cards · Reference API

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"

Vyzkoušet

Klíč API

Klíč zůstává v paměti této karty prohlížeče a odesílá se jen na https://api.sursa.com.

Požadavky pracují se skutečnými daty vaší organizace.

Idempotency-Key header

X-View-As header

Idempotency-Key

Když je pole prázdné, vygeneruje se pro každý požadavek nový klíč.

Tělo požadavku (JSON)