API за QR кодове

Общ преглед

API за кодове е сърцето на qr3.app. С него можете да създавате, актуализирате и изтривате динамични и статични QR кодове.

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

Задължителен REST договор

Следният договор е задължителен за всички клиенти:

POST /v1/codes приема само типовете url, vcard, wifi, email, sms и location. Полетата са плоски: url; поне vcard_first_name или vcard_last_name; wifi_ssid; email_to; sms_phone; или location_lat и location_lng.
Само кодовете от тип url могат да са динамични. Заявките за създаване могат по избор да съдържат expires_at като момент по ISO 8601; ab_enabled, ab_target_url_b и ab_weight_a (A/B цели) се приемат за динамични url кодове; redirect_after_expiry не е част от договора за създаване.
GET /v1/codes поддържа само limit, cursor и status (live, paused, flagged, draft).
POST /v1/codes/batch приема url, vcard и wifi. Лимитът е 10 за Free, 500 за Pro и 1 000 записа за Business/Agency/Enterprise на заявка. URL сканиранията се изпълняват синхронно за най-много 50 URL записа; над 50 е необходимо skip_url_scan: true.

Създаване на QR код

`POST /v1/codes`

curl -X POST https://qr3.app/v1/codes \
  -H "Authorization: Bearer qr3_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "url",
    "url": "https://example.com",
    "title": "Mein erster QR-Code",
    "tags": ["marketing", "q1"],
    "is_dynamic": true
  }'

const code = await qr3.codes.create({
  type: 'url',
  url: 'https://example.com',
  title: 'Mein erster QR-Code',
  tags: ['marketing', 'q1'],
  is_dynamic: true,
});

qr3 create https://example.com --title "Mein QR-Code" --tags marketing,q1

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

{
  "data": {
    "id": "qr_a1b2c3d4",
    "short_code": "r7f3Kx",
    "redirect_url": "https://qr3.app/r7f3Kx",
    "image_svg_url": "https://qr3.app/v1/codes/r7f3Kx/qr.svg",
    "image_png_url": "https://qr3.app/v1/codes/r7f3Kx/qr.png",
    "image_pdf_url": "https://qr3.app/v1/codes/r7f3Kx/qr.pdf",
    "image_eps_url": "https://qr3.app/v1/codes/r7f3Kx/qr.eps",
    "type": "url",
    "target_url": "https://example.com",
    "is_dynamic": true,
    "status": "live",
    "tags": ["marketing", "q1"],
    "total_scans": 0,
    "created_at": "2026-03-15T10:00:00.000Z"
  },
  "meta": { "request_id": "req_xyz123" }
}

Типове QR кодове

Тип	Описание	Задължителни полета
`url`	URL адрес на уебсайт (динамичен или статичен)	`url`
`vcard`	Визитка (vCard 3.0)	`vcard_first_name` или `vcard_last_name`
`wifi`	WLAN конфигурация	`wifi_ssid`
`email`	Имейл (mailto:)	`email_to`
`sms`	SMS	`sms_phone`
`location`	Местоположение (geo:)	`location_lat`, `location_lng`

Пакетно създаване

`POST /v1/codes/batch`

curl -X POST https://qr3.app/v1/codes/batch \
  -H "Authorization: Bearer qr3_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "type": "url", "url": "https://produkt-1.example.com", "tags": ["batch"] },
      { "type": "url", "url": "https://produkt-2.example.com", "tags": ["batch"] },
      { "type": "wifi", "wifi_ssid": "GastWLAN", "wifi_password": "geheim123" }
    ],
    "skip_url_scan": false
  }'

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

{
  "data": {
    "created": [
      { "id": "qr_...", "short_code": "abc123", "redirect_url": "https://qr3.app/abc123" },
      { "id": "qr_...", "short_code": "def456", "redirect_url": "https://qr3.app/def456" },
      { "id": "qr_...", "short_code": "ghi789", "status": "live" }
    ],
    "total": 3,
    "failed": 0
  }
}

Списък с QR кодове

`GET /v1/codes`

curl https://qr3.app/v1/codes?status=live&limit=20 \
  -H "Authorization: Bearer qr3_sk_..."

Query параметри:

Параметър	Тип	По подразбиране	Описание
`cursor`	string	—	Курсор за пагинация
`limit`	integer	20	Резултати на страница (макс. 100)
`status`	string	—	Филтър: `live`, `paused`, `flagged`, `draft`

Получаване на QR код

`GET /v1/codes/:id`

curl https://qr3.app/v1/codes/qr_a1b2c3d4 \
  -H "Authorization: Bearer qr3_sk_..."

Актуализиране на QR код

`PATCH /v1/codes/:id`

