API Nextcloud : automatiser les fichiers et utilisateurs en 2026

Une application métier doit déposer ses factures, partager un dossier ou préparer l'arrivée d'un collaborateur sans passer par un navigateur. En 2026, l'API Nextcloud répartit ces scénarios entre WebDAV pour les fichiers et les API OCS pour les partages, les utilisateurs et les groupes.

Ce guide construit un premier flux avec curl, puis traite les points qui provoquent les incidents réels : choix de l'interface, authentification, réponse XML ou JSON, écrasement involontaire, gros fichiers, droits d'administration et gestion des secrets. Les commandes utilisent des valeurs fictives. Exécutez-les d'abord sur des comptes et dossiers de test.

WebDAV ou API OCS : quelle interface utiliser ?

WebDAV étend HTTP pour agir sur des fichiers et leurs propriétés. Dans Nextcloud 34, l'URL de base authentifiée est /remote.php/dav. Les fichiers d'un utilisateur se trouvent habituellement sous /remote.php/dav/files/{user}/. Une requête vise donc une ressource précise dans l'arborescence du compte connecté.

L'API OCS répond à d'autres besoins. Elle sert notamment à créer ou modifier un partage, interroger des utilisateurs ou lire des capacités de l'instance. L'API de partage OCS utilise la base /ocs/v2.php/apps/files_sharing/api/v1 et exige l'en-tête OCS-APIRequest: true. Un flux peut employer WebDAV pour déposer un PDF, puis OCS pour partager ce chemin avec un groupe.

Besoin	Interface adaptée	Méthode courante
Lister un dossier	WebDAV	PROPFIND
Télécharger un fichier	WebDAV	GET
Envoyer ou remplacer un fichier	WebDAV	PUT
Créer un dossier	WebDAV	MKCOL
Déplacer ou renommer	WebDAV	MOVE
Copier	WebDAV	COPY
Supprimer	WebDAV	DELETE
Créer un partage	OCS Share API	POST
Lister ou gérer des comptes	OCS Provisioning API	GET, POST, PUT, DELETE

Le guide complet de Nextcloud présente Files et les applications de la plateforme. Ici, l'objectif n'est pas de synchroniser tout un poste, mais de relier un processus précis à un répertoire maîtrisé.

Un lien public possède un autre endpoint : /public.php/dav/files/{share_token}, disponible depuis Nextcloud 29 selon le manuel développeur. Si le partage est protégé, l'authentification Basic utilise anonymous comme nom d'utilisateur et le mot de passe du lien comme secret. Les requêtes non GET, telles que PROPFIND ou PUT, doivent aussi fournir X-Requested-With: XMLHttpRequest, sauf si le partage sortant entre serveurs est activé sur l'instance. Sans cet en-tête, le serveur renvoie 401 Not Authenticated.

N'utilisez pas un lien public comme raccourci pour un traitement interne permanent. Sa durée, son mot de passe et ses permissions répondent au partage avec un destinataire, tandis qu'un compte technique offre une identité révocable et une arborescence délimitée. Si le besoin consiste à recevoir des pièces externes, testez le partage dans un dossier dédié et vérifiez que le téléchargement, la liste et l'écriture correspondent exactement aux droits attendus.

Comment préparer un accès API sans exposer le compte principal ?

Créez un compte de service distinct lorsque l'organisation peut en assurer le propriétaire, les droits et la révocation. Partagez-lui seulement le dossier nécessaire. N'utilisez pas le compte administrateur de l'instance : WebDAV exécute chaque opération avec les autorisations du compte authentifié, y compris une suppression récursive autorisée.

Générez ensuite un secret propre à cette intégration. Le guide du mot de passe d'application Nextcloud détaille la création et la révocation. Cette séparation permet de couper le connecteur sans changer le mot de passe principal ni déconnecter les autres appareils. Elle est aussi nécessaire pour de nombreux accès directs lorsque la 2FA est imposée.

Préparez ces trois variables fictives pour les exemples :

NC_URL="https://cloud.exemple.fr"
NC_USER="robot-factures"
NC_APP_PASSWORD="MOT_DE_PASSE_APPLICATION"

Ne placez pas le secret réel dans un dépôt, un fichier livré avec l'application ou une ligne de commande conservée dans l'historique. Pour un test local, chargez-le depuis un fichier protégé ou un gestionnaire de secrets. En production, injectez-le au moment de l'exécution et empêchez les journaux d'afficher les en-têtes d'authentification.

Comment automatiser les utilisateurs et groupes avec OCS ?

L'application Provisioning API expose la base /ocs/v1.php/cloud. Elle permet à un système externe de créer, lire, modifier, désactiver ou supprimer des utilisateurs, d'agir sur leurs groupes et leurs quotas, et d'interroger les applications actives. Chaque appel OCS doit fournir OCS-APIRequest: true. Ajoutez Accept: application/json pour obtenir une réponse homogène, car certains endpoints historiques utilisent XML par défaut.

