API-ul Dazr Files: documentație pentru dezvoltatori

Citiți fișiere din Dazr Files în propriul software, de exemplu pentru backup: un API REST cu flux de modificări și WebDAV pentru instrumentele de backup. Doar citire.

• Început rapid
• Acces al organizației
• Fișierele proprii ale unei persoane
• Referință
• Backupuri incrementale
• Erori și limite
• WebDAV

Început rapid

1. Înregistrați aplicația și activați API-ul Dazr Files. Înregistrați aplicația, sau folosiți una existentă, în consola Dazr Identity: același loc ca pentru Conectare cu Dazr Identity și API-ul Dazr Sign, cu același ID de client și același secret. Pe pagina aplicației, alegeți Activați API-ul Dazr Files. Pentru backupuri nesupravegheate, aplicația trebuie să fie de tip server web (cu secret de client).
2. Obțineți aprobarea. Dați organizației ID-ul de client. Un proprietar sau administrator deschide Dazr Identity → Organizații → organizația → Aplicații conectate la Files, introduce ID-ul de client și alege ce poate citi aplicația: toate fișierele partajate sau dosarele alese cu tot conținutul lor. Poate limita aplicația și la rețele indicate (intervale IP).
3. Obțineți un token. Serverul dvs. cere un token cu grant_type=client_credentials, id-ul organizației ca org, și ID-ul de client și secretul (HTTP Basic sau corpul formularului). Doar aplicațiile cu secret de client pot face asta.
4. Apelați API-ul. Trimiteți tokenul de acces ca Authorization: Bearer. Este valabil 10 minute și nu există token de reîmprospătare: cereți unul nou când expiră.

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

Acces al organizației pentru backup

Există două căi. Un proprietar sau administrator al unei organizații aprobă aplicația dvs. pentru fișierele partajate ale organizației, iar serverul dvs. primește tokenuri fără o persoană (ideal pentru backupuri nesupravegheate). Sau o persoană permite aplicației scope-ul files.read, iar aplicația citește fișierele proprii ale acelei persoane.

O organizație care nu a aprobat aplicația, una care a revocat-o și una care nu există răspund toate invalid_grant. Administratorii văd când a fost folosită ultima dată aplicația și fiecare fișier descărcat, și îi pot modifica oricând dosarele sau o pot revoca. O aprobare revocată se oprește la următoarea cerere: tokenurile deja emise nu mai funcționează imediat, la fel și linkurile de descărcare deja date. Fișierele proprii ale membrilor nu fac niciodată parte din aprobarea unei organizații.

Fișierele proprii ale unei persoane

Cereți openid files.read (și offline_access pentru un token de reîmprospătare) în fluxul obișnuit authorization code cu PKCE. Persoana vede pe ecranul de consimțământ că aplicația îi poate vedea și descărca fișierele. Tokenul ajunge la fișierele ei proprii, iar la fișierele partajate ale unei organizații doar dacă și acea organizație a aprobat aplicația și persoana este un membru care le poate deschide, cu aceleași dosare. Când persoana elimină aplicația din Aplicații conectate, tokenurile nu mai funcționează.

Referință

URL de bază https://suite.dazr.eu/api/files/v1. Fiecare endpoint este GET (și HEAD); orice altă metodă răspunde 405. Erorile sunt JSON: { "error": { "code", "message" } }. Listele acceptă limit (între 1 și 1000, implicit 200) și returnează next_cursor cât timp mai sunt elemente.

Fiecare cerere are nevoie de scope-ul files.read. Parametri de interogare:

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

Urmați redirecționarea (curl -L): linkul de pe files.dazr.eu nu are nevoie de antetul Authorization. Un fișier care nu este încă în gateway-ul Files este transmis direct în loc să fie redirecționat.

Sume de control: Dazr Files nu stochează un hash al conținutului fiecărui fișier, deci sha256 este mereu null. etag-ul se schimbă de fiecare dată când se schimbă conținutul (o versiune nouă). Calculați-vă propriul hash în timpul descărcării, dacă aveți nevoie. Fișierele sunt stocate criptat (AES-256-GCM, cu o cheie pentru fiecare spațiu, păstrată de Dazr), iar Dazr le decriptează când le descărcați prin TLS. Aceasta nu este criptare end-to-end.

Backupuri incrementale

Apelați changes o dată fără cursor: fiecare dosar și fișier vine ca created, cu un cursor. Păstrați cursorul și trimiteți-l data viitoare ca cursor=. Primiți ce s-a schimbat între timp: created, updated (conținut nou), moved (redenumit sau mutat în alt dosar), trashed, restored și deleted (șters definitiv sau nu mai este în dosarele pe care aplicația le poate citi). Fiecare schimbare are id-ul, item_type și item-ul curent (null la ștergere). Dosarele vin înaintea fișierelor, părinții înaintea copiilor. Cât timp has_more este true, apelați din nou cu noul cursor. Dacă nu s-a schimbat nimic, primiți același cursor. Un cursor funcționează 90 de zile, doar pentru aplicația dvs. și acel spațiu; unul expirat răspunde 410 și o luați de la capăt fără cursor. Rămân valabile doar cele mai noi 5 cursoare ale aplicației pentru un spațiu.

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 }

Erori și limite

Erorile au un status HTTP și un corp precum { "error": { "code": "not_found", "message": "..." } }. Tot ce tokenul nu poate atinge răspunde 404, la fel ca ceva ce nu există.

Endpointul de token răspunde cu erori OAuth: invalid_client (ID de client sau secret greșit, ori o aplicație fără secret de client), unauthorized_client (API-ul Dazr Files nu este activat pentru aplicație), invalid_scope și invalid_grant (nicio aprobare a acelei organizații sau nu din rețelele indicate).

Fiecare descărcare este înregistrată pentru administratorii organizației cu numele aplicației, fișierul, ora și o parte din adresa IP: ultimele 5.000, până la 180 de zile. Același fișier descărcat din nou în 10 minute se numără o dată. Activitatea Files a organizației arată o linie pe zi pentru aplicația dvs. Descărcările din fișierele proprii ale unei persoane apar în Aplicațiile conectate ale acesteia.

WebDAV

Pentru instrumentele de backup care folosesc WebDAV, un administrator al organizației creează o conectare WebDAV pentru aplicația dvs. în Aplicații conectate la Files. Parola este afișată o dată, este stocată doar ca hash și nu este niciodată parola Dazr a cuiva. Conectarea urmează aprobarea: aceleași dosare, rețele și limite, și se oprește când aprobarea este revocată.

Numele dosarelor și fișierelor sunt afișate așa cum sunt în Dazr Files. Când două elemente dintr-un dosar au același nume (fără a ține cont de majuscule), cel mai vechi îl păstrează, iar celelalte primesc id-ul între paranteze înaintea extensiei, astfel încât fiecare element are propria cale. Un dosar cu peste 10.000 de elemente nu poate fi listat prin WebDAV; folosiți API-ul pentru el. După 10 conectări eșuate de la o adresă IP în 15 minute, acea adresă așteaptă 15 minute.

rclone

1. Rulați rclone config, alegeți n pentru un remote nou, numiți-l dazr și alegeți tipul de stocare webdav.
2. URL: https://files.dazr.eu/dav/. Vendor: other. User: numele de utilizator (dzw_…). Password: alegeți să o introduceți și lipiți parola.
3. Lăsați bearer token gol și salvați. Verificați cu rclone lsd dazr:, apoi faceți backupul.

# ~/.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 compară dimensiunea și ora modificării. Folosiți copy în loc de sync pentru a păstra în backup fișierele șterse în Dazr Files.

Synology Cloud Sync

1. Deschideți Cloud Sync pe NAS, adăugați un furnizor cloud și alegeți WebDAV.
2. Adresa serverului: https://files.dazr.eu/dav/. Nume de utilizator și parolă: conectarea WebDAV de la administrator.
3. Alegeți un dosar local, dosarul la distanță / (sau un dosar) și direcția de sincronizare Download remote changes only.

Cloud Sync cu WebDAV, direcția de sincronizare „Download remote changes only”. Hyper Backup scrie backupuri pe WebDAV, dar nu poate citi de acolo.