Update contract: url may be changed only for an existing type: "url" code, and its value must use http:// or https://. Other code types must not receive url; invalid requests return 422.

Динамичните QR кодове позволяват промяна на целевия URL адрес по всяко време — без да е необходимо повторно отпечатване на QR кода.

curl -X PATCH https://qr3.app/v1/codes/qr_a1b2c3d4 \
  -H "Authorization: Bearer qr3_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://neue-zielseite.example.com", "status": "live" }'

Целева страница (Landing page) & външни връзки

За динамични url кодове можете да зададете is_landing_page: true (при създаване или чрез PATCH). При сканиране вместо пренасочване ще се покаже хоствана от qr3 страница с публичните файлове и външните връзки на кода. Външните връзки се предават като масив links:

{
  "is_landing_page": true,
  "links": [
    { "label": "Datenblatt", "url": "https://example.com/datenblatt.pdf" },
    { "label": "Zertifikat", "url": "https://example.com/zertifikat.pdf" }
  ]
}

0–20 връзки на код; label е с дължина 1–100 знака; url трябва да бъде http(s) (≤ 2048 знака).
Всеки URL адрес се проверява с Google Web Risk — опасен URL адрес връща 422.
Ако Google Web Risk не е достъпен при записването, връзката все пак се приема, но се маркира за повторна проверка. Ежедневен процес (job) проверява отново записаните връзки (и периодично препроверява тези, класифицирани като безопасни) и автоматично паузира кода, ако някоя връзка по-късно бъде разпозната като опасна.
"links": [] изтрива всички връзки. Вижте ръководството за целеви страници.

Изтриване на QR код

`DELETE /v1/codes/:id`

Меко изтриване (Soft-Delete) — QR кодът се архивира, а данните от сканиранията се запазват.

Второ DELETE на същия код връща 404, дори ако двете заявки пристигнат едновременно. Уебхукът qr.deleted се изпраща точно веднъж.

curl -X DELETE https://qr3.app/v1/codes/qr_a1b2c3d4 \
  -H "Authorization: Bearer qr3_sk_..."

Изтегляне на QR изображения

Всички формати на изображения са публично достъпни — не се изисква удостоверяване (автентификация).

Формат	URL	Употреба
SVG (векторен)	`/v1/codes/:code/qr.svg`	Уеб, мащабиране, дигитални медии
PNG (растерен)	`/v1/codes/:code/qr.png`	Имейл, презентации
PDF (векторен)	`/v1/codes/:code/qr.pdf`	По подразбиране: квадратен (само кодът); `?format=a4` за лист за печат
EPS (векторен)	`/v1/codes/:code/qr.eps`	Професионални работни процеси за печат (Adobe, печатници)

Опционално: ?size=N — размер на модула в пиксели (2–20, по подразбиране: 4) за SVG, PNG и EPS. PDF форматът използва фиксиран размер на модула.

Само за PDF: ?format=a4|square — формат на страницата (по подразбиране: square — само код + Quiet Zone, без бяло пространство за A4; a4 за готов за печат лист А4)

# SVG für Web
curl https://qr3.app/v1/codes/r7f3Kx/qr.svg

# PNG in hoher Auflösung
curl https://qr3.app/v1/codes/r7f3Kx/qr.png?size=10 -o qr-hires.png

# Kompaktes PDF (nur der Code, Standard)
curl https://qr3.app/v1/codes/r7f3Kx/qr.pdf -o qr.pdf

# Druckfertiges A4-Blatt
curl "https://qr3.app/v1/codes/r7f3Kx/qr.pdf?format=a4" -o qr-a4.pdf

Цветове и корекция на грешки

Всичките четири маршрута за изображения приемат три незадължителни параметъра. Те се прилагат за това конкретно извикване и имат предимство пред цветовете, записани в кода (следващия раздел).

Параметър	Стойности	По подразбиране	SVG, PNG	PDF, EPS
`fg`	Hex `RRGGBB` или `RGB`	`000000`	изчертава се	изчертава се като печатен цвят
`bg`	Hex като `fg` или `transparent`	`ffffff`	изчертава се	изчертава се като печатен цвят
`ecc`	`L`, `M`, `Q`, `H`	`M`	действа	действа