Une simple liste illustre le format sans modifier l'instance :

curl --fail-with-body \
  --user "$NC_ADMIN_USER:$NC_ADMIN_APP_PASSWORD" \
  --request GET \
  --header "OCS-APIRequest: true" \
  --header "Accept: application/json" \
  "$NC_URL/ocs/v1.php/cloud/users?search=martin&limit=50&offset=0"

Cette requête ne doit pas réutiliser le compte WebDAV limité aux factures. La documentation réserve plusieurs actions de provisioning à un administrateur. Un sous-administrateur de groupe peut gérer les groupes dont il a la charge, ce qui réduit le périmètre. Créez donc une identité séparée pour l'annuaire, avec son propre mot de passe d'application, puis vérifiez chaque opération sur un groupe pilote.

Avant un POST de création, recherchez l'identifiant exact et conservez la correspondance avec l'identifiant du logiciel RH. Une relance ne doit pas créer un second compte sous un nom approchant. Pour un départ, distinguez la désactivation, qui bloque la connexion, de la suppression, qui retire le compte. Définissez séparément le transfert ou la conservation des données, puis contrôlez le statut OCS dans le corps de la réponse en plus du code HTTP.

Comment lister un dossier et lire les propriétés ?

PROPFIND retourne les ressources et propriétés DAV demandées. Pour examiner uniquement le dossier lui-même, ajoutez Depth: 0. Avec Depth: 1, le serveur inclut ses enfants directs. Évitez une profondeur non bornée sur une grande arborescence : demandez le niveau utile, puis parcourez les sous-dossiers de façon contrôlée.

Cette commande demande le nom, le type, la date de modification, la taille et l'ETag des éléments de Factures :

curl --fail-with-body \
  --user "$NC_USER:$NC_APP_PASSWORD" \
  --request PROPFIND \
  --header "Depth: 1" \
  --header "Content-Type: application/xml" \
  --data '<?xml version="1.0"?>
    <d:propfind xmlns:d="DAV:">
      <d:prop>
        <d:displayname/>
        <d:resourcetype/>
        <d:getlastmodified/>
        <d:getcontentlength/>
        <d:getetag/>
      </d:prop>
    </d:propfind>' \
  "$NC_URL/remote.php/dav/files/$NC_USER/Factures/"

Une réponse réussie à PROPFIND prend généralement la forme d'un 207 Multi-Status. Le corps XML contient plusieurs blocs response, et une propriété absente peut avoir son propre statut. Un script ne doit donc pas se contenter de rechercher un nom de fichier dans le texte. Il doit parser l'espace de noms DAV:, vérifier chaque statut puis enregistrer le chemin, l'ETag et la taille attendus.

L'ETag est un identifiant de version renvoyé par le serveur. Conservez-le avec l'identifiant de votre objet métier pour reconnaître une modification entre deux lectures. La documentation expose aussi oc:fileid, un identifiant unique dans l'instance, ainsi que les permissions, le propriétaire et les types de partage. Ne demandez que les propriétés réellement utilisées afin de limiter le volume XML.

Comment créer, envoyer et déplacer un fichier ?

Créez d'abord le dossier cible avec MKCOL. Un second appel sur un dossier déjà présent doit être traité comme un cas prévu par votre code, pas comme une raison de relancer toutes les étapes sans contrôle.

curl --fail-with-body \
  --user "$NC_USER:$NC_APP_PASSWORD" \
  --request MKCOL \
  "$NC_URL/remote.php/dav/files/$NC_USER/Factures/2026-09/"

L'envoi utilise PUT avec le contenu binaire du fichier. Attention, un PUT sur un chemin déjà occupé remplace le fichier. Vérifiez le nom cible, interrogez la ressource au préalable et choisissez une convention déterministe, par exemple l'identifiant immuable de la facture plutôt qu'un titre saisi librement.

curl --fail-with-body \
  --user "$NC_USER:$NC_APP_PASSWORD" \
  --request PUT \
  --header "Content-Type: application/pdf" \
  --data-binary "@facture-2026-0098.pdf" \
  "$NC_URL/remote.php/dav/files/$NC_USER/Factures/2026-09/facture-2026-0098.pdf"

Après la réponse, lisez les en-têtes OC-Etag et OC-FileId documentés par Nextcloud, puis faites un PROPFIND de contrôle. N'interprétez pas OC-Checksum comme une preuve automatique de contenu lors d'un PUT classique : la documentation indique que cette valeur est alors stockée sans validation. Si l'intégrité est requise, calculez votre propre empreinte et vérifiez aussi le fichier récupéré.

