API для сокращения ссылок: создавайте ссылки и QR-коды из своей системы
Когда ссылок десятки в день, создавать их руками в кабинете неудобно. Интернет-магазину нужна короткая ссылка на каждый заказ, типографии — 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_… и показывается один раз — сразу сохраните его в менеджер паролей или в переменную окружения на сервере. У нас хранится только хеш ключа, поэтому показать его повторно мы не сможем.
Ключ передаётся в каждом запросе заголовком:
Authorization: Bearer sk_ваш_ключПодробнее о том, что такое API-ключ и почему его нельзя показывать в браузере, — ниже, в разделе о безопасности.
Шаг 3. Создайте ссылку
Обязательное поле одно — url, адрес, куда должна вести ссылка. Остальные необязательные:
| Поле | Что это |
|---|---|
url | Адрес назначения, только http:// или https://, до 2 000 символов |
alias | Свой адрес: aroma-menu превратится в snap.kz/aroma-menu |
title | Название для себя — видно в кабинете и в списке |
tags | Теги для группировки: кампания, клиент, филиал |
utm | UTM-метки: source, medium, campaign, term, content |
expires_at | Дата, после которой ссылка перестанет открываться |
password | Пароль, который посетитель введёт перед переходом |
Запрос на curl:
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-код
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. Посмотрите статистику
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+)
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)
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
$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-код.
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 — с какого места продолжить. Курсор следующей страницы приходит в ответе: передайте его в следующий запрос и повторяйте, пока страницы не закончатся.
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 в минуту | 60 | 300 |
| Глубина статистики | 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-кодами и статистикой переходов. Ссылки не отключаются за неоплату, сервер — в Казахстане.