API do Dazr Files: documentação para programadores

Leia ficheiros do Dazr Files no seu software, por exemplo para cópias de segurança: uma API REST com feed de alterações, e WebDAV para ferramentas de cópia de segurança. Só leitura.

• Início rápido
• Acesso de uma organização
• Os ficheiros próprios de uma pessoa
• Referência
• Cópias de segurança incrementais
• Erros e limites
• WebDAV

Início rápido

1. Registe a sua aplicação e ative a API do Dazr Files. Registe a aplicação, ou use uma que já tenha, na consola do Dazr Identity: o mesmo sítio que para Iniciar sessão com Dazr Identity e a API do Dazr Sign, com o mesmo ID de cliente e segredo. Na página da aplicação, escolha Ativar a API do Dazr Files. Para cópias de segurança automáticas, tem de ser uma aplicação de servidor web (com segredo de cliente).
2. Obtenha a aprovação. Dê o seu ID de cliente à organização. Um proprietário ou administrador abre Dazr Identity → Organizações → a organização → Aplicações ligadas ao Files, introduz o ID de cliente e escolhe o que a sua aplicação pode ler: todos os ficheiros partilhados, ou pastas escolhidas com tudo o que contêm. Também pode limitar a aplicação a redes indicadas (intervalos IP).
3. Obtenha um token. O seu servidor pede um token com grant_type=client_credentials, o id da organização como org, e o seu ID de cliente e segredo (HTTP Basic ou o corpo do formulário). Só as aplicações com segredo de cliente o podem fazer.
4. Chame a API. Envie o token de acesso como Authorization: Bearer. Dura 10 minutos e não há token de atualização: peça um novo quando expirar.

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

Acesso de uma organização para cópias de segurança

Há duas formas de acesso. Um proprietário ou administrador de uma organização aprova a sua aplicação para os ficheiros partilhados da organização, e o seu servidor obtém tokens sem uma pessoa (o melhor para cópias de segurança automáticas). Ou uma pessoa autoriza a sua aplicação com o scope files.read, e a aplicação lê os ficheiros próprios dessa pessoa.

Uma organização que não aprovou a sua aplicação, uma que a revogou e uma que não existe respondem todas invalid_grant. Os administradores veem quando a aplicação foi usada pela última vez e cada ficheiro que transferiu, e podem alterar as pastas ou revogá-la a qualquer momento. Uma aprovação revogada para no pedido seguinte: os tokens já emitidos deixam de funcionar de imediato, tal como as ligações de transferência já entregues. Os ficheiros próprios dos membros nunca fazem parte da aprovação de uma organização.

Os ficheiros próprios de uma pessoa

Peça openid files.read (e offline_access para um token de atualização) no fluxo habitual de authorization code com PKCE. A pessoa vê no ecrã de consentimento que a sua aplicação pode ver e transferir os seus ficheiros. O token chega aos ficheiros próprios dela, e aos ficheiros partilhados de uma organização só quando essa organização também aprovou a aplicação e a pessoa é um membro que os pode abrir, com as mesmas pastas. Quando a pessoa remove a aplicação em Aplicações ligadas, os tokens deixam de funcionar.

Referência

URL base https://suite.dazr.eu/api/files/v1. Todos os endpoints são GET (e HEAD); qualquer outro método responde 405. Os erros são JSON: { "error": { "code", "message" } }. As listas aceitam limit (1 a 1000, 200 por omissão) e devolvem next_cursor enquanto houver mais.

Cada pedido precisa do scope files.read. Parâmetros de consulta:

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

Siga o redirecionamento (curl -L): a ligação em files.dazr.eu não precisa do cabeçalho Authorization. Um ficheiro que ainda não está no gateway do Files é transmitido diretamente em vez de redirecionado.

Somas de verificação: o Dazr Files não guarda um hash do conteúdo de cada ficheiro, por isso sha256 é sempre null. O etag muda sempre que o conteúdo muda (uma nova versão). Calcule o seu próprio hash durante a transferência, se precisar. Os ficheiros são guardados cifrados (AES-256-GCM, com uma chave por espaço guardada pelo Dazr) e o Dazr decifra-os quando os transfere por TLS. Isto não é cifragem ponto a ponto.

