API за QR кодове

Задължителен 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.

Общ преглед

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

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

Създаване на 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 кодът се архивира, а данните от сканиранията се запазват.

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

Коментари

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

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

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

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

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

# 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 }'