Files API

Oversigt

Files-API’en hoster filer hos qr3 og leverer en stabil URL til formålet. QR-koden peger på denne URL — du kan til enhver tid udskifte filen bagved uden at genprinte koden.

Basis-URL: https://qr3.app/v1/files

Du kan valgfrit knytte en fil til en kode via code_id. Dette er grundlaget for en landingsside pr. kode, som viser alle offentlige filer for en kode.

Understøttede typer kontrolleres via magic bytes, ikke på filnavnet: PDF, PNG, JPEG, WebP, MP4, glTF/GLB, JSON. En .pdf, der ikke er en PDF, afvises.

Note

Skal skelnes fra DPP-dokumenter (Digital Product Passport): Disse er DPP-specifikke og bundet til et Passport. Files-API’en er generisk og bundet til en kode eller slet ingenting.

Roller

Operation	Påkrævet	Modtager 403
Alle GET	enhver rolle	—
POST /upload, PUT /:id	skriverolle	viewer
DELETE /:id	sletterolle	viewer, contributor

Særreglen er contributor: Rollen må oprette og redigere, men ikke fjerne noget.

Caution

En Publishable Key (qr3_pk_) er uanset sine scopes altid viewer — klient-integrerede nøgler kan altså aldrig uploade, erstatte eller slette. Uploads kræver en Secret- eller Test-Key med skrive-scope.

Upload fil

POST /v1/files/upload

Forventer multipart/form-data.

Felt	Påkrævet	Beskrivelse
file	Ja	Filen
code_id	Nej	Knyt til en kode (skal tilhøre dit workspace)
visibility	Nej	private (standard) eller 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
});

Response (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 er kun sat ved visibility: "public" og status: "active". Adressen kræver ingen login og er direkte velegnet som destinations-URL for en QR-kode.

Vis filer

GET /v1/files

Query: code_id og visibility, begge valgfrie. Returnerer de aktive filer i dit workspace, med de nyeste først.

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

Response (HTTP 200):

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

Caution

Dette slutpunkt afviger fra det standardiserede listeformat: Det er ikke pagineret og returnerer ikke meta.pagination — alle resultater returneres altid på én gang.

file_count og total_size_bytes refererer til den filtrerede resultatmængde, ikke til dit workspace som helhed. Med ?code_id=… eller ?visibility=… tæller de kun de filtrerede filer og kan derfor ikke bruges til at aflæse det samlede forbrug i forhold til abonnementets grænser.

Hent filoplysninger

GET /v1/files/:id

Returnerer metadata inklusive download_url (og public_url for offentlige filer). Kan læses af alle roller.

Download fil

GET /v1/files/:id/download

Streamer indholdet som Content-Disposition: attachment med Cache-Control: private, no-store — svaret er altså altid den nyeste version, i modsætning til den cachede offentlige /f/:id-URL.

404 kan opstå på to måder: Filen eksisterer ikke i dit workspace (oder er slettet), eller den eksisterer, men det gemte objekt mangler.

Erstat fil

PUT /v1/files/:id

Udskifter indholdet og beholder id’et — og dermed den offentlige /f/:id- og download_url-adresse. En allerede printet QR-kode forbliver gyldig.

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

visibility, code_id og created_at bevares; filename, mime_type, size_bytes og hash_sha256 opdateres. Abonnementsgrænsen pr. fil gælder ligesom ved upload, og workspacets lagergrænse kontrolleres mod forskellen. Grænsen “filer pr. kode” gælder ikke, da der ikke tilføjes en ny fil.

Note

Den offentlige URL leveres med Cache-Control: public, max-age=300. Efter en udskiftning kan en cachet CDN- eller browser-version derfor vise den gamle fil i op til 5 minutter. Det autentificerede download er no-store og opdateres med det samme.

Slet fil

DELETE /v1/files/:id

Soft-delete: Filen forsvinder med det samme fra listen, kan ikke længere hentes og leveres — hvis den er offentlig — ikke længere under /f/:id.

Response (HTTP 200):

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

Caution

En sletning betyder ikke øjeblikkelig afpublicering for en person, der allerede har det direkte link: /f/:id leveres med max-age=300 og kan vise filen i op til 5 minutter endnu. Landingssiden caches derimod ikke og holder straks op med at vise filen.

Kaldet er ikke idempotent — et andet DELETE på samme fil returnerer 404.

Grænser

Abonnement	Maks. pr. fil
Free	5 MB
Pro	25 MB
Business	100 MB
Agency	100 MB
Enterprise	250 MB

Derudover gælder der for hvert abonnement et maksimalt antal filer pr. kode og en samlet lagerplads pr. workspace. Upload-hastighedsgrænsen (rate limit) er 100 uploads pr. time pr. workspace.

Fejl

Status	Hvornår
400	Ukendt eller ikke-matchende filsignatur, ugyldig multipart-body
401	Manglende eller ugyldig API-nøgle
403	Rollen må ikke skrive eller slette
404	code_id eller filen findes ikke i workspacet; ved download også: objektet mangler på lageret
413	Filen er større end abonnementsgrænsen
422	Filen mangler, ugyldig visibility, grænsen “filer pr. kode” er nået, workspacets lagergrænse er overskredet
429	Upload-hastighedsgrænse (100/time/workspace) eller generel hastighedsgrænse

Relateret

• Filer & datablade — vejen via dashboardet
• Landingsside pr. kode