Публичный API для автоматизации ссылок

Задача

Сотни SKU, филиалов или клиентских кампаний невозможно обслуживать вручную через кабинет. Маркетинг ждёт синхронизации с CRM, а IT — стабильного контракта без хрупкого парсинга интерфейса. Каждая новая акция не должна превращаться в отдельный тикет на «создайте QR».

Ценность

Публичный API QR.RU.NET даёт программный доступ к тем же ссылкам, что и кабинет: создавайте, обновляйте destination_url, деактивируйте и забирайте stats. Пакетный endpoint ускоряет массовые операции. Ключ с granular permissions (чтение/запись ссылок, чтение аналитики) живёт в пространстве и отзывается без смены паролей пользователей.

Поддерживаемые операции

GET /api/v1/public/links — список ссылок пространства с пагинацией. POST — создание новой ссылки с destination_url и опциональным slug.

GET /api/v1/public/links/{link} — детали ссылки. PATCH — обновление полей, включая назначение и статус. DELETE — удаление.

POST /api/v1/public/links/batch — пакетные действия (например, массовая деактивация по link_ids). GET /api/v1/public/links/{link}/stats — агрегированная статистика переходов.

Все запросы проходят через middleware throttle:public-api — соблюдайте лимиты вашего тарифа.

• index, store, show, update, destroy
• batch
• stats

Авторизация и ключи

Передавайте API-ключ в заголовке X-API-Key. Альтернативно Bearer-токен поддерживается в тестах интеграции — ориентируйтесь на документацию /docs/public-api как на источник истины.

Ключи выдаются в кабинете рабочего пространства с разделением прав: links:read, links:write, analytics:read. Принцип минимальных привилегий: отдельные ключи для staging и production.

Не встраивайте ключи во фронтенд браузера — только server-to-server вызовы из вашего бэкенда.

Ошибки и лимиты

Ошибки возвращаются как application/problem+json с полями title и detail — типичные случаи: занятый slug, отклонённый destination_url, превышен лимит тарифа или rate limit.

При приближении к лимитам ссылок или переходов API вернёт отказ до автоматического списания с внешней карты — перерасход не тарифицируется скрыто.

Актуальные лимиты запросов и условия тарифа смотрите в кабинете «Тариф и использование» и на /pricing.

Вебхуки и расширения

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

Для большинства интеграций достаточно периодического опроса stats или списка ссылок. Планируйте архитектуру исходя из documented API, а не предполагаемых push-уведомлений.

Wallet billing позволяет пополнять баланс пространства для расширения лимитов без смены контракта — актуально для сезонных всплесков API-нагрузки.

Типовые сценарии

• Включите API на подходящем тарифе и создайте ключ в кабинете
• Настройте server-to-server клиент с X-API-Key
• Создайте ссылки через POST при появлении новых SKU или кампаний
• Обновляйте destination_url через PATCH при смене акций
• Деактивируйте устаревшие ссылки через PATCH или batch
• Забирайте stats для отчётов и дашбордов

Ограничения

• API доступен не на всех тарифах — проверьте условия тарифа в каталоге
• Публичный API покрывает links CRUD/batch/stats — не все функции кабинета дублируются 1:1
• Rate limits и лимиты ссылок применяются к API так же, как к UI
• Вебхуки не заявлены как готовая self-service функция для всех планов

Доступ к API и лимиты запросов зависят от тарифа рабочего пространства. Enterprise и старшие планы включают расширенные возможности. Кошелёк биллинга — для пополнения без автосписаний. Подробности: /pricing и /docs/public-api.

Частые вопросы