Cópias de segurança incrementais

Chame changes uma vez sem cursor: cada pasta e ficheiro volta como created, com um cursor. Guarde o cursor e envie-o da próxima vez como cursor=. Recebe o que mudou desde então: created, updated (conteúdo novo), moved (mudou de nome ou foi movido para outra pasta), trashed, restored e deleted (eliminado de vez, ou já fora das pastas que a aplicação pode ler). Cada alteração tem o id, o item_type e o item atual (null quando eliminado). As pastas vêm antes dos ficheiros, os pais antes dos filhos. Enquanto has_more for true, chame de novo com o novo cursor. Se nada mudou, recebe o mesmo cursor. Um cursor funciona durante 90 dias, só para a sua aplicação e esse espaço; um expirado responde 410, e recomeça sem cursor. Só os 5 cursores mais recentes da sua aplicação para um espaço continuam válidos.

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 }

Erros e limites

Os erros têm um estado HTTP e um corpo como { "error": { "code": "not_found", "message": "..." } }. Tudo o que o token não alcança responde 404, tal como o que não existe.

O endpoint de token responde com erros OAuth: invalid_client (ID de cliente ou segredo errados, ou uma aplicação sem segredo de cliente), unauthorized_client (a API do Dazr Files não está ativa para a aplicação), invalid_scope e invalid_grant (sem aprovação dessa organização, ou fora das suas redes indicadas).

Cada transferência fica registada para os administradores da organização com o nome da aplicação, o ficheiro, a hora e parte do endereço IP: as últimas 5000, até 180 dias. O mesmo ficheiro transferido de novo em 10 minutos conta uma vez. A atividade do Files da organização mostra uma linha por dia para a sua aplicação. As transferências dos ficheiros próprios de uma pessoa aparecem nas Aplicações ligadas dela.

WebDAV

Para ferramentas de cópia de segurança que usam WebDAV, um administrador da organização cria um acesso WebDAV para a sua aplicação em Aplicações ligadas ao Files. A palavra-passe é mostrada uma vez, só é guardada como hash e nunca é a palavra-passe Dazr de alguém. O acesso segue a aprovação: as mesmas pastas, redes e limites, e para quando a aprovação é revogada.

Os nomes de pastas e ficheiros aparecem como estão no Dazr Files. Quando dois itens numa pasta têm o mesmo nome (sem distinguir maiúsculas), o mais antigo mantém-no e os outros recebem o seu id entre parênteses antes da extensão, para que cada item tenha o seu próprio caminho. Uma pasta com mais de 10 000 itens não pode ser listada por WebDAV; use a API para ela. Após 10 inícios de sessão falhados a partir de um endereço IP em 15 minutos, esse endereço espera 15 minutos.

rclone

1. Execute rclone config, escolha n para um novo remote, chame-lhe dazr e escolha o tipo de armazenamento webdav.
2. URL: https://files.dazr.eu/dav/. Vendor: other. User: o nome de utilizador (dzw_…). Password: escolha escrevê-la e cole a palavra-passe.
3. Deixe o bearer token vazio e guarde. Verifique com rclone lsd dazr: e faça a cópia.

# ~/.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

O rclone compara o tamanho e a hora de modificação. Use copy em vez de sync para manter na cópia os ficheiros eliminados no Dazr Files.

Synology Cloud Sync

1. Abra o Cloud Sync no NAS, adicione um fornecedor de cloud e escolha WebDAV.
2. Endereço do servidor: https://files.dazr.eu/dav/. Nome de utilizador e palavra-passe: o acesso WebDAV dado pelo administrador.
3. Escolha uma pasta local, a pasta remota / (ou uma pasta) e a direção de sincronização Download remote changes only.

Cloud Sync com WebDAV, direção de sincronização “Download remote changes only”. O Hyper Backup grava cópias em WebDAV, mas não consegue ler a partir dele.