Files API

Pārskats

Files API izvieto failus vietnē qr3 un nodrošina tiem stabilu URL. QR kods norāda uz šo URL — aiz tā esošo failu varat nomainīt jebkurā laikā, neizdrukājot kodu no jauna.

Bāzes URL: https://qr3.app/v1/files

Pēc izvēles varat piesaistīt failu kodam, izmantojot code_id. Tas ir pamats mērķlapai katram kodam, kurā ir uzskaitīti visi koda publiskie faili.

Atbalstītie tipi tiek pārbaudīti pēc magic byte, nevis pēc faila nosaukuma paplašinājuma: PDF, PNG, JPEG, WebP, MP4, glTF/GLB, JSON. Fails ar paplašinājumu .pdf, kas nav PDF fails, tiks noraidīts.

Note

Jānošķir no DPP dokumentiem (Digital Product Passport): tie ir specifiski DPP un piesaistīti konkrētai pasei. Files API ir vispārīga un ir piesaistīta kodam vai nav piesaistīta nekam.

Lomas

Operācija	Nepieciešams	Saņem 403
Visi GET	jebkura loma	—
POST /upload, PUT /:id	rakstīšanas loma	viewer
DELETE /:id	dzēšanas loma	viewer, contributor

Īpašais noteikums attiecas uz contributor: šī loma drīkst izveidot un mainīt, bet nevar neko dzēst.

Caution

Publishable Key (qr3_pk_) neatkarīgi no tā apgabaliem (scopes) vienmēr ir viewer — tādējādi klienta pusē iegultie atslēgu kodi nekad nevar augšupielādēt, aizstāt vai dzēst. Augšupielādei ir nepieciešama Secret vai Test atslēga ar rakstīšanas apgabalu (scope).

Faila augšupielāde

POST /v1/files/upload

Sagaida multipart/form-data.

Lauks	Obligāts	Apraksts
file	Jā	Fails
code_id	Nē	Piesaistīt kodam (jāpieder darba videi)
visibility	Nē	private (noklusējums) vai 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
});

Atbilde (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 ir iestatīts tikai tad, ja visibility: "public" un status: "active". Šai adresei nav nepieciešama autentifikācija, un tā ir tieši piemērota kā QR koda mērķa URL.

Failu saraksts

GET /v1/files

Query parametri: code_id un visibility, abi nav obligāti. Atgriež darba vides aktīvos failus, sākot ar jaunākajiem.

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

Atbilde (HTTP 200):

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

Caution

Šis galapunkts (endpoint) atšķiras no standarta saraksta formāta: tam nav lapošanas (pagination) un tas neatgriež meta.pagination — vienmēr tiek atgriezti visi rezultāti.

file_count un total_size_bytes attiecas uz filtrēto rezultātu kopu, nevis uz darba vidi kopumā. Izmantojot ?code_id=… vai ?visibility=…, tie uzskaita tikai filtrētos failus un tāpēc nav izmantojami, lai pārbaudītu plāna ierobežojumu kopējo krātuves apjomu.

Faila informācijas iegūšana

GET /v1/files/:id

Atgriež metadatus, tostarp download_url (un public_url publiskiem failiem). Pieejams lasīšanai visām lomām.

Faila lejupielāde

GET /v1/files/:id/download

Straumē saturu kā Content-Disposition: attachment ar Cache-Control: private, no-store — tādējādi atbilde vienmēr ir pašreizējais stāvoklis, atšķirībā no kešatmiņā saglabātā publiskā /f/:id URL.

404 kļūda tiek atgriezta divos gadījumos: fails neeksistē darba vidē (vai ir dzēsts) vai tas eksistē, bet trūkst saglabātā objekta.

Faila aizstāšana

PUT /v1/files/:id

Aizstāj saturu un saglabā id — un līdz ar to arī publisko /f/:id un download_url adresi. Jau izdrukāts QR kods joprojām paliek derīgs.

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

visibility, code_id un created_at tiek saglabāti; filename, mime_type, size_bytes un hash_sha256 tiek atjaunināti. Plāna ierobežojums vienam failam tiek piemērots tāpat kā augšupielādei, un darba vides krātuves ierobežojums tiek pārbaudīts pret starpību. Ierobežojums “failu skaits vienam kodam” netiek piemērots, jo jauns fails netiek pievienots.

Note

Publiskais URL tiek nodrošināts ar Cache-Control: public, max-age=300. Tāpēc pēc aizstāšanas kešatmiņā saglabātais CDN vai pārlūkprogrammas stāvoklis līdz pat 5 minūtēm var rādīt veco failu. Autentificētā lejupielāde izmanto no-store un ir uzreiz aktuāla.

Faila dzēšana

DELETE /v1/files/:id

Mīkstā dzēšana (Soft-Delete): fails nekavējoties pazūd no saraksta, vairs nav pieejams un — ja tas ir publisks — vairs netiek nodrošināts adresē /f/:id.

Atbilde (HTTP 200):

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

Caution

Dzēšana nav tūlītēja publikācijas atcelšana kādam, kuram jau ir tiešā saite: /f/:id tiek nodrošināts ar max-age=300 un var rādīt failu vēl līdz 5 minūtēm. Turpretī mērķlapa netiek saglabāta kešatmiņā un uzreiz pārtrauc faila rādīšanu.

Izsaukums nav idempotents — otrs DELETE pieprasījums tam pašam failam atgriezīs 404.

Ierobežojumi

Plāns	Maks. vienam failam
Free	5 MB
Pro	25 MB
Business	100 MB
Agency	100 MB
Enterprise	250 MB

Papildus katram plānam tiek piemērots maksimālais failu skaits vienam kodam un kopējais krātuves apjoms vienai darba videi. Augšupielādes ātruma ierobežojums (rate limit) ir 100 augšupielādes stundā vienai darba videi.

Kļūdas

Statuss	Kad
400	Nezināms vai neatbilstošs faila paraksts, nederīgs multipart ķermenis (body)
401	Nav API atslēgas vai tā ir nederīga
403	Lomai nav atļauts rakstīt vai dzēst
404	code_id vai fails neatrodas darba vidē; lejupielādes gadījumā arī: objekts trūkst krātuvē
413	Fails ir lielāks par plāna ierobežojumu
422	Trūkst faila, nederīga visibility vērtība, sasniegts ierobežojums “failu skaits vienam kodam”, pārsniegts darba vides krātuves ierobežojums
429	Augšupielādes ātruma ierobežojums (100/stundā/darba videi) vai vispārējais ātruma ierobežojums (rate limit)

Saistītās tēmas

• Faili un datu lapas — ceļš caur vadības paneli
• Mērķlapa katram kodam