API генератора QR‑кодов

Этот документ описывает, как программно создавать PNG, SVG или PDF‑файлы с QR‑кодами через HTTP‑энд‑пойнт /api/gen.php.

1. Обзор

Внимание: сервис не хранит сгенерированые QR коды, более подробно описано в FAQ

URL энд‑пойнта: https://qr.uralst.ru/api/gen.php
Доступные методы: GET, POST — генерация, OPTIONS — интроспекция.
Ответ: JSON с прямой ссылкой на файл или сам файл (при download=1). Для OPTIONS возвращается JSON‑список поддерживаемых параметров.

2. Быстрый старт

# PNG‑код
curl "https://qr.uralst.ru/api/gen.php?apikey=demo123&text=Hello%20World&size=400&format=png"

JSON‑ответ:

{
  "status": "success",
  "file"  : "https://qr.uralst.ru/qrcodes/qr_abcd1234.png",
  "size"  : 400,
  "ecc"   : "Q",
  "format": "png"
}

2.1 Интроспекция параметров

curl -X OPTIONS https://qr.uralst.ru/api/gen.php | jq

Получите объект со всеми параметрами, их типами и значениями по умолчанию — пригодно для автогенерации UI и CORS‑preflight.

3. Параметры запроса

Параметр	Тип / диапазон	По умолчанию	Описание
`apikey`	string	— (обяз.)	Ключ доступа к API (если включена проверка).
`data` / `text`	string	— (обяз.)	Текст/URL для кодирования.
`data64` / `text64`	base64‑string	—	Альтернатива `data` (передача спецсимволов без URL‑кодирования).
`format`	png \| svg \| pdf	png	Формат выходного файла.
`size`	50 – 3000 px	700	Ширина/высота QR‑кода.
`margin`	0 – 100 модулей	4	Белая рамка вокруг кода.
`level`	L \| M \| Q \| H	Q	Уровень коррекции ошибок.
`frontcolor`	#RRGGBB	#000000	Цвет «пикселей».
`backcolor`	#RRGGBB	#FFFFFF	Цвет фона.
`transparent`	0 \| 1	0	1 — фон будет прозрачным.
`marker_out`	finder, plus, dot, dots, 9-dots, 9-dots-fat, rounded, sun, pulse, flurry, leaf, flower, elastic, vortex, sparkle_dot, 3-corners, frame	dot	Стиль внешних угловых маркеров.
`marker_in`	default, plus, dot, dots, 9-dots, 9-dots-fat, rounded, sun, pulse, flurry, leaf, flower, elastic, vortex, sparkle_dot, 3-corners, frame	default	Стиль внутренних маркеров.
`marker_out_color`	#RRGGBB	frontcolor	Цвет внешних маркеров.
`marker_in_color`	#RRGGBB	frontcolor	Цвет внутренних маркеров.
`font`	DejaVuSans, DejaVuSansCondensed, DejaVuSerif, DejaVuSerifCondensed, DejaVuSansMono	DejaVuSans	Шрифт для PDF (лежит в `/pdf/fonts/`).
`paper`	A4, A6, Letter …	A4	Размер листа при PDF.
`download`	0 \| 1	0	1 — вместо JSON вернётся готовый файл.
`embed`	0 \| 1	0	1 — добавить поле `data` (Base64) в ответ.

Полный перечень поддерживаемых стилей маркеров и шрифтов доступен на главной странице.

4. Примеры

4.1 PNG с пользовательскими маркерами

curl "https://qr.uralst.ru/api/gen.php?apikey=demo123&text=Hello+PNG&format=png&marker_out=dot&marker_in=plus&marker_out_color=FF0000&marker_in_color=00FF00" -o qr.png

4.2 SVG c base64‑данными

curl "https://qr.uralst.ru/api/gen.php?apikey=demo123&data64=$(echo -n 'Секрет 👍'|base64)&format=svg" -o qr.svg

4.3 PDF‑наклейка

curl -X POST https://qr.uralst.ru/api/gen.php \
     -d "apikey=demo123&text64=$(base64 -w0 <<< 'SN:XPTO-2025-0001')&format=pdf&size=450&paper=A6&font=DejaVuSerifCondensed&download=1" \
     -o label.pdf

4.4 Получить описание параметров

curl -X OPTIONS https://qr.uralst.ru/api/gen.php | jq .marker_in.values

5. Формат ответа

Ключ	Описание
`status`	`success` \| `error`
`file`	URL готового файла (нет при `download=1`)
`mime`	MIME‑тип (image/png, image/svg+xml, application/pdf)
`data`	Base64‑контент (при `embed=1` или OPTIONS)
`size`	Размер в пикселях
`ecc`	Уровень ECC
`format`	png \| svg \| pdf
`message`	Текст ошибки (при `error`)

6. Коды ошибок

HTTP	message	Причина
400	parameter "data" required	Нет входных данных
400	invalid format	Неверное значение `format`
422	backend missing	Серверу не хватает Imagick / rsvg‑convert / Dompdf / mPDF
500	internal error	Необработанное исключение

7. Расширенные возможности

Интроспекция — отправьте OPTIONS, получите JSON‑схему.
SVG → PDF без растрирования — vector=1.
Прозрачный фон — transparent=1.
Кэширование PNG/SVG — отдавайте статику из /qrcodes/.
Собственный шрифт — положите TTF в /pdf/fonts/ и передайте font=<имя>.

8. FAQ

Ошибка «missing or invalid apikey»

Вы не передали apikey или он недействителен. Уточните его у администратора сервиса.

Почему сервис не хранит QR коды

Сервис не хранит QR коды для экономии места, они стираются раз в час. Время хранения можно увеличить или сделать постоянным.

PNG выглядит размытым

Увеличьте size или используйте SVG/PDF.

Как сделать фон прозрачным?

transparent=1 или backcolor=#FFFFFF00.

Нужен логотип в центре

Сгенерируйте PNG и наложите логотип средствами GD/Imagick.

Base64 encode/decode API

1. Обзор

Методы: GET, POST, OPTIONS (pre‑flight)
Аутентификация: API‑ключ (заголовок X-API-Key / Authorization: Bearer / параметр apikey)
Форматы запроса: application/json, application/x-www-form-urlencoded, (опц.) text/plain
Ответ: JSON

2. Аутентификация

Способ	Пример
Заголовок	`X-API-Key: demo123`
Bearer‑токен	`Authorization: Bearer demo123`
Параметр	`?apikey=demo123` или в теле формы

При отсутствии/ошибке ключа будет 403 и ошибка missing or invalid apikey.

3. Параметры

Имя	Тип	Обяз.	Описание
`data`	string	✔	Строка UTF‑8 для кодирования/декодирования
`action`	string	✔	`encode` (по умолч.) или `decode`

4. Примеры запросов

4.1 Кодирование (GET)

curl "https://qr.uralst.ru/api/base64.php?apikey=demo123&data=Hello%20World&action=encode"

4.2 Кодирование (POST / JSON)

curl -X POST https://qr.uralst.ru/api/base64.php \
     -H "Content-Type: application/json" \
     -H "X-API-Key: demo123" \
     -d '{
           "data": "Привет мир",
           "action": "encode"
         }'

4.3 Декодирование (POST / Bearer)

curl -X POST https://qr.uralst.ru/api/base64.php \
     -H "Authorization: Bearer demo123" \
     -H "Content-Type: application/json" \
     -d '{
           "data": "SGVsbG8gV29ybGQ=",
           "action": "decode"
         }'

5. Формат ответа

{
  "status": true,
  "action" : "encode",
  "input"  : "Hello World",
  "result" : "SGVsbG8gV29ybGQ="
}

6. Ошибки

HTTP	error	Причина
400	Parameter "data" is required.	Нет строки
400	Invalid base64 string.	Некорректная Base64 при decode
403	missing or invalid apikey	Ключ отсутствует / неверен