API Dazr Files: dokumentácia pre vývojárov

Čítajte súbory z Dazr Files vo vlastnom softvéri, napríklad kvôli zálohovaniu: REST API s kanálom zmien a WebDAV pre zálohovacie nástroje. Iba čítanie.

• Rýchly štart
• Prístup organizácie
• Vlastné súbory osoby
• Referencia
• Prírastkové zálohy
• Chyby a limity
• WebDAV

Rýchly štart

1. Zaregistrujte aplikáciu a zapnite API Dazr Files. Zaregistrujte aplikáciu, alebo použite existujúcu, v konzole Dazr Identity: na rovnakom mieste ako prihlásenie cez Dazr Identity a API Dazr Sign, s rovnakým Client ID a tajným kľúčom. Na stránke aplikácie zvoľte Zapnúť API Dazr Files. Pre zálohy bez obsluhy musí ísť o aplikáciu webového servera (s tajným kľúčom klienta).
2. Získajte schválenie. Dajte organizácii svoje Client ID. Vlastník alebo správca otvorí Dazr Identity → Organizácie → organizácia → Prepojené aplikácie pre Files, zadá Client ID a vyberie, čo smie vaša aplikácia čítať: všetky zdieľané súbory, alebo vybrané priečinky so všetkým, čo obsahujú. Môže tiež aplikáciu obmedziť na uvedené siete (rozsahy IP).
3. Získajte token. Váš server si vyžiada token s grant_type=client_credentials, id organizácie ako org a vaším Client ID a tajným kľúčom (HTTP Basic alebo telo formulára). Môžu to len aplikácie s tajným kľúčom klienta.
4. Zavolajte API. Posielajte prístupový token ako Authorization: Bearer. Platí 10 minút a refresh token neexistuje: keď vyprší, vyžiadajte si nový.

curl -u "$DAZR_CLIENT_ID:$DAZR_CLIENT_SECRET" https://identity.dazr.eu/oauth/token \
  -d grant_type=client_credentials -d scope=files.read -d org=org_3k9x2m0q8w1v5t7a

{ "access_token": "eyJhbGciOiJFUzI1NiIs...", "token_type": "Bearer", "expires_in": 600, "scope": "files.read" }

curl -H "Authorization: Bearer $TOKEN" https://suite.dazr.eu/api/files/v1/spaces

Prístup organizácie pre zálohy

Sú dve cesty. Vlastník alebo správca organizácie schváli vašu aplikáciu pre zdieľané súbory organizácie a váš server potom dostáva tokeny bez osoby (najlepšie pre zálohy bez obsluhy). Alebo osoba povolí vašej aplikácii scope files.read a aplikácia číta vlastné súbory tejto osoby.

Organizácia, ktorá vašu aplikáciu neschválila, organizácia, ktorá schválenie odvolala, aj organizácia, ktorá neexistuje, odpovedia rovnako: invalid_grant. Správcovia vidia, kedy bola aplikácia naposledy použitá, a každý súbor, ktorý stiahla, a môžu kedykoľvek zmeniť jej priečinky alebo ju odvolať. Odvolané schválenie skončí pri ďalšej požiadavke: už vydané tokeny okamžite prestanú fungovať, rovnako ako už vydané odkazy na stiahnutie. Vlastné súbory členov nie sú nikdy súčasťou schválenia organizácie.

Vlastné súbory osoby

Požiadajte o openid files.read (a offline_access pre refresh token) v obvyklom toku authorization code s PKCE. Osoba na obrazovke súhlasu uvidí, že vaša aplikácia smie jej súbory zobraziť a stiahnuť. Token dosiahne na jej vlastné súbory a na zdieľané súbory organizácie len vtedy, keď vašu aplikáciu schválila aj táto organizácia a osoba je členom, ktorý ich smie otvoriť, s rovnakými priečinkami. Keď osoba aplikáciu odstráni v Prepojených aplikáciách, tokeny prestanú fungovať.

Referencia