Начин на изписване: Главните и малките букви нямат значение, знакът # е незадължителен. Ако го изпращате, го кодирайте като %23.
Невалидните стойности се считат за незададени. ?fg=lila връща цвета, съхранен в кода, или нормалното черно, ако няма съхранен такъв, с 200 и никога грешка. Само изрично ?fg=000000 налага черно.
bg=transparent връща SVG, PDF или EPS без фонов цвят и PNG с реален алфа канал. Основата, върху която се поставя кодът, трябва да бъде светла и да оставя свободна зона (тиха зона) от 4 модула от всички страни. Тъмен код върху тъмна основа не може да се разчете.
PDF и EPS записват черно и сиво като нива на сивото (само черна пластина), а всеки друг цвят като CMYK в цели проценти, например 1F4E79 като C74 M36 Y0 K53. Веднага щом бъде избран цвят, зад кода и неговата тиха зона се разполага непрозрачен запълващ слой, бял или в цвета на bg, както е при SVG. Без цветове и двата файла остават непроменени. Преобразуване и ограничения: Цветове при печат.
Контраст: Маршрутът за изображения не го проверява. Препоръчва се съотношение от поне 4:1 и тъмни модули на светъл фон. #1F4E79 върху бяло има съотношение 8,7:1, а #ff6600 върху бяло – само 2,9:1.
ecc променя модела на точките, а не съдържанието. Вече отпечатан код продължава да работи, но не смесвайте стари и нови файлове за печат. Q или H правят кода по-устойчив, например върху велпапе. Наличието на лого винаги налага H.
С лого областта зад логото остава бяла, дори и при цветен или прозрачен фон.
Кеш: Само действителното стандартно изображение (черно на бяло, корекция на грешки M, без лого) се доставя като непроменяемо за 24 часа; всяко друго изобразяване — за 5 минути. За PDF и EPS всеки посочен фон се счита за отклонение: bg=ffffff изчертава бял запълващ цвят там, какъвто стандартният файл няма.
Тарифен план: Цветовете и корекцията на грешки са налични във всеки тарифен план, включително и в безплатния.

cURL
TypeScript SDK

# Dark blue code on white
curl "https://qr3.app/v1/codes/r7f3Kx/qr.svg?fg=1F4E79" -o qr-blue.svg

# Transparent PNG for a layout on a light surface
curl "https://qr3.app/v1/codes/r7f3Kx/qr.png?size=10&bg=transparent" -o qr-transparent.png

# More robust for corrugated board: error correction Q
curl "https://qr3.app/v1/codes/r7f3Kx/qr.pdf?ecc=Q" -o qr-q.pdf

// @qr3/sdk 1.2.0 or later — imageUrl() only builds the URL, it sends no request
// Dark blue code on white
qr3.codes.imageUrl('r7f3Kx', { format: 'svg', fg: '1F4E79' });
// → https://qr3.app/v1/codes/r7f3Kx/qr.svg?fg=1F4E79

// Transparent PNG for a layout on a light surface
qr3.codes.imageUrl('r7f3Kx', { format: 'png', size: 10, bg: 'transparent' });

// More robust for corrugated board: error correction Q
qr3.codes.imageUrl('r7f3Kx', { format: 'pdf', ecc: 'Q' });

Запазване на цветове в кода

PATCH /v1/codes/:id запазва цветове като appearance в кода. След това маршрутите за изображения ги изчертават по подразбиране, без параметри.

cURL
TypeScript SDK

curl -X PATCH https://qr3.app/v1/codes/qr_a1b2c3d4 \
  -H "Authorization: Bearer qr3_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"appearance": {"foreground_color": "#1F4E79"}}'

// @qr3/sdk 1.2.0 or later
const code = await qr3.codes.update('qr_a1b2c3d4', {
  appearance: { foreground_color: '#1F4E79' },
});
code.appearance; // { foreground_color: '#1F4E79', background_color: null }
code.issues;     // contrast check findings, absent when there are none

Отговор (HTTP 200, съкратен):

{
  "data": {
    "id": "qr_a1b2c3d4",
    "short_code": "r7f3Kx",
    "appearance": { "foreground_color": "#1F4E79", "background_color": null }
  },
  "meta": { "request_id": "req_xyz", "issues": [] }
}

Стойности: foreground_color като #RRGGBB, background_color като #RRGGBB или transparent. Други ключове връщат 400.
Обединяване: Пропуснато поле запазва своята записана стойност. null нулира дадено поле, "appearance": null и двете. Черно и бяло не се запазват; отговорът ги показва като null.
Всеки отговор за код съдържа appearance, както и webhooks qr.created и qr.updated.
Последователност в маршрутите за изображения: първо параметърът, след това запазеният цвят, след това стойността по подразбиране. Поради това ?fg=000000 предоставя черния файл за печат на цветен код.
Вградени изображения: Един URL адрес на изображение следва съхранените цветове, освен ако не ги задава сам с fg и bg: URL адрес без параметри и за двата цвята, ?fg=000000 за фоновия цвят, ?ecc=Q също и за двата. След промяна на цвета страница, която вгражда такъв URL адрес, може все още да показва старото изображение: до 24 часа, ако дотогава URL адресът е доставял стандартното изображение (черно на бяло, корекция на грешки M, без лого), в противен случай до 5 минути. Решението е собствен параметър в URL адреса, който се променя при всяка промяна на цвета, например ?v=2 или updated_at на кода, както в таблото. Маршрутите за изображения игнорират непознати параметри.
Корекцията на грешки никога не се запазва. Тя се избира за всяко изтегляне с ?ecc=.
Само чрез PATCH: POST /v1/codes, груповата обработка (batch) и импортирането отхвърлят appearance с 422.
PDF и EPS изчертават запазените цветове като цветове за печат, точно както и параметрите. Тъй като бялото никога не се запазва, код със запазен цвят на предния план получава бял запълващ цвят там, както е в SVG.

