Разработчикам и ИИ

API для сокращения ссылок: создавайте ссылки и QR-коды из своей системы

Обновлено 8 мин чтения

Когда ссылок десятки в день, создавать их руками в кабинете неудобно. Интернет-магазину нужна короткая ссылка на каждый заказ, типографии — QR-код на каждую партию этикеток, SMM-агентству — набор ссылок с UTM-метками под каждую кампанию. Через API snap.kz ваша программа делает это сама: отправляет адрес и получает короткую ссылку, картинку QR-кода и статистику переходов.

Ниже — как получить ключ, создать первую ссылку на curl, Node.js, Python и PHP, забрать QR-код и статистику, поменять адрес назначения и что означает каждая ошибка. Полный список полей — в документации API.

Что умеет API

API snap.kz — обычный REST: у каждой операции свой адрес и HTTP-метод, данные ходят в JSON. Базовый адрес — https://snap.kz/api/v1.

ЗапросЧто делает
POST /linksСоздаёт короткую ссылку: адрес назначения, свой адрес, название, теги, UTM, срок действия, пароль
GET /linksСписок ссылок с поиском, фильтром по тегу и постраничной выдачей
GET /links/{id}Одна ссылка
PATCH /links/{id}Меняет адрес назначения, название, теги, срок действия, включает и выключает ссылку
DELETE /links/{id}Удаляет ссылку
GET /links/{id}/statsСтатистика: переходы, уникальные, QR-сканы, города, устройства, источники
GET /links/{id}/qrКартинка QR-кода в SVG или PNG
GET /meТариф, лимиты и сколько уже использовано

API работает на тарифах «Про» и «Бизнес». На бесплатном тарифе ссылки создаются только в кабинете.

Пошагово: первая ссылка через API

Шаг 1. Включите тариф «Про» или «Бизнес»

Зарегистрируйтесь и оплатите тариф: «Про» стоит 2 990 ₸ за 30 дней или 29 900 ₸ за год, «Бизнес» — 9 990 ₸ или 99 900 ₸. Оплата — Kaspi или счёт на ТОО/ИП, без автопродления. Чем отличаются тарифы, видно на странице цен.

Шаг 2. Получите API-ключ

Ключ выпускается в кабинете, в разделе API. Он выглядит как sk_… и показывается один раз — сразу сохраните его в менеджер паролей или в переменную окружения на сервере. У нас хранится только хеш ключа, поэтому показать его повторно мы не сможем.

Ключ передаётся в каждом запросе заголовком:

HTTP
Authorization: Bearer sk_ваш_ключ

Подробнее о том, что такое API-ключ и почему его нельзя показывать в браузере, — ниже, в разделе о безопасности.

Шаг 3. Создайте ссылку

Обязательное поле одно — url, адрес, куда должна вести ссылка. Остальные необязательные:

ПолеЧто это
urlАдрес назначения, только http:// или https://, до 2 000 символов
aliasСвой адрес: aroma-menu превратится в snap.kz/aroma-menu
titleНазвание для себя — видно в кабинете и в списке
tagsТеги для группировки: кампания, клиент, филиал
utmUTM-метки: source, medium, campaign, term, content
expires_atДата, после которой ссылка перестанет открываться
passwordПароль, который посетитель введёт перед переходом

Запрос на curl:

bash
export SNAP_API_KEY="sk_ваш_ключ"

curl -X POST https://snap.kz/api/v1/links \
  -H "Authorization: Bearer $SNAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://aroma.kz/menu",
    "alias": "aroma-menu",
    "title": "Меню на столах, Абая 10",
    "tags": ["меню", "офлайн"],
    "utm": {"source": "qr", "medium": "offline", "campaign": "menu-osen"}
  }'

Успешный ответ — код 201 и данные ссылки: id, code, short_url (готовая короткая ссылка), qr_url (картинка QR-кода) и target_url (куда ведёт). Сохраните у себя id: по нему потом запрашивают статистику и меняют адрес.

Свой адрес — латиница в нижнем регистре, цифры, - и _, от 3 до 50 символов, начинается и заканчивается буквой или цифрой. Адреса общие на весь сервис, поэтому menu или sale скорее всего заняты — добавляйте название бренда. Без alias получится случайный код из 6 символов. Как придумать хороший адрес, — в гайде про свой адрес ссылки.

