API Files

Aperçu

L’API Files héberge des fichiers sur qr3 et fournit une URL stable. Le code QR pointe vers cette URL — vous pouvez remplacer le fichier sous-jacent à tout moment, sans avoir à réimprimer le code.

URL de base : https://qr3.app/v1/files

Optionnellement, vous pouvez associer un fichier à un code via code_id. C’est la base de la page de destination par code qui liste tous les fichiers publics d’un code.

Les types pris en charge sont vérifiés par magic byte, et non par l’extension du fichier : PDF, PNG, JPEG, WebP, MP4, glTF/GLB, JSON. Un fichier .pdf qui n’est pas un PDF sera rejeté.

Note

À distinguer des documents DPP (Digital Product Passport) : ceux-ci sont spécifiques au DPP et liés à un passeport. L’API Files est générique et liée à un code ou à rien du tout.

Rôles

Opération	Requis	Reçoit 403
Tous les GET	n’importe quel rôle	—
POST /upload, PUT /:id	rôle d’écriture	viewer
DELETE /:id	rôle de suppression	viewer, contributor

La règle spéciale concerne contributor : ce rôle peut créer et modifier, mais ne peut rien supprimer.

Attention

Une clé publiable (qr3_pk_) est toujours viewer, quels que soient ses scopes — les clés intégrées côté client ne peuvent donc jamais téléverser, remplacer ou supprimer. Les téléversements nécessitent une clé secrète ou de test avec un scope d’écriture.

Téléverser un fichier

POST /v1/files/upload

Attend du multipart/form-data.

Champ	Requis	Description
file	Oui	Le fichier
code_id	Non	Associer à un code (doit appartenir au Workspace)
visibility	Non	private (par défaut) ou public

cURL

curl -X POST https://qr3.app/v1/files/upload \
  -H "Authorization: Bearer qr3_sk_..." \
  -F "[email protected]" \
  -F "code_id=qr_a1b2c3d4" \
  -F "visibility=public"

JavaScript

const form = new FormData();
form.append('file', fileInput.files[0]);
form.append('code_id', 'qr_a1b2c3d4');
form.append('visibility', 'public');

const res = await fetch('https://qr3.app/v1/files/upload', {
  method: 'POST',
  headers: { Authorization: 'Bearer qr3_sk_...' },
  body: form, // Content-Type NICHT selbst setzen — der Boundary fehlt sonst
});

Réponse (HTTP 201) :

{
  "data": {
    "id": "file_a1b2c3d4",
    "code_id": "qr_a1b2c3d4",
    "filename": "datenblatt.pdf",
    "mime_type": "application/pdf",
    "size_bytes": 284913,
    "hash_sha256": "9f86d081884c7d65…",
    "visibility": "public",
    "status": "active",
    "created_at": "2026-03-14T12:00:00.000Z",
    "download_url": "https://qr3.app/v1/files/file_a1b2c3d4/download",
    "public_url": "https://qr3.app/f/file_a1b2c3d4"
  },
  "meta": { "request_id": "req_abc123" }
}

public_url est définie uniquement si visibility: "public" et status: "active". L’adresse ne nécessite aucune authentification et convient directement comme URL de destination d’un code QR.

Lister les fichiers

GET /v1/files

Requête : code_id et visibility, tous deux optionnels. Renvoie les fichiers actifs du Workspace, les plus récents en premier.

curl "https://qr3.app/v1/files?code_id=qr_a1b2c3d4" \
  -H "Authorization: Bearer qr3_sk_..."

Réponse (HTTP 200) :

{
  "data": [ { "id": "file_a1b2c3d4", "…": "…" } ],
  "meta": {
    "request_id": "req_abc123",
    "file_count": 3,
    "total_size_bytes": 812004
  }
}

Attention

Ce point de terminaison diffère du format de liste standard : il n’est pas paginé et ne renvoie pas de meta.pagination — tous les résultats correspondants sont toujours renvoyés.