Проверка на контраста

API проверява двойката, която се получава от заявката и запазената стойност:

Ниво	Кога	Отговор
`blocked`	Контраст под 1,5:1	`422`, нищо не се запазва
`critical`	под 2:1 или разлика в яркостта под 0,30; предупреждение заедно с лого; всеки прозрачен фон	`200` с `meta.issues`
`warning`	под 4:1 или разлика в яркостта под 0,50; светли модули на тъмен фон	`200` с `meta.issues`
ok	всичко останало	`200`, `meta.issues` е празно

Всеки запис в meta.issues съдържа code, severity, field, message и по избор hints като contrast_ratio — същата форма като съобщенията за съответствие на дигиталния продуктов паспорт (DPP). Прозрачният фон никога не се блокира, тъй като светъл код върху тъмна опаковка е реален случай на употреба. Въпреки това основата се нуждае от ясен контраст и свободна защитна зона от 4 модула от всички страни.

Качването и премахването на лого (POST и DELETE /v1/codes/:id/logo) извършват същата проверка на запазените цветове и също връщат констатациите в meta.issues: с лого предупреждението става critical, а без лого — отново предупреждение.

Ако друга заявка промени същия код в същия момент, API прилага промените към най-актуалното състояние. Едва когато това се провали три пъти поред, той отговаря с 409; тогава клиентът презарежда кода и повтаря промяната.

Лого

`POST /v1/codes/:id/logo`

Multipart заявка, поле file: PNG, JPEG или WebP, максимум 1 MB, разпознати по техните magic bytes. Нормализира изображението до прозрачно 512×512-PNG и заменя съществуващото лого.

curl -X POST https://qr3.app/v1/codes/qr_a1b2c3d4/logo \
  -H "Authorization: Bearer qr3_sk_..." \
  -F "[email protected]"

Отговор (HTTP 201): актуализираният код със зададено logo_file_id.

`DELETE /v1/codes/:id/logo`

Премахва логото и изтрива записания обект. Идемпотентно — извикване без съществуващо лого все пак връща 200.

Ако друга заявка промени логото на същия код в същия момент (второ качване или премахване), POST и DELETE /v1/codes/:id/logo отговарят с 409 (errors/conflict) и не променят нищо; каченото изображение се отхвърля. Презаредете кода и опитайте отново. Две едновременни извиквания на DELETE /v1/codes/:id/logo не представляват конфликт; и двете връщат 200.

Ако е зададено, и четирите формата — qr.svg, qr.png, qr.pdf и qr.eps — вграждат пикселите на логото и повишават нивото на корекция на грешки до H. Пълният договор — включително коя промяна (добавяне/премахване спрямо замяна) променя точковия модел — както и инструкции за печат, са налични в Лого в QR кода.

Коментари

Коментарите позволяват обратна връзка между агенции и клиенти.

`GET /v1/codes/:id/comments`

`POST /v1/codes/:id/comments`

`PATCH /v1/codes/:id/comments/:commentId`

`DELETE /v1/codes/:id/comments/:commentId`

Коментарите в Dashboard се приписват на създалия ги потребител (author_id); коментарите, създадени чрез обикновени API ключове, остават неприписани (author_id: null). Даден коментар може да бъде изтрит само от самия автор или от org_admin/ws_admin — обикновените API ключове могат да изтриват само неприписани коментари, създадени чрез API.

# Kommentar hinzufügen
curl -X POST https://qr3.app/v1/codes/qr_a1b2c3d4/comments \
  -H "Authorization: Bearer qr3_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "body": "QR-Code bitte auf grünen Hintergrund abstimmen.", "author_name": "Max Müller" }'

# Offene Kommentare auflisten
curl "https://qr3.app/v1/codes/qr_a1b2c3d4/comments?resolved=false" \
  -H "Authorization: Bearer qr3_sk_..."

# Kommentar als erledigt markieren
curl -X PATCH https://qr3.app/v1/codes/qr_a1b2c3d4/comments/cmt_xyz \
  -H "Authorization: Bearer qr3_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "resolved": true }'