Files API

Översikt

Files-API:n hostar filer hos qr3 och levererar en stabil URL för detta. QR-koden pekar på denna URL — filen bakom kan du när som helst byta ut utan att behöva trycka om koden.

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

Om du vill kan du koppla en fil till en kod via code_id. Detta är grunden för landningssida per kod, som listar alla offentliga filer för en kod.

Typer som stöds kontrolleras via magic bytes, inte på filnamnet: PDF, PNG, JPEG, WebP, MP4, glTF/GLB, JSON. En .pdf som inte är en PDF nekas.

Note

Bör särskiljas från DPP-dokument (Digital Product Passport): Dessa är DPP-specifika och bundna till ett Passport. Files-API:n är generisk och bunden till en kod eller inte bunden till någonting alls.

Roller

Operation	Krävs	Får 403
Alla GET	alla roller	—
POST /upload, PUT /:id	skrivroll	viewer
DELETE /:id	raderingsroll	viewer, contributor

Specialregeln är contributor: rollen får skapa och ändra, men inte ta bort något.

Caution

En Publishable Key (qr3_pk_) är oavsett sina scopes alltid viewer — klientinbäddade nycklar kan alltså aldrig ladda upp, ersätta eller radera. Uppladdningar kräver en Secret- eller Test-Key med skriv-scope.

Ladda upp fil

POST /v1/files/upload

Förväntar sig multipart/form-data.

Fält	Obligatoriskt	Beskrivning
file	Ja	Filen
code_id	Nej	Koppla till en kod (måste tillhöra workspacet)
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
});

Svar (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 är endast satt vid visibility: "public" och status: "active". Adressen kräver ingen inloggning och lämpar sig direkt som mål-URL för en QR-kod.

Lista filer

GET /v1/files

Query: code_id och visibility, båda valfria. Returnerar de aktiva filerna i workspacet, med de senaste först.

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

Svar (HTTP 200):

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

Caution

Denna endpoint avviker från standardformatet för listor: den är inte paginerad och returnerar inte meta.pagination — alla matchningar returneras alltid.

file_count och total_size_bytes avser den filtrerade resultatmängden, inte workspacet som helhet. Med ?code_id=… eller ?visibility=… räknar de endast de filtrerade filerna och kan därför inte användas för att kontrollera lagringsstatusen mot abonnemangsgränsen.

Hämta filinformation

GET /v1/files/:id

Returnerar metadata inklusive download_url (och public_url för offentliga filer). Läsbar för alla roller.

Ladda ner fil

GET /v1/files/:id/download

Strömmar innehållet som Content-Disposition: attachment med Cache-Control: private, no-store — svaret är alltså alltid den aktuella versionen, till skillnad från den cachade offentliga /f/:id-URL:en.

404 kan uppstå på två sätt: filen finns inte i workspacet (eller är raderad), eller så finns den men det lagrade objektet saknas.

Ersätt fil

PUT /v1/files/:id

Ersätter innehållet och behåller id — och därmed den offentliga /f/:id- och download_url-adressen. En redan tryckt QR-kod förblir giltig.

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

visibility, code_id och created_at behålls; filename, mime_type, size_bytes och hash_sha256 uppdateras. Abonnemangsgränsen per fil gäller på samma sätt som vid uppladdning, och workspacets lagringsgräns kontrolleras mot differensen. Gränsen “filer per kod” gäller inte, eftersom ingen ny fil läggs till.

Note

Den offentliga URL:en levereras med Cache-Control: public, max-age=300. Efter ett byte kan en cachad version i CDN eller webbläsare därför visa den gamla filen i upp till 5 minuter. Den autentiserade nedladdningen är no-store och uppdateras omedelbart.

Radera fil

DELETE /v1/files/:id

Mjuk radering (soft-delete): Filen försvinner omedelbart från listan, kan inte längre hämtas och levereras — om den är offentlig — inte längre under /f/:id.

Svar (HTTP 200):

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

Caution

En radering innebär inte en omedelbar avpublicering för någon som redan har den direkta länken: /f/:id levereras med max-age=300 och kan visa filen i upp till 5 minuter till. Landningssidan cachas däremot inte och slutar visa filen omedelbart.

Anropet är inte idempotent — ett andra DELETE på samma fil ger 404.

Gränser

Plan	Max per fil
Free	5 MB
Pro	25 MB
Business	100 MB
Agency	100 MB
Enterprise	250 MB

Dessutom gäller för varje plan ett maximalt antal filer per kod och ett totalt lagringsutrymme per workspace. Gränsen för uppladdningshastighet (rate limit) är 100 uppladdningar per timme och workspace.

Fel

Status	När
400	Okänd eller icke-matchande filsignatur, ogiltig multipart-body
401	Saknad eller ogiltig API-nyckel
403	Rollen får inte skriva respektive inte radera
404	code_id eller filen finns inte i workspacet; vid nedladdning även: objektet saknas i lagringen
413	Filen är större än planens gräns
422	Filen saknas, ogiltig visibility, gränsen “filer per kod” har nåtts, workspacets lagringsgräns har överskridits
429	Gräns för uppladdningshastighet (100/timme/workspace) eller allmän hastighetsbegränsning

Relaterat

• Filer & datablad — vägen via instrumentpanelen
• Landningssida per kod