API: dokumenty (REST)

Tieto verejné endpointy slúžia na to, aby externý systém (ERP, CRM, skript…) spravoval dokumenty v jednom priečinku: posielal ich, vypísal ich zoznam a mazal ich. Autentifikujú sa API kľúčom typu „zápis dokumentov“, ktorý vygenerujete v administrácii, pozri API kľúče.

Kľúč je viazaný na jeden priečinok (typu „dokumenty“). Cieľový priečinok sa určí z kľúča, neposiela sa v tele.

Poslanie dokumentu

POST /api/v1/documents
Authorization: Bearer kw_live_…
Content-Type: application/json

{
  "content": "# Zápis z porady\n\nDohodli sme sa, že …",
  "id": "erp-doc-12345",          // voliteľné: stabilné ID pre upsert
  "title": "Zápis z porady",       // voliteľné: názov záznamu
  "format": "markdown"             // voliteľné: markdown | text | csv (predvolené markdown)
}

content (povinné): text dokumentu (markdown, čistý text alebo CSV).
format (voliteľné): markdown (predvolené), text alebo csv.

Upsert vs. nový dokument

S id: dokument sa uloží pod stabilným názvom odvodeným z id. Opätovné poslanie s tým istým id prepíše predchádzajúcu verziu (upsert). Ideálne pre priebežnú synchronizáciu.
Bez id: každé volanie pridá nový dokument.

Indexovanie prebieha asynchrónne, dokument je vyhľadateľný krátko po nahratí. Úspech vráti 202 Accepted:

{
  "ok": true,
  "document": { "name": "erp-doc-12345.md", "upserted": true },
  "collectionKey": "faktury",
  "note": "Indexing runs asynchronously; the document becomes searchable shortly."
}

Zoznam dokumentov

Vypíše dokumenty v priečinku kľúča.

GET /api/v1/documents
Authorization: Bearer kw_live_…

{
  "collectionKey": "faktury",
  "count": 2,
  "documents": [
    { "name": "erp-doc-12345.md", "size": 1024, "uploadedAt": "2026-08-19T10:00:00Z" }
  ]
}

Zmazanie dokumentu

Zmaže dokument poslaný cez API, podľa jeho id.

DELETE /api/v1/documents/{id}
Authorization: Bearer kw_live_…

{ "ok": true, "deleted": ["erp-doc-12345.md"] }

Zmazanie sa týka len dokumentov nahraných cez API (podľa konvencie názvu z id), takže kľúč nezmaže súbory, ktoré do priečinka nahral človek. Ak sa dokument s daným id nenájde, vráti 404.

Limity

Veľkosť dokumentu: max 1 MB textu.
Zatiaľ len textový obsah (markdown / text / CSV). Binárne súbory (napr. PDF) pribudnú neskôr.
Rate limit na kľúč: zápis/mazanie 60/min, výpis 120/min. Pri prekročení 429 rate_limited.

Chyby

Status	Kód / dôvod
`401`	Chýbajúci, neplatný, zneplatnený alebo expirovaný kľúč.
`403`	Kľúč nie je typu „zápis dokumentov“.
`403`	Balík neobsahuje API (Growth+).
`400`	Neplatné JSON telo alebo prázdny `content`.
`404`	Dokument s daným `id` sa v priečinku nenašiel (pri `DELETE`).
`413`	Dokument je väčší ako 1 MB.
`409`	Cieľový priečinok sa nedá zapisovať (spravovaný / len na čítanie).
`429`	`rate_limited`: prekročený rate limit na kľúč.
`502`	Operácia nad indexom zlyhala, skúste znova.

Príklad (curl)

curl -X POST https://<vasa-instancia>/api/v1/documents \
  -H "Authorization: Bearer kw_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "erp-doc-12345",
    "title": "Zápis z porady",
    "content": "# Zápis z porady\n\nDohodli sme sa, že …"
  }'