Документация 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
statusactive — работает; disabled — выключена вами; review — на проверке безопасности; blocked — заблокирована за нарушение правил
is_customtrue — свой адрес, false — случайный код
expires_at, expiredКогда перестанет открываться (ISO 8601) или null; expired — срок уже истёк
has_passwordСпрашивает ли пароль перед переходом
clicks, qr_scansПереходов за всё время без ботов и сколько из них — по QR-коду

Новые поля могут добавляться — не полагайтесь на их отсутствие.

Создать ссылку

POST/api/v1/links
ПолеЧто значит
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 и начинают работать после ручной проверки.

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

GET/api/v1/links?limit=20&cursor=…&q=…&tag=…&status=…
ПараметрЧто значит
limitСколько ссылок вернуть: 1–100, по умолчанию 20
cursorКурсор следующей страницы из next_cursor предыдущего ответа
qПоиск по коду, названию и адресу назначения
tagТолько ссылки с этим тегом
statusactive, disabled, review или blocked
Ответ
{ "links": [ { "id": 1042, "code": "menu", … } ], "next_cursor": "1000", "total": 127 }

Новые ссылки — сверху. next_cursor: null — это последняя страница.

Одна ссылка

GET/api/v1/links/{id}

Ответ — объект ссылки или 404 not_found.

Изменить ссылку

PATCH/api/v1/links/{id}
ПолеЧто значит
target_urlНовый адрес назначения. Короткая ссылка и QR-код остаются прежними — перепечатывать ничего не нужно
titleНазвание
tagsТеги — массив целиком заменяет прежний
statusactive или 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.

Удалить ссылку

DELETE/api/v1/links/{id}

Ответ — { "ok": true, "id": 1042 }. Удалённая ссылка перестаёт открываться, напечатанные QR с ней не сработают. Если нужно просто временно выключить — используйте PATCH { "status": "disabled" }.

Статистика

GET/api/v1/links/{id}/stats?from=2026-10-01&to=2026-10-17
ПараметрЧто значит
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-код

GET/api/v1/links/{id}/qr?format=svg&size=1024&color=0c111d&bg=ffffff&margin=2
ПараметрЧто значит
formatsvg (по умолчанию) — вектор для печати; png — картинка
sizeСторона в пикселях: 64–2048, по умолчанию 512
color, bgЦвет модулей и фона в hex, удобнее без #: 0c111d. Код должен быть заметно темнее фона, иначе 422 invalid_request
marginПоле вокруг кода в модулях: 0–10, по умолчанию 2

Ответ — сам файл (image/svg+xml или image/png). Код ведёт на короткую ссылку с пометкой QR, поэтому сканы видны в статистике отдельно. Логотип и форму модулей настраивайте в конструкторе в кабинете.

Аккаунт

GET/api/v1/me
Ответ
{
  "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 уже занят" } }
400 invalid_json
Тело запроса — не JSON
401 unauthorized, invalid_key
Нет ключа, ключ неверный или отозван
402 plan_required
Тариф не позволяет: API, свой адрес, теги, UTM-метки, пароль, срок действия или смену адреса назначения
402 links_limit
Все ссылки тарифа заняты — удалите ненужные или перейдите на тариф выше
403 link_blocked
Ссылка заблокирована за нарушение правил — менять и включать её нельзя
404 not_found
Ссылки нет в вашем аккаунте или она удалена
409 alias_taken, alias_reserved
Свой адрес уже занят или зарезервирован
422 invalid_url
Неверный адрес: не http/https, нет домена, внутренняя сеть, ссылка на сам snap.kz, длиннее 2 000 символов
422 unsafe_url
Адрес запрещён правилами или помечен как опасный (фишинг, вредоносные программы)
422 invalid_alias, invalid_tags, invalid_utm, invalid_expires, invalid_password, invalid_status
Неверное значение поля
422 invalid_request
Нет обязательного поля, неизвестное поле в PATCH, неверный параметр запроса или цвета QR
429 rate_limited
Больше запросов в минуту, чем позволяет тариф; сколько ждать — в заголовке Retry-After
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:
        break

MCP: ссылки и статистика для ИИ-агентов

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_qrQR-код ссылки (по 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».

Начать