Шаг 4. Заберите QR-код

bash
curl "https://snap.kz/api/v1/links/ID/qr?format=svg" \
  -H "Authorization: Bearer $SNAP_API_KEY" \
  -o aroma-menu.svg

Вместо ID подставьте id ссылки из ответа. Формат — svg или png, размер и цвета задаются параметрами size, color и bg. Для печати берите SVG: векторная картинка не размывается при любом увеличении. QR-код ведёт на короткую ссылку с меткой ?qr, поэтому сканы в статистике считаются отдельно от кликов. Как выбрать размер под печать, — в гайде про печать QR-кода.

Шаг 5. Посмотрите статистику

bash
curl "https://snap.kz/api/v1/links/ID/stats?from=2026-10-01&to=2026-10-17" \
  -H "Authorization: Bearer $SNAP_API_KEY"

В ответе — всего переходов (total), уникальных (uniques), из них по QR-коду (qr), ряд по дням (series: день, клики, уникальные), а также разбивка по городам, устройствам, операционным системам, браузерам и источникам. Глубина истории зависит от тарифа: на «Про» — год, на «Бизнесе» — 3 года. Боты и превью ссылок в мессенджерах в основные цифры не попадают. Что именно считается переходом, разобрано в гайде как посчитать переходы по ссылке.

Та же ссылка на Node.js, Python и PHP

Node.js (fetch, Node 18+)

JavaScript
const res = await fetch("https://snap.kz/api/v1/links", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SNAP_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://alma.kz/orders/1042",
    title: "Заказ №1042",
    tags: ["заказы"],
  }),
});