file_count et total_size_bytes se rapportent à l’ensemble des résultats filtrés, et non au Workspace dans son ensemble. Avec ?code_id=… ou ?visibility=…, ils ne comptent que les fichiers filtrés et ne peuvent donc pas servir à mesurer l’utilisation de la limite du forfait.

Récupérer les informations d’un fichier

GET /v1/files/:id

Renvoie les métadonnées, y compris download_url (et public_url pour les fichiers publics). Lisible par tous les rôles.

Télécharger un fichier

GET /v1/files/:id/download

Diffuse le contenu en tant que Content-Disposition: attachment avec Cache-Control: private, no-store — la réponse correspond donc toujours à l’état le plus récent, contrairement à l’URL publique /f/:id mise en cache.

Une erreur 404 peut survenir de deux manières : le fichier n’existe pas dans le Workspace (ou a été supprimé), ou il existe mais l’objet stocké est manquant.

Remplacer un fichier

PUT /v1/files/:id

Remplace le contenu et conserve l’ id — et donc l’adresse publique /f/:id ainsi que la download_url. Un code QR déjà imprimé reste valide.

curl -X PUT https://qr3.app/v1/files/file_a1b2c3d4 \
  -H "Authorization: Bearer qr3_sk_..." \
  -F "[email protected]"

visibility, code_id et created_at sont conservés ; filename, mime_type, size_bytes et hash_sha256 sont mis à jour. La limite du forfait par fichier s’applique comme pour le téléversement, et la limite de stockage du Workspace est vérifiée par rapport à la différence. La limite du « nombre de fichiers par code » ne s’applique pas, car aucun nouveau fichier n’est ajouté.

Note

L’URL publique est servie avec Cache-Control: public, max-age=300. Après un remplacement, une version mise en cache par un CDN ou un navigateur peut donc continuer à afficher l’ancien fichier pendant un maximum de 5 minutes. Le téléchargement authentifié utilise no-store et est immédiatement à jour.

Supprimer un fichier

DELETE /v1/files/:id

Suppression logique (soft-delete) : le fichier disparaît immédiatement de la liste, n’est plus accessible et — s’il est public — n’est plus servi à l’adresse /f/:id.

Réponse (HTTP 200) :

{
  "data": { "id": "file_a1b2c3d4", "deleted": true },
  "meta": { "request_id": "req_abc123" }
}

Attention

Une suppression ne constitue pas un retrait immédiat de la publication pour une personne disposant déjà du lien direct : /f/:id est servi avec max-age=300 et peut continuer à afficher le fichier pendant un maximum de 5 minutes. En revanche, la page de destination n’est pas mise en cache et cesse immédiatement d’afficher le fichier.

L’appel n’est pas idempotent — un second DELETE sur le même fichier renvoie une erreur 404.

Limites

Forfait	Max. par fichier
Free	5 MB
Pro	25 MB
Business	100 MB
Agency	100 MB
Enterprise	250 MB

De plus, un nombre maximal de fichiers par code et un espace de stockage total par Workspace s’appliquent selon le forfait. La limite de taux de téléversement est de 100 téléversements par heure et par Workspace.

Erreurs

Statut	Quand
400	Signature de fichier inconnue ou non correspondante, corps multipart invalide
401	Clé API manquante ou invalide
403	Le rôle n’est pas autorisé à écrire ou à supprimer
404	code_id ou fichier absent du Workspace ; lors du téléchargement également : objet manquant dans le stockage
413	Fichier plus grand que la limite du forfait
422	Fichier manquant, visibility invalide, limite du « nombre de fichiers par code » atteinte, limite de stockage du Workspace dépassée
429	Limite de taux de téléversement (100/heure/Workspace) ou limite de taux générale

Voir aussi

• Fichiers & fiches techniques — la méthode via le tableau de bord
• Page de destination par code