Pour déplacer la ressource, envoyez MOVE et une URL absolue dans Destination. La valeur d'écrasement par défaut est T. Ajoutez Overwrite: F lorsque le flux doit échouer plutôt que remplacer un fichier existant.

curl --fail-with-body \
  --user "$NC_USER:$NC_APP_PASSWORD" \
  --request MOVE \
  --header "Destination: $NC_URL/remote.php/dav/files/$NC_USER/Archives/facture-2026-0098.pdf" \
  --header "Overwrite: F" \
  "$NC_URL/remote.php/dav/files/$NC_USER/Factures/2026-09/facture-2026-0098.pdf"

Le compte technique limite l'accès, WebDAV transporte les opérations et le stockage conserve les fichiers ainsi que leurs propriétés.

Comment fiabiliser les gros fichiers et les reprises ?

Un unique PUT oblige souvent à recommencer après une coupure. Nextcloud 34 documente un téléversement découpé v2, recommandé par rapport à la première version et compatible avec les stockages cibles qui prennent en charge ce mode, notamment certains stockages objet. Il utilise /remote.php/dav/uploads/{userid} avant un MOVE final vers le fichier cible.

Le client crée un dossier d'envoi au nom unique, dépose les blocs par PUT, puis demande l'assemblage avec MOVE. Les noms de blocs sont compris entre 1 et 10 000 et déterminent l'ordre d'assemblage. Chaque bloc mesure entre 5 Mo et 5 Go, sauf le dernier qui peut être plus petit. Un dossier sans activité expire après 24 heures.

Fournissez OC-Total-Length dès les blocs. Le serveur peut alors refuser tôt l'opération avec 507 Insufficient Storage si le quota restant ne suffit pas. Sans cette taille totale, l'échec peut n'arriver qu'à l'assemblage final. En cas d'abandon, supprimez le dossier d'envoi temporaire avec DELETE.

Pour de nombreux petits fichiers, Nextcloud expose aussi un envoi groupé à /remote.php/dav/bulk. N'activez pas cette optimisation par intuition. Mesurez d'abord le flux ordinaire, vérifiez que votre version documente l'endpoint et testez les réponses partielles avant de l'introduire.

Quels contrôles effectuer avant la production ?

Recettez le connecteur avec un compte standard et un dossier jetable. Testez la création, un PUT, une liste, un téléchargement, un déplacement et la suppression d'un fichier. Ajoutez les cas d'échec : secret révoqué, quota épuisé, dossier absent, nom déjà utilisé, destination interdite, coupure pendant l'envoi et XML partiellement exploitable.

La suppression mérite une règle spécifique. DELETE appliqué à un dossier supprime récursivement son contenu. Le connecteur doit donc interdire les chemins racines, comparer le préfixe autorisé et demander une preuve d'état avant une opération destructive. Pour un archivage, préférez d'abord un MOVE vers un dossier isolé, puis une purge effectuée par une politique distincte.

Le guide de sécurité Nextcloud complète cette recette pour la 2FA, les mises à jour, les journaux et les sauvegardes. Si l'automatisation enchaîne plusieurs applications, Nextcloud Flow peut couvrir des règles internes déclenchées par les fichiers, tandis que WebDAV reste adapté à un système externe qui lit ou écrit réellement leur contenu.

Avant la mise en service, consignez :

• le propriétaire métier et technique du connecteur ;
• le compte, le dossier et les méthodes HTTP autorisés ;
• l'emplacement du secret et sa procédure de rotation ;
• les délais, tentatives et erreurs qui déclenchent une alerte ;
• le comportement d'écrasement, d'archivage et de suppression ;
• la taille maximale testée et la stratégie de reprise ;
• la preuve qu'une restauration du dossier est possible.

Conclusion

L'API Nextcloud ne forme pas un endpoint unique. WebDAV gère le contenu des fichiers, l'API OCS de partage distribue un chemin, et la Provisioning API pilote les utilisateurs et groupes. Une intégration fiable choisit l'interface exacte, sépare les identités techniques, limite les droits, contrôle le corps des réponses et rend chaque relance prévisible. Commencez sur un dossier et un groupe pilotes, puis bloquez les suppressions hors périmètre avant de connecter l'application métier.

Étudier l'offre Nextcloud GaprodEspace Nextcloud géré et hébergé en France

Sources officielles

• Opérations WebDAV de base, Nextcloud 34
• Téléversement découpé v2, Nextcloud 34
• Recherche WebDAV, Nextcloud 34
• Envoi groupé de fichiers, Nextcloud 34
• API de partage OCS, Nextcloud 34
• Présentation des API OCS, Nextcloud 34
• Provisioning des utilisateurs et groupes, Nextcloud 34
• Login Flow et secrets d'application, Nextcloud 34
• RFC 4918, protocole WebDAV