Документация API
Базовый адрес: https://snap.kz/api/v1. Запросы и ответы — JSON в UTF-8. Через API можно создать, найти, изменить и удалить ссылку, получить её статистику и QR-код, узнать тариф и лимиты. Логотип в QR, оплата и загрузка ссылок из CSV — только в кабинете.
API и MCP-сервер работают на тарифах «Про» и «Бизнес». На бесплатном тарифе запросы получат ошибку 402 plan_required — сравнить тарифы.
Авторизация
Ключ создаётся в кабинете, раздел «API и MCP». Он показывается один раз — сохраните его в надёжном месте; мы храним только хеш и показать ключ повторно не сможем. Потеряли — выпустите новый, старый перестанет работать. Ключ передаётся в заголовке:
Authorization: Bearer sk_…
Без ключа — 401 unauthorized, с неверным или отозванным — 401 invalid_key. Держите ключ на сервере, не вставляйте его в код страниц и мобильных приложений. GET /me отвечает с ключом на любом тарифе — видно, какие функции открыты.
Лимиты
| Лимит | Про / Бизнес |
|---|---|
| запросов в минуту | 60 / 300 на аккаунт |
| новых ссылок в сутки | 300 / 3 000 |
| активных ссылок | 1 000 / 10 000 |
| глубина статистики | 365 дней / 1095 дней |
Превысили минутный лимит — 429 rate_limited и заголовок Retry-After (через сколько секунд повторить); лимит указан в заголовке X-RateLimit-Limit. Новых ссылок за сутки больше лимита — 429 daily_limit; все ссылки тарифа заняты — 402 links_limit. Сколько использовано — GET /me.
Объект ссылки
{
"id": 1042,
"code": "menu",
"short_url": "https://snap.kz/menu",
"qr_url": "https://snap.kz/menu?qr",
"target_url": "https://cafe-alma.kz/menu/osen-2026",
"title": "Осеннее меню",
"tags": ["меню", "алматы"],
"utm": { "source": "qr", "medium": "offline", "campaign": "osen-2026" },
"is_custom": true,
"status": "active",
"expired": false,
"has_password": false,
"expires_at": null,
"clicks": 2178,
"qr_scans": 1428,
"last_click_at": "2026-10-17T09:41:12.000Z",
"created_at": "2026-10-01T06:00:00.000Z",
"updated_at": "2026-10-15T12:30:00.000Z"
}| Поле | Что значит |
|---|---|
| id | Идентификатор ссылки. Везде, где в адресе {id}, можно передать и код ссылки: /links/menu |
| code | Код после snap.kz/. Случайный — 6 символов с учётом регистра; свой адрес — в нижнем регистре |
| short_url | Короткая ссылка — её публикуйте и отправляйте |
| qr_url | Адрес для QR-кода: короткая ссылка с пометкой ?qr — переходы по ней считаются сканами. Готовая картинка — GET /links/{id}/qr |
| target_url | Адрес назначения — как вы его передали. Метки из utm в нём не видны: мы дописываем их при переходе |
| utm | Метки ссылки { source, medium, campaign, term, content } или null |
| status | active — работает; disabled — выключена вами; review — на проверке безопасности; blocked — заблокирована за нарушение правил |
| is_custom | true — свой адрес, false — случайный код |
| expires_at, expired | Когда перестанет открываться (ISO 8601) или null; expired — срок уже истёк |
| has_password | Спрашивает ли пароль перед переходом |
| clicks, qr_scans | Переходов за всё время без ботов и сколько из них — по QR-коду |
Новые поля могут добавляться — не полагайтесь на их отсутствие.
Создать ссылку
| Поле | Что значит |
|---|---|
| url | обязательно. Адрес назначения: http или https, до 2 000 символов |
| alias | Свой адрес: 3–50 символов, латиница, цифры, - и _, начинается и заканчивается буквой или цифрой; хранится в нижнем регистре. Без него — случайный код |
| title | Название для себя — видно в кабинете и API |
| tags | До 10 тегов, массив строк: ["меню", "алматы"] |
| utm | Метки { source, medium, campaign, term, content }, каждая до 200 символов — допишем к адресу назначения при переходе (заменят такие же метки в самом адресе) |
| expires_at | Срок действия: 2026-12-31 или ISO 8601, в будущем и не дальше 10 лет |
| password | Пароль, который спросим перед переходом: 4–100 символов |
curl -X POST https://snap.kz/api/v1/links \
-H "Authorization: Bearer $SNAP_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://cafe-alma.kz/menu/osen-2026",
"alias": "menu",
"title": "Осеннее меню",
"tags": ["меню"],
"utm": { "source": "qr", "medium": "offline", "campaign": "osen-2026" }
}'Ответ — 201 и объект ссылки. Свой адрес занят — 409 alias_taken; неверный адрес — 422 invalid_url; адрес запрещён или опасен — 422 unsafe_url.
Подозрительные адреса (например, похожие на страницы банков или госуслуг) создаются со статусом review и начинают работать после ручной проверки.
Список ссылок
| Параметр | Что значит |
|---|---|
| limit | Сколько ссылок вернуть: 1–100, по умолчанию 20 |
| cursor | Курсор следующей страницы из next_cursor предыдущего ответа |
| q | Поиск по коду, названию и адресу назначения |
| tag | Только ссылки с этим тегом |
| status | active, disabled, review или blocked |
{ "links": [ { "id": 1042, "code": "menu", … } ], "next_cursor": "1000", "total": 127 }Новые ссылки — сверху. next_cursor: null — это последняя страница.
Одна ссылка
Ответ — объект ссылки или 404 not_found.
Изменить ссылку
| Поле | Что значит |
|---|---|
| target_url | Новый адрес назначения. Короткая ссылка и QR-код остаются прежними — перепечатывать ничего не нужно |
| title | Название |
| tags | Теги — массив целиком заменяет прежний |
| status | active или disabled — включить или выключить ссылку |
| expires_at | Новый срок действия или null — бессрочно |
| password | Новый пароль; пустая строка — убрать пароль |
| utm | Новые метки |
curl -X PATCH https://snap.kz/api/v1/links/1042 \
-H "Authorization: Bearer $SNAP_KEY" \
-H "Content-Type: application/json" \
-d '{ "target_url": "https://cafe-alma.kz/menu/zima-2026" }'Передавайте только поля, которые меняете; неизвестное поле — 422 invalid_request. Ответ — обновлённый объект ссылки. Заблокированную ссылку менять нельзя — 403 link_blocked.
Удалить ссылку
Ответ — { "ok": true, "id": 1042 }. Удалённая ссылка перестаёт открываться, напечатанные QR с ней не сработают. Если нужно просто временно выключить — используйте PATCH { "status": "disabled" }.
Статистика
| Параметр | Что значит |
|---|---|
| from, to | Даты YYYY-MM-DD по времени Алматы, включительно. По умолчанию — последние 30 дней |
| days | Последние N дней — вместо from |
| group | Только day — ряд по дням (можно не передавать) |
{
"link_id": 1042, "code": "menu", "from": "2026-10-10", "to": "2026-10-17", "group": "day",
"total": 512, "uniques": 431, "qr": 341, "bots": 37,
"series": [ { "day": "2026-10-10", "clicks": 61, "uniques": 52, "qr": 40 }, … ],
"cities": [ { "name": "Алматы", "clicks": 225 }, { "name": "Астана", "clicks": 108 }, … ],
"countries": [ { "code": "KZ", "name": "Казахстан", "clicks": 498 }, … ],
"devices": [ { "type": "mobile", "name": "Телефон", "clicks": 470 }, … ],
"os": [ { "name": "Android", "clicks": 251 }, … ],
"browsers": [ { "name": "Chrome", "clicks": 230 }, … ],
"referrers": [ { "host": "instagram.com", "name": "instagram.com", "clicks": 96 }, … ],
"languages": [ { "code": "ru", "name": "Русский", "clicks": 401 }, … ],
"hours": [ …24 числа — переходы по часам суток… ],
"previews": [ { "name": "Telegram", "hits": 21 }, … ]
}qr — переходы по QR-коду (код ведёт на https://snap.kz/<код>?qr, метку мы убираем перед переходом). Боты и превью ссылок в мессенджерах в переходы не входят — они отдельно в bots и previews. Период шире, чем позволяет тариф, сокращается до глубины тарифа, а в ответе появляется поле notice. Город определяется по IP приблизительно (IP-геолокация: DB-IP.com).
QR-код
| Параметр | Что значит |
|---|---|
| format | svg (по умолчанию) — вектор для печати; png — картинка |
| size | Сторона в пикселях: 64–2048, по умолчанию 512 |
| color, bg | Цвет модулей и фона в hex, удобнее без #: 0c111d. Код должен быть заметно темнее фона, иначе 422 invalid_request |
| margin | Поле вокруг кода в модулях: 0–10, по умолчанию 2 |
Ответ — сам файл (image/svg+xml или image/png). Код ведёт на короткую ссылку с пометкой QR, поэтому сканы видны в статистике отдельно. Логотип и форму модулей настраивайте в конструкторе в кабинете.
Аккаунт
{
"id": 77, "email": "owner@cafe-alma.kz", "name": "Айгерим", "company": "ТОО «Алма»",
"plan": "pro", "plan_title": "Про", "plan_until": "2026-11-16T06:00:00.000Z", "days_left": 30,
"limits": {
"links": 1000, "links_per_day": 300, "stats_days": 365, "api_per_minute": 60,
"custom_alias": true, "edit_target": true, "qr_logo": true, "full_stats": true, "password_expiry": true,
"export_csv": true, "api": true, "bulk": false, "tags": true, "utm": true
},
"usage": { "links": 127, "created_last_24h": 4 }
}Ошибки
Ошибка — HTTP-код и тело:
{ "error": { "code": "alias_taken", "message": "Адрес snap.kz/menu уже занят" } }| HTTP | code | Когда |
|---|---|---|
| 400 invalid_json | ||
| 400 | invalid_json | Тело запроса — не JSON |
| 401 unauthorized, invalid_key | ||
| 401 | unauthorized, invalid_key | Нет ключа, ключ неверный или отозван |
| 402 plan_required | ||
| 402 | plan_required | Тариф не позволяет: API, свой адрес, теги, UTM-метки, пароль, срок действия или смену адреса назначения |
| 402 links_limit | ||
| 402 | links_limit | Все ссылки тарифа заняты — удалите ненужные или перейдите на тариф выше |
| 403 link_blocked | ||
| 403 | link_blocked | Ссылка заблокирована за нарушение правил — менять и включать её нельзя |
| 404 not_found | ||
| 404 | not_found | Ссылки нет в вашем аккаунте или она удалена |
| 409 alias_taken, alias_reserved | ||
| 409 | alias_taken, alias_reserved | Свой адрес уже занят или зарезервирован |
| 422 invalid_url | ||
| 422 | invalid_url | Неверный адрес: не http/https, нет домена, внутренняя сеть, ссылка на сам snap.kz, длиннее 2 000 символов |
| 422 unsafe_url | ||
| 422 | unsafe_url | Адрес запрещён правилами или помечен как опасный (фишинг, вредоносные программы) |
| 422 invalid_alias, invalid_tags, invalid_utm, invalid_expires, invalid_password, invalid_status | ||
| 422 | invalid_alias, invalid_tags, invalid_utm, invalid_expires, invalid_password, invalid_status | Неверное значение поля |
| 422 invalid_request | ||
| 422 | invalid_request | Нет обязательного поля, неизвестное поле в PATCH, неверный параметр запроса или цвета QR |
| 429 rate_limited | ||
| 429 | rate_limited | Больше запросов в минуту, чем позволяет тариф; сколько ждать — в заголовке Retry-After |
| 429 daily_limit | ||
| 429 | daily_limit | Исчерпан лимит новых ссылок за сутки |
Текст в message — для людей и может меняться; в коде программы проверяйте code.
Примеры кода
JavaScript (Node.js 18+)
const API = "https://snap.kz/api/v1";
const headers = { Authorization: `Bearer ${process.env.SNAP_KEY}`, "Content-Type": "application/json" };
// создать ссылку
const res = await fetch(`${API}/links`, {
method: "POST",
headers,
body: JSON.stringify({ url: "https://shop.kz/sale", alias: "sale", tags: ["акция"] }),
});
const link = await res.json();
if (!res.ok) throw new Error(`${link.error.code}: ${link.error.message}`);
console.log(link.short_url); // https://snap.kz/sale
// поменять, куда ведёт ссылка (QR перепечатывать не нужно)
await fetch(`${API}/links/${link.id}`, {
method: "PATCH",
headers,
body: JSON.stringify({ target_url: "https://shop.kz/sale-november" }),
});
// статистика за неделю
const stats = await (await fetch(`${API}/links/${link.id}/stats?from=2026-10-10&to=2026-10-17`, { headers })).json();
console.log(stats.total, stats.qr, stats.cities);Python
import os, requests
API = "https://snap.kz/api/v1"
H = {"Authorization": f"Bearer {os.environ['SNAP_KEY']}"}
r = requests.post(f"{API}/links", headers=H, json={"url": "https://shop.kz/sale", "alias": "sale"})
r.raise_for_status()
link = r.json()
print(link["short_url"])
# QR-код в SVG — для макета упаковки
svg = requests.get(f"{API}/links/{link['id']}/qr", headers=H, params={"format": "svg", "color": "0c111d"}).text
open("sale.svg", "w").write(svg)
# все ссылки с тегом, постранично
cursor = None
while True:
page = requests.get(f"{API}/links", headers=H, params={"tag": "акция", "limit": 100, "cursor": cursor}).json()
for item in page["links"]:
print(item["short_url"], item["clicks"])
cursor = page.get("next_cursor")
if not cursor:
breakMCP: ссылки и статистика для ИИ-агентов
MCP-сервер даёт ИИ-агенту — Claude Code, Codex, Cursor и другим клиентам MCP — шесть инструментов из таблицы ниже: всё, что умеет API, кроме удаления ссылок (удалить можно в кабинете или через DELETE). Попросите агента сделать ссылку для рассылки, поменять адрес у QR на упаковке или собрать отчёт по переходам за месяц.
| Инструмент | Что делает |
|---|---|
| create_link | Создать ссылку — поля как в POST /links |
| list_links | Найти ссылки: поиск, тег, постранично — как GET /links |
| get_link_stats | Статистика за период (from, to или days) — как GET /links/{id}/stats |
| update_link | Поменять адрес назначения, название, теги, статус, срок — как PATCH |
| make_qr | QR-код ссылки (по id или коду) в PNG или SVG; без id — статичный QR любого текста (text), без статистики |
| me | Тариф, лимиты и сколько использовано |
Сервер работает по HTTP (Streamable HTTP): JSON-RPC 2.0 методом POST на https://snap.kz/api/mcp, ключ — тот же API-ключ. Ошибки инструментов приходят текстом с теми же кодами, что в API.
Claude Code — одной командой
claude mcp add --transport http snap https://snap.kz/api/mcp --header "Authorization: Bearer sk_…"
Конфиг для любого MCP-клиента
{
"mcpServers": {
"snap": {
"type": "http",
"url": "https://snap.kz/api/mcp",
"headers": { "Authorization": "Bearer sk_…" }
}
}
}Получите API-ключ
Зарегистрируйтесь, подключите «Про» или «Бизнес» и создайте ключ в разделе «API и MCP».