Files API

Przegląd

Files API hostuje pliki w qr3 i udostępnia dla nich stały adres URL. Kod QR wskazuje na ten URL — powiązany plik możesz w każdej chwili wymienić bez konieczności ponownego drukowania kodu.

Bazowy URL: https://qr3.app/v1/files

Opcjonalnie możesz powiązać plik z kodem za pomocą code_id. Jest to podstawa dla strony docelowej dla kodu, która wyświetla listę wszystkich publicznych plików danego kodu.

Obsługiwane typy są weryfikowane na podstawie sygnatury pliku (magic bytes), a nie rozszerzenia: PDF, PNG, JPEG, WebP, MP4, glTF/GLB, JSON. Plik .pdf, który nie jest plikiem PDF, zostanie odrzucony.

Notatka

Należy odróżnić je od dokumentów DPP (Digital Product Passport): są one specyficzne dla DPP i powiązane z paszportem. Files API jest generyczne i może być powiązane z kodem lub z niczym.

Role

Operacja	Wymagana rola	Otrzymuje 403
Wszystkie GET	dowolna rola	—
POST /upload, PUT /:id	rola zapisu	viewer
DELETE /:id	rola usuwania	viewer, contributor

Wyjątkiem jest rola contributor: może ona tworzyć i modyfikować, ale nie może niczego usuwać.

Uwaga

Klucz Publishable Key (qr3_pk_) jest zawsze traktowany jako viewer, niezależnie od jego zakresów (scopes) — klucze osadzone po stronie klienta nigdy nie mogą przesyłać, zastępować ani usuwać plików. Przesyłanie plików wymaga klucza Secret Key lub Test Key z zakresem zapisu.

Przesyłanie pliku

POST /v1/files/upload

Oczekuje multipart/form-data.

Pole	Wymagane	Opis
file	Tak	Plik
code_id	Nie	Powiązanie z kodem (musi należeć do Workspace)
visibility	Nie	private (domyślnie) lub 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
});

Odpowiedź (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" }
}

Pole public_url jest ustawiane tylko przy visibility: "public" oraz status: "active". Adres ten nie wymaga uwierzytelniania i nadaje się bezpośrednio jako docelowy URL kodu QR.

Lista plików

GET /v1/files

Parametry zapytania (Query): code_id i visibility, oba opcjonalne. Zwraca aktywne pliki z Workspace, zaczynając od najnowszych.

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

Odpowiedź (HTTP 200):

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

Uwaga

Ten punkt końcowy (endpoint) różni się od standardowego formatu listy: nie obsługuje stronicowania (paginacji) i nie zwraca pola meta.pagination — zawsze zwracane są wszystkie pasujące wyniki.

Pola file_count i total_size_bytes odnoszą się do przefiltrowanej listy wyników, a nie do całego Workspace. Przy użyciu ?code_id=… lub ?visibility=… zliczają one tylko przefiltrowane pliki, więc nie nadają się do sprawdzania limitu pamięci dla danego planu.

Pobieranie informacji o pliku

GET /v1/files/:id

Zwraca metadane, w tym download_url (oraz public_url dla plików publicznych). Dostępne do odczytu dla wszystkich ról.

Pobieranie pliku

GET /v1/files/:id/download

Przesyła zawartość strumieniowo jako Content-Disposition: attachment z nagłówkiem Cache-Control: private, no-store — odpowiedź zawsze reprezentuje aktualny stan, w przeciwieństwie do buforowanego publicznego adresu URL /f/:id.

Błąd 404 może wystąpić w dwóch przypadkach: plik nie istnieje w Workspace (lub został usunięty) albo plik istnieje, ale brakuje zapisanego obiektu.

Zastępowanie pliku

PUT /v1/files/:id

Zastępuje zawartość pliku i zachowuje jego id — a tym samym publiczny adres /f/:id oraz download_url. Wydrukowany już kod QR pozostaje ważny.

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

Pola visibility, code_id i created_at pozostają bez zmian; filename, mime_type, size_bytes oraz hash_sha256 są aktualizowane. Limit rozmiaru pojedynczego pliku w planie obowiązuje tak samo jak przy przesyłaniu, a limit pamięci Workspace jest weryfikowany pod kątem różnicy w rozmiarze. Limit „liczby plików na kod” nie ma zastosowania, ponieważ nie jest dodawany nowy plik.

Notatka

Publiczny adres URL jest serwowany z nagłówkiem Cache-Control: public, max-age=300. Po zastąpieniu pliku, wersja buforowana przez CDN lub przeglądarkę może być widoczna jako stara wersja nawet przez 5 minut. Uwierzytelnione pobieranie korzysta z no-store i jest natychmiast aktualne.

Usuwanie pliku

DELETE /v1/files/:id

Miękkie usuwanie (soft-delete): plik natychmiast znika z listy, przestaje być dostępny i — jeśli był publiczny — nie jest już serwowany pod adresem /f/:id.

Odpowiedź (HTTP 200):

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

Uwaga

Usunięcie pliku nie oznacza natychmiastowego cofnięcia publikacji dla osób, które posiadają już bezpośredni link: adres /f/:id jest serwowany z parametrem max-age=300 i może wyświetlać plik jeszcze przez maksymalnie 5 minut. Z kolei strona docelowa nie jest buforowana i natychmiast przestaje wyświetlać ten plik.

Wywołanie to nie jest idempotentne — drugie żądanie DELETE dla tego samego pliku zwróci błąd 404.

Limity

Plan	Maks. na plik
Free	5 MB
Pro	25 MB
Business	100 MB
Agency	100 MB
Enterprise	250 MB

Dodatkowo dla każdego planu obowiązuje maksymalna liczba plików na kod oraz całkowity limit pamięci na Workspace. Limit częstotliwości przesyłania (rate limit) wynosi 100 przesłanych plików na godzinę na Workspace.

Błędy

Status	Kiedy
400	Nieznana lub niepasująca sygnatura pliku, nieprawidłowa zawartość multipart
401	Brak lub nieprawidłowy klucz API
403	Rola nie ma uprawnień do zapisu lub usuwania
404	code_id lub plik nie znajduje się w Workspace; przy pobieraniu również: brak obiektu w pamięci
413	Plik jest większy niż limit planu
422	Brak pliku, nieprawidłowa wartość visibility, osiągnięto limit „liczby plików na kod”, przekroczono limit pamięci Workspace
429	Limit częstotliwości przesyłania (100/godzinę/Workspace) lub ogólny limit częstotliwości (rate limit)

Powiązane tematy

• Pliki i karty danych — ścieżka przez Dashboard
• Strona docelowa dla kodu