Základná URL https://suite.dazr.eu/api/files/v1. Každý endpoint je GET (a HEAD); akákoľvek iná metóda odpovie 405. Chyby sú v JSON: { "error": { "code", "message" } }. Zoznamy berú limit (1 až 1000, predvolene 200) a vracajú next_cursor, kým je čo načítať.

Každá požiadavka potrebuje scope files.read. Parametre dopytu:

GET /spaces
{ "spaces": [ { "id": "org_3k9x2m0q8w1v5t7a", "type": "organisation", "name": "Bakkerij Jansen", "folders": "chosen" } ] }

GET /spaces/org_3k9x2m0q8w1v5t7a/folders/root/children?limit=2
{ "items": [
    { "id": "Hk2mQ9xP4aL1", "type": "folder", "name": "Finance", "parent_id": null, "path": "/Finance",
      "created_at": "2026-09-01T08:12:40.000Z" },
    { "id": "p3RtY7uW0zQe", "type": "file", "name": "Budget 2027.xlsx", "parent_id": "Hk2mQ9xP4aL1",
      "path": "/Finance/Budget 2027.xlsx", "size": 48213,
      "mime": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet", "version": 3, "version_count": 3,
      "etag": "\"p3RtY7uW0zQe.3.48213\"", "sha256": null, "created_at": "2026-09-02T10:00:00.000Z",
      "modified_at": "2026-10-14T16:31:09.000Z", "trashed_at": null } ],
  "next_cursor": "o.2" }

GET /spaces/org_3k9x2m0q8w1v5t7a/files/p3RtY7uW0zQe/versions
{ "versions": [ { "version": 3, "size": 48213, "mime": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
                  "created_at": "2026-10-14T16:31:09.000Z", "current": true, "restored_from": null } ] }

GET /spaces/org_3k9x2m0q8w1v5t7a/files/p3RtY7uW0zQe/content
302 Found
Location: https://files.dazr.eu/v1/file?t=g1.…

curl -L -o "Budget 2027.xlsx" -H "Authorization: Bearer $TOKEN" \
  https://suite.dazr.eu/api/files/v1/spaces/org_3k9x2m0q8w1v5t7a/files/p3RtY7uW0zQe/content

Nasledujte presmerovanie (curl -L): odkaz na files.dazr.eu nepotrebuje hlavičku Authorization. Súbor, ktorý ešte nie je v bráne Files, sa streamuje priamo namiesto presmerovania.

Kontrolné súčty: Dazr Files neukladá hash obsahu jednotlivých súborov, preto je sha256 vždy null. etag sa zmení vždy, keď sa zmení obsah (nová verzia). Ak hash potrebujete, vypočítajte si ho pri sťahovaní. Súbory sú uložené šifrovane (AES-256-GCM, s kľúčom pre každý priestor, ktorý spravuje Dazr) a Dazr ich dešifruje, keď ich sťahujete cez TLS. Nejde o end-to-end šifrovanie.

Prírastkové zálohy

Zavolajte changes prvýkrát bez kurzora: každý priečinok a súbor sa vráti ako created, spolu s cursor. Kurzor si uložte a nabudúce ho pošlite ako cursor=. Dostanete, čo sa medzitým zmenilo: created, updated (nový obsah), moved (premenované alebo presunuté do iného priečinka), trashed, restored a deleted (natrvalo odstránené, alebo už mimo priečinkov, ktoré aplikácia smie čítať). Každá zmena má id, item_type a aktuálny item (null pri odstránených). Priečinky sú pred súbormi, rodičia pred deťmi. Kým je has_more true, volajte znova s novým kurzorom. Keď sa nič nezmenilo, dostanete rovnaký kurzor. Kurzor platí 90 dní, len pre vašu aplikáciu a daný priestor; vypršaný odpovie 410 a začnete znova bez kurzora. Platných zostáva len 5 najnovších kurzorov vašej aplikácie pre daný priestor.

GET /spaces/org_3k9x2m0q8w1v5t7a/changes?cursor=dc1.ds_…
{ "changes": [
    { "type": "updated", "id": "p3RtY7uW0zQe", "item_type": "file",
      "item": { "id": "p3RtY7uW0zQe", "type": "file", "name": "Budget 2027.xlsx", "version": 4, … } },
    { "type": "deleted", "id": "Zx81LmQa2bNc", "item_type": "file", "item": null } ],
  "cursor": "dc1.ds_…",
  "has_more": false }

Chyby a limity

Chyby majú stav HTTP a telo ako { "error": { "code": "not_found", "message": "..." } }. Všetko, na čo token nedosiahne, odpovie 404, rovnako ako niečo, čo neexistuje.

Endpoint tokenu odpovedá chybami OAuth: invalid_client (nesprávne Client ID alebo tajný kľúč, alebo aplikácia bez tajného kľúča klienta), unauthorized_client (API Dazr Files nie je pre aplikáciu zapnuté), invalid_scope a invalid_grant (žiadne schválenie od tejto organizácie, alebo nie z jej uvedených sietí).

Každé stiahnutie sa pre správcov organizácie zaznamená s názvom aplikácie, súborom, časom a časťou IP adresy: posledných 5 000, až 180 dní. Rovnaký súbor stiahnutý znova do 10 minút sa počíta raz. Aktivita Files organizácie ukazuje pre vašu aplikáciu jeden riadok denne. Stiahnutia z vlastných súborov osoby sa zobrazia v jej Prepojených aplikáciách.

WebDAV

Pre zálohovacie nástroje, ktoré podporujú WebDAV, vytvorí správca organizácie pre vašu aplikáciu prihlásenie WebDAV v Prepojených aplikáciách pre Files. Heslo sa zobrazí raz, ukladá sa len ako hash a nikdy to nie je niečie heslo k Dazr. Prihlásenie sa riadi schválením: rovnaké priečinky, siete a limity, a skončí, keď sa schválenie odvolá.

Názvy priečinkov a súborov sa zobrazujú tak, ako sú v Dazr Files. Keď majú dve položky v priečinku rovnaký názov (bez ohľadu na veľkosť písmen), staršia si ho ponechá a ostatné dostanú svoje id v zátvorke pred príponou, aby mala každá položka vlastnú cestu. Priečinok s viac ako 10 000 položkami nemožno cez WebDAV vypísať; použite preň API. Po 10 neúspešných prihláseniach z jednej IP adresy počas 15 minút táto adresa 15 minút čaká.

rclone

1. Spustite rclone config, zvoľte n pre nový remote, pomenujte ho dazr a zvoľte typ úložiska webdav.
2. URL: https://files.dazr.eu/dav/. Vendor: other. User: používateľské meno (dzw_…). Password: zvoľte vlastné zadanie a vložte heslo.
3. Bearer token nechajte prázdny a uložte. Overte pomocou rclone lsd dazr: a potom zálohujte.

# ~/.config/rclone/rclone.conf (rclone obscure <password> gives the pass value)
[dazr]
type = webdav
url = https://files.dazr.eu/dav/
vendor = other
user = dzw_0123456789abcdef0123
pass = <obscured password>

rclone lsd dazr:
rclone sync dazr: /backup/dazr --transfers 4

rclone porovnáva veľkosť a čas zmeny. Použite copy namiesto sync, aby v zálohe zostali súbory odstránené v Dazr Files.

Synology Cloud Sync

1. Otvorte na NAS Cloud Sync, pridajte poskytovateľa cloudu a zvoľte WebDAV.
2. Adresa servera: https://files.dazr.eu/dav/. Používateľské meno a heslo: prihlásenie WebDAV od správcu.
3. Zvoľte miestny priečinok, vzdialený priečinok / (alebo jeden priečinok) a smer synchronizácie Download remote changes only.

Cloud Sync s WebDAV, smer synchronizácie „Download remote changes only“. Hyper Backup zálohy na WebDAV zapisuje, ale čítať z neho nevie.