const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error?.code}: ${data.error?.message}`);
console.log(data.short_url, data.qr_url);

Python (requests)

Python
import os
import requests

r = requests.post(
    "https://snap.kz/api/v1/links",
    headers={"Authorization": f"Bearer {os.environ['SNAP_API_KEY']}"},
    json={
        "url": "https://alma.kz/sale",
        "utm": {"source": "telegram", "medium": "post", "campaign": "black-friday"},
    },
    timeout=10,
)
data = r.json()
if r.status_code != 201:
    raise RuntimeError(f"{r.status_code} {data['error']['code']}: {data['error']['message']}")
print(data["short_url"])

PHP (cURL)

PHP
<?php
$ch = curl_init("https://snap.kz/api/v1/links");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("SNAP_API_KEY"),
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "url" => "https://alma.kz/catalog/sumki",
        "title" => "Каталог сумок",
    ], JSON_UNESCAPED_UNICODE),
]);
$data = json_decode(curl_exec($ch), true);
$code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($code !== 201) {
    throw new Exception($data["error"]["code"] . ": " . $data["error"]["message"]);
}
echo $data["short_url"];

Поменять адрес назначения

Главное, ради чего ссылки создают через сервис, а не печатают длинный адрес: назначение можно поменять, а ссылка и напечатанный QR-код останутся прежними. Это и есть динамический QR-код.

bash
curl -X PATCH https://snap.kz/api/v1/links/ID \
  -H "Authorization: Bearer $SNAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"target_url": "https://aroma.kz/menu-zima"}'

Через PATCH меняются target_url, title, tags, expires_at и status: disabled выключает ссылку, active включает обратно. Переход по выключенной ссылке покажет страницу «Ссылка отключена». DELETE удаляет ссылку совсем: напечатанный QR-код с ней перестанет работать, поэтому для временной паузы лучше выключать, а не удалять.

Смена назначения работает, потому что snap.kz отвечает редиректом 302 — временным. Браузер не запоминает его и каждый раз спрашивает сервер, куда вести.

Список ссылок и поиск

GET /api/v1/links отдаёт ссылки аккаунта страницами. Параметры: limit — сколько ссылок на странице, q — поиск, tag — только ссылки с этим тегом, cursor — с какого места продолжить. Курсор следующей страницы приходит в ответе: передайте его в следующий запрос и повторяйте, пока страницы не закончатся.

bash
curl "https://snap.kz/api/v1/links?tag=black-friday&limit=50" \
  -H "Authorization: Bearer $SNAP_API_KEY"

Чтобы узнать тариф, лимит ссылок и сколько уже занято, вызовите GET /api/v1/me — удобно проверить перед большой пачкой.

Ошибки и что с ними делать

Тело ошибки всегда одинаковое: {"error": {"code": "…", "message": "…"}}. В message — понятное описание, в code — машинный код, по которому удобно ветвить логику.

Код HTTPЧто случилосьЧто делать
400Запрос собран неверно: не JSON, нет urlПроверьте тело и заголовок Content-Type
401Нет ключа или ключ неверныйПроверьте заголовок Authorization: Bearer sk_…
402Тариф не позволяет: API, свой адрес или лимит не входят в текущий тарифПродлите или смените тариф на странице цен
403Действие запрещено для этого аккаунта или ссылкиПрочитайте message, при сомнениях — в поддержку
404Ссылки с таким id нет или она не вашаПроверьте id
409Свой адрес уже занятВозьмите другой alias, например с названием бренда
422Данные не прошли проверку: адрес не http(s), слишком длинный, ведёт на сам snap.kz, неверный формат своего адресаИсправьте поле, о котором говорит message
429Слишком много запросов в минуту или ссылок за суткиПодождите и повторите с паузой

На 429 не повторяйте запрос сразу в цикле — делайте паузу и увеличивайте её с каждой попыткой. Если адрес назначения похож на подозрительный, ссылка может уйти на ручную проверку: она создастся, но посетители увидят предупреждение, пока мы её не проверим. Почему так, — в гайде о безопасности коротких ссылок.

Лимиты

ПроБизнес
Ссылок на аккаунтедо 1 000до 10 000
Новых ссылок в суткидо 300до 3 000
Запросов к API в минуту60300
Глубина статистики1 год3 года

Если тариф закончился, ссылки не отключаются: и созданные через API, и свои адреса продолжают вести, куда вели. Перестают работать платные функции, в том числе сам API, пока вы не продлите тариф. За 3 дня до окончания напомним в Telegram, если вы открыли бота поддержки из кабинета.

Нужно создать сотни ссылок разом, без программирования? На тарифе «Бизнес» есть массовое создание из CSV. А если ссылки удобнее заказывать словами, подключите MCP-сервер для ИИ-агента — он работает с тем же ключом.

Безопасность ключа

  • Ключ — только на сервере. Не вставляйте его в JavaScript страницы сайта, мобильное приложение или Telegram-бота с открытым кодом: кто увидит ключ, сможет создавать и менять ваши ссылки.
  • Переменная окружения, а не код. Храните ключ в SNAP_API_KEY или менеджере секретов, а не в файлах, которые попадают в git.
  • Ключ один на аккаунт. Он открывает все ссылки аккаунта, поэтому не раздавайте его подрядчикам без нужды.
  • Не кладите персональные данные в адрес. Телефон или имя клиента в url или UTM видны каждому, кто откроет ссылку. Подробнее — в гайде о персональных данных.

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

Можно ли пользоваться API на бесплатном тарифе?

Нет. API и MCP входят в тарифы «Про» и «Бизнес». На бесплатном тарифе ссылки и QR-коды создаются в кабинете — до 30 ссылок.

Нужна ли библиотека или SDK?

Нет. Подойдёт любой HTTP-клиент: curl, fetch в Node.js, requests в Python, cURL в PHP. Запросы и ответы — JSON в UTF-8, кириллица в названиях и тегах передаётся как есть.

Как сделать QR-код через API?

Создайте ссылку через POST /links, затем запросите GET /links/{id}/qr?format=svg или format=png. QR-код ведёт на короткую ссылку, поэтому его можно напечатать, а адрес назначения поменять потом через PATCH.

Можно ли передать UTM-метки?

Да, полем utm с ключами source, medium, campaign, term и content. Как их правильно составлять, — в гайде про UTM-метки.

Что будет со ссылками, если не продлить тариф?

Они продолжат работать и вести туда же. Перестанут работать API и другие платные функции, а новые ссылки сверх лимита бесплатного тарифа создать будет нельзя.

Где находится сервер API?

В Казахстане, вместе с базой ссылок и статистики. Оплата — в тенге, Kaspi или счётом на ТОО/ИП.

Сделайте короткую ссылку с QR-кодом

Бесплатно — до 30 ссылок с QR-кодами и статистикой переходов. Ссылки не отключаются за неоплату, сервер — в Казахстане.