Static QR API: создание QR-кодов с вашего бэкенда

Static QR API от WebQR позволяет вашему бэкенду создавать QR-коды на лету: вы отправляете содержимое и дизайн — и получаете готовый SVG. Рассказываем, где найти ключи, как создать ключ и отправить первый запрос.

Где найти API

В кабинете откройте страницу API — dash.webqr.io/api. Отсюда ссылка API‑ключи ведёт к вашим ключам, а в блоке Документация есть кнопки Документация API и Конструктор API — в конструкторе можно посмотреть SVG ещё до написания кода.

Создайте ключ

Перейдите в API‑ключи (dash.webqr.io/api/keys) и нажмите Создать API‑ключ.

В окне Создать ключ впишите Название ключа — короткое имя, которое видно только в вашем списке, — и нажмите Создать API‑ключ.

Полный секрет показывается только один раз, сразу после создания, — скопируйте его и сохраните в надёжном месте, например в переменной окружения на сервере. В списке ключ потом виден в замаскированном виде, с префиксом для поиска, датой создания и полем Разрешённые IP.

Откройте документацию

Полный справочник — на webqr.io/api-documentation: пошаговая инструкция, формат запроса и ответа, параметры дизайна и ошибки. Там же можно скачать спецификацию OpenAPI (YAML) и коллекцию Postman.

Создайте QR-код

Отправьте POST https://api.webqr.io/v1/generate с заголовком X-API-Key и JSON-телом. В поле data (до 1000 символов) — содержимое кода: ссылка, текст, данные Wi-Fi и т. д. Объект design необязателен: размер, цвета, форма модулей и глазков, рамка, логотип и другое. Вызывайте API только со своего бэкенда — не из кода в браузере и не из мобильного приложения.

Вот реальный запрос:

curl -X POST https://api.webqr.io/v1/generate \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "data": "https://webqr.io",
    "design": {
        "size": 512,
        "color": "#000000",
        "backgroundColor": "#FFFFFF",
        "styleType": "a7k2m9",
        "eyeType": "r2s4t6",
        "showColorGradient": false
    }
}'

Ответ приходит в JSON. SVG-разметка кода — в data.qr_code: её можно сохранить в файл или вставить на страницу как есть.

{
    "success": true,
    "data": {
        "qr_code": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 512 512\" width=\"512\" height=\"512\" ...>...</svg>",
        "format": "svg",
        "content": "https://webqr.io",
        "design": { "size": 512, "color": "#000000", ... }
    },
    ...
}

WebQR не хранит коды, созданные через API: каждый ответ самодостаточен.

Проверьте использование

GET /v1/usage возвращает счётчики использования. Запрос только читает данные и не создаёт коды.

curl https://api.webqr.io/v1/usage \
  -H "X-API-Key: YOUR_API_KEY"

Дополнительная защита

Для каждого ключа есть две необязательные настройки:

• Список разрешённых IP — ключ работает только с указанных адресов. По умолчанию разрешены все.
• Подпись HMAC — каждый запрос несёт заголовки X-WebQR-Timestamp и X-WebQR-Signature с подписью HMAC-SHA256 на основе вашего секрета. Точная строка для подписи описана в документации.

Частые ошибки

• 401 — ключ не передан, неверен или отозван либо подпись не совпала.
• 403 — запрос пришёл с IP, который не разрешён для этого ключа.
• 422 — тело запроса не прошло проверку, например data пустое или слишком длинное. В ответе перечислены проблемные поля.
• 429 — слишком много запросов за короткое время. Подождите время из заголовка Retry-After и повторите.

Советы

• Создавайте отдельный ключ для каждого проекта или сервера — так проще отозвать только один.
• Не коммитьте ключ в репозиторий и не вставляйте его во фронтенд.
• Сначала подберите дизайн в Конструкторе API, а потом перенесите параметры в запрос.