Files API

Общ преглед

API за файлове (Files API) хоства файлове в qr3 и предоставя стабилен URL адрес за тях. QR кодът сочи към този URL адрес — можете да замените файла зад него по всяко време, без да пренапечатвате кода.

Базов URL адрес: https://qr3.app/v1/files

Опционално можете да свържете файл с даден код чрез code_id. Това е основата за лендинг страница за всеки код, която изброява всички публични файлове на даден код.

Поддържаните типове се проверяват чрез магически байт (magic byte), а не по разширението на файла: PDF, PNG, JPEG, WebP, MP4, glTF/GLB, JSON. Файл с разширение .pdf, който не е действителен PDF, ще бъде отхвърлен.

Note

Да се различава от DPP документите (Digital Product Passport): Те са специфични за DPP и са обвързани с паспорт (Passport). Files API е универсално и може да бъде обвързано с код или с нищо.

Роли

Операция	Изисква се	Получава 403
Всички GET	всяка роля	—
POST /upload, PUT /:id	Роля за писане	viewer
DELETE /:id	Роля за изтриване	viewer, contributor

Специалното правило е за contributor: тази роля може да създава и променя, но не и да изтрива.

Caution

Публикуемият ключ (Publishable Key - qr3_pk_) винаги е с роля viewer, независимо от неговите обхвати (scopes) — следователно вградените от страна на клиента ключове никога не могат да качват, заменят или изтриват. За качване на файлове е необходим таен (Secret) или тестов (Test) ключ с обхват за писане (write scope).

Качване на файл

POST /v1/files/upload

Очаква multipart/form-data.

Поле	Задължително	Описание
file	Да	Файлът
code_id	Не	Свързване с код (трябва да принадлежи към същото работно пространство (Workspace))
visibility	Не	private (по подразбиране) или 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
});

Отговор (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 се задава само при visibility: "public" и status: "active". Адресът не изисква влизане в профила и е подходящ директно за целеви URL адрес на QR код.

Списък с файлове

GET /v1/files

Параметри на заявката (Query): code_id и visibility, и двата са опционални. Връща активните файлове на работното пространство (Workspace), като най-новите са първи.

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

Отговор (HTTP 200):

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

Caution

Тази крайна точка (Endpoint) се различава от стандартния формат за списъци: тя няма пагинация и не връща meta.pagination — винаги се връщат всички съвпадения.

file_count и total_size_bytes се отнасят за филтрирания набор от резултати, а не за работното пространство като цяло. При използване на ?code_id=… или ?visibility=… те броят само филтрираните файлове и следователно не са подходящи за проверка на лимита за съхранение на плана.

Получаване на информация за файл

GET /v1/files/:id

Връща метаданните, включително download_url (и public_url за публични файлове). Достъпно за четене от всички роли.

Изтегляне на файл

GET /v1/files/:id/download

Предава съдържанието като поток (stream) с Content-Disposition: attachment и Cache-Control: private, no-store — следователно отговорът винаги е в текущото си състояние, за разлика от кеширания публичен URL адрес /f/:id.

404 се връща в два случая: файлът не съществува в работното пространство (или е изтрит) или той съществува, но записаният обект липсва.

Замяна на файл

PUT /v1/files/:id

Заменя съдържанието и запазва id — а с това и публичния адрес /f/:id и адреса download_url. Вече отпечатаният QR код остава валиден.

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

visibility, code_id и created_at се запазват; filename, mime_type, size_bytes и hash_sha256 се актуализират. Лимитът на плана за файл важи по същия начин, както при качване, а лимитът за съхранение на работното пространство се проверява спрямо разликата в размера. Ограничението „Файлове за код“ не се прилага, тъй като не се добавя нов файл.

Note

Публичният URL адрес се предоставя с Cache-Control: public, max-age=300. Поради това след замяна кешираното състояние в CDN или браузъра може да показва стария файл в продължение на до 5 минути. Удостовереното изтегляне (authenticated download) е с no-store и се обновява веднага.

Изтриване на файл

DELETE /v1/files/:id

Меко изтриване (Soft-Delete): Файлът изчезва незабавно от списъка, вече не е достъпен и — ако е публичен — вече не се предоставя на адрес /f/:id.

Отговор (HTTP 200):

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

Caution

Изтриването не означава незабавно премахване от публичен достъп за някой, който вече разполага с директната връзка: /f/:id се предоставя с max-age=300 и може да показва файла в продължение на до 5 минути. От друга страна, лендинг страницата не се кешира и веднага спира да показва файла.

Заявката не е идемпотентна — второ DELETE за същия файл връща 404.

Лимити

План	Макс. за файл
Free	5 MB
Pro	25 MB
Business	100 MB
Agency	100 MB
Enterprise	250 MB

Освен това за всеки план важат максимален брой файлове за код и общо пространство за съхранение за всяко работно пространство (Workspace). Ограничението за честота на качване (Upload-Ratelimit) е 100 качвания на час за всяко работно пространство.

Грешки

Статус	Кога
400	Неизвестен или несъответстващ файлов подпис, невалидно multipart тяло
401	Липсващ или невалиден API ключ
403	Ролята няма права за писане или изтриване
404	code_id или файлът не е в работното пространство; при изтегляне също: обектът липсва в хранилището
413	Файлът е по-голям от лимита на плана
422	Липсващ файл, невалидна стойност за visibility, достигнато ограничение „Файлове за код“, превишен лимит за съхранение на работното пространство
429	Ограничение за честота на качване (100/час/работно пространство) или общо ограничение на честотата (Rate-Limit)

Свързани теми

• Файлове и информационни листове — начинът през таблото за управление (Dashboard)
• Лендинг страница за всеки код