Ҳуҷҷатҳои API
REST API барои сохтани пайвандҳои кӯтоҳ ва гирифтани таҳлил. Барои ҳамгироӣ аз ҳар забон мувофиқ аст — танҳо калиди API-и худро фиристед.
Оғози зуд
- Бақайд гиред ва бахши Калидҳои API -ро дар кабинет кушоед.
- Калид созед ва нусха бардоред (як бор нишон дода мешавад).
- Калидро дар сарлавҳаи
Authorization.
curl -X POST https://link.tj/api/v1/links \
-H "Authorization: Bearer lnktj_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com/a/very/long/link"}'Аутентификатсия
Ҳар дархост бояд сарлавҳаи Authorization: Bearer <key> (ё X-Api-Key: <key>)-ро дар бар гирад. URL-и асосӣ:
https://link.tj/api/v1Калидҳо ба ҳисоби шумо пайвастанд, бинобар ин ҳамон маҳдудиятҳои тариф амал мекунанд. CORS кушода аст (*); API-ро аз браузер даъват кардан мумкин аст.
Шартҳо ва талабот
- Ҳисоб дар link.tj ва API-калиди сохташуда лозим аст (бахши «API-калидҳо»).
- Калид як бор нишон дода мешавад — фавран нигоҳ доред.
- Сарварақи Authorization: Bearer <key> ё X-Api-Key: <key>-ро фиристед.
- Маҳдудиятҳои тарифи шумо амал мекунанд.
- Маҳдудияти суръат: 120 дархост дар як дақиқа барои ҳар калид (вагарна 429 бо retryAfter).
- CORS кушода аст (*) — API-ро аз браузер даъват кардан мумкин аст.
Аутентификатсия барои барномаҳо (мобилӣ)
Барномаҳои мобилӣ ва нативӣ токенро бо email ва парол мегиранд: POST /api/auth/token. Дар ҷавоб JWT меояд, ки онро ба /api/v1/* мисли API-калид мефиристед: Authorization: Bearer <token>. Агар 2FA фаъол бошад, майдони code-ро илова кунед; бе он 401 бо error: needs_2fa бармегардад.
/api/auth/tokenВоридшавӣ бо email/парол → JWT барои /api/v1/*. Бадан: email, password, code? (барои 2FA).
Тарзи истифода: email ва паролро фиристед, то JWT барои барнома гиред.
curl -X POST https://link.tj/api/auth/token \
-H "Content-Type: application/json" \
-d '{"email":"you@example.com","password":"••••••••"}'Ҷавоб
{
"token": "eyJhbGciOi...",
"user": { "id": "clx...", "email": "you@example.com", "name": "You", "role": "USER" }
}Шартҳо ва талабот
- email ва парол ҳатмист (вагарна 400).
- Ҳисоб набояд маҳкам бошад (вагарна 403).
- Агар 2FA фаъол бошад — майдони code-ро илова кунед; бе он 401 бо error: needs_2fa.
- Маҳдудият: 30 кӯшиш дар 15 дақиқа барои IP ва 10 барои email (вагарна 429).
- JWT-и гирифташударо ба /api/v1/* ҳамчун Authorization: Bearer <token> фиристед.
Эндпоинтҳо
/api/v1/meҲисоб, тариф ва сарфи маҳдудиятҳои моҳона.
Тарзи истифода: Профил, тариф ва истеъмоли моҳи ҷориро дархост кунед.
curl https://link.tj/api/v1/me \
-H "Authorization: Bearer lnktj_API_KEY"Ҷавоб
{
"data": {
"email": "you@example.com",
"plan": { "name": "Free", "linkLimit": 5 },
"usage": { "linksUsed": 2, "linksRemaining": 3, "clicksUsed": 87 }
}
}Шартҳо ва талабот
- API-калид ё JWT-и эътиборнок лозим аст.
- Ҳисоб набояд маҳкам бошад.
- Танҳо GET — маълумот ба соҳиби калид тааллуқ дорад.
/api/v1/linksСохтани пайванди кӯтоҳ. Майдонҳо: url (барои kind=url ҳатмӣ), slug (ихтиёрӣ), title (ихтиёрӣ), kind (ихтиёрӣ: url | wifi | vcard | text), payload (объект барои навъҳои ғайри url).
Навъҳои wifi/vcard/text дар тарифҳои пулакӣ дастрасанд (вагарна 403). Чунин QR ба саҳифаи пайгиришавандаи /l/{slug} мебарад.
Тарзи истифода: JSON-ро бо майдони url (пайванди оддӣ) ё kind + payload (пайванди типӣ) фиристед.
curl -X POST https://link.tj/api/v1/links \
-H "Authorization: Bearer lnktj_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com","slug":"promo","title":"Promo"}'Намуна: Wi-Fi (тарифи пулакӣ)
curl -X POST https://link.tj/api/v1/links \
-H "Authorization: Bearer lnktj_API_KEY" \
-H "Content-Type: application/json" \
-d '{"kind":"wifi","title":"Guest Wi-Fi","payload":{"ssid":"MyNet","encryption":"WPA","password":"secret123"}}'Ҷавоби 201
{
"data": {
"id": "clx...",
"slug": "promo",
"shortUrl": "https://link.tj/promo",
"kind": "url",
"originalUrl": "https://example.com",
"summary": null,
"clicks": 0
},
"usage": { "linksUsed": 3, "linkLimit": 5, "linksRemaining": 2 }
}Ҷавоби 402 — маҳдудияти тариф расид
{
"error": "limit_reached",
"code": "limit_reached",
"recommend": { "name": "Core", "priceMonthly": 8, "linkLimit": 100 }
}Шартҳо ва талабот
- url ҳатмист ва бояд http(s)-и дуруст бошад ҳангоми kind=url (вагарна 400).
- slug ихтиёрист; агар ишғол бошад — 409, агар холӣ бошад — худкор сохта мешавад.
- kind: url | wifi | vcard | text (пешфарз url).
- Навъҳои wifi/vcard/text тарифи пулакӣ (вагарна 403) ва майдони payload талаб мекунанд.
- title ихтиёрист, на бештар аз 200 аломат.
- Ҳангоми расидан ба ҳудуди пайвандҳои тариф — 402 бо тарифи тавсияшуда.
- Сарлавҳаи X-Client: telegram | mobile манбаи сохтани пайвандро қайд мекунад (пешфарз api) — дар таҳлили манбаъҳо дида мешавад.
- Дар тарифи ройгон ҳангоми ба охир расидани ҳудуди моҳона огоҳинома бо пешниҳоди баланд бардоштани тариф меояд (дар кабинет, Telegram ва бо SMS); фавран, бе интизори охири моҳ, баланд бардоштан мумкин аст.
/api/v1/linksРӯйхати пайвандҳои шумо. Параметрҳо: limit (1–100), offset.
Тарзи истифода: Пайвандҳои худро бо саҳифабандӣ гиред.
curl "https://link.tj/api/v1/links?limit=20&offset=0" \
-H "Authorization: Bearer lnktj_API_KEY"Ҷавоб — рӯйхат
{
"total": 42,
"limit": 20,
"offset": 0,
"data": [
{ "id": "clx...", "slug": "promo", "shortUrl": "https://link.tj/promo", "kind": "url",
"originalUrl": "https://example.com", "clicks": 128, "isActive": true }
]
}Шартҳо ва талабот
- limit аз 1 то 100 (пешфарз 50).
- offset ≥ 0 барои саҳифабандӣ.
- Танҳо пайвандҳои соҳиби калид бармегарданд; майдони total — шумораи умумӣ.
/api/v1/links/{id_or_slug}Тафсилоти пайванд ва таҳлили гузаришҳо (аз рӯи кишвар, дастгоҳ, манбаъ).
Тарзи истифода: id ё slug-и пайвандро фиристед, то тафсилот ва таҳлили кликҳоро гиред.
curl https://link.tj/api/v1/links/promo \
-H "Authorization: Bearer lnktj_API_KEY"Ҷавоб — тафсилот ва таҳлил
{
"data": {
"id": "clx...", "slug": "promo", "shortUrl": "https://link.tj/promo",
"originalUrl": "https://example.com", "clicks": 128, "isActive": true,
"analytics": {
"byCountry": [ { "name": "TJ", "count": 80 }, { "name": "RU", "count": 48 } ],
"byDevice": [ { "name": "mobile", "count": 95 }, { "name": "desktop", "count": 33 } ],
"byReferrer": [ { "name": "t.me", "count": 60 }, { "name": "Unknown", "count": 68 } ]
}
}
}Шартҳо ва талабот
- Ҳам id ва ҳам slug қабул мешавад.
- Пайванд бояд ба соҳиби калид тааллуқ дошта бошад (вагарна 404).
- Дар ҷавоб блоки analytics: тақсим аз рӯи кишвар, дастгоҳ ва манбаъ.
/api/v1/links/{id_or_slug}Тағйири пайванд: фаъолӣ (isActive) ва феҳраст (folderId).
Тарзи истифода: id ё slug ва танҳо майдонҳоеро, ки тағйир додан мехоҳед, фиристед.
curl -X PATCH https://link.tj/api/v1/links/promo \
-H "Authorization: Bearer lnktj_API_KEY" \
-H "Content-Type: application/json" \
-d '{"isActive":false}'Ҷавоб
{
"data": { "id": "clx...", "slug": "promo", "title": "Promo", "isActive": false, "folderId": null }
}Шартҳо ва талабот
- Пайванд бояд ба соҳиби калид тааллуқ дошта бошад (вагарна 404).
- isActive (boolean) — равонкунии пайвандро фаъол ё ғайрифаъол мекунад.
- folderId (string | null) — пайвандро ба феҳраст гузаронед ё аз он бароред.
- Дар ҷавоб объекти навшуда: id, slug, title, isActive, folderId.
/api/v1/links/{id_or_slug}Нест кардани пайванд ва таҳлили он.
Тарзи истифода: id ё slug-ро фиристед, то пайвандро нест кунед.
curl -X DELETE https://link.tj/api/v1/links/promo \
-H "Authorization: Bearer lnktj_API_KEY"Шартҳо ва талабот
- Пайванд бояд ба соҳиби калид тааллуқ дошта бошад (вагарна 404).
- Несткунӣ нарм аст: пайванд ғайрифаъол шуда, ба бахши «Несткардашуда» меравад; таҳлили он нигоҳ дошта мешавад.
- То охири давраи ҷорӣ пайванд дар ҳудуди моҳонаи тариф ба ҳисоб гирифта мешавад (ҳифз аз гузаштан аз квота).
Вебхукҳо (рӯйдодҳои содиротӣ)
URL-ро дар бахши «Вебхукҳо»-и кабинет пайваст кунед — ҳангоми рӯйдод мо ба сервери шумо POST мефиристем. Бадан: { event, data, ts }. Сарварақҳо: X-LinkTJ-Event ва X-LinkTJ-Signature.
Тарзи истифода: URL-ро илова карда, дар бахши «Вебхукҳо» ба рӯйдодҳо обуна шавед, баъд имзоро дар сервери худ тафтиш кунед.
Рӯйдодҳо
link.created— link.created — пайванди кӯтоҳ сохта шуд. data: { id, slug, url }.subscription.created— subscription.created — обуна оғоз ё тамдид шуд. data: { plan, amount, interval }.
POST https://your-server.example/webhook
X-LinkTJ-Event: link.created
X-LinkTJ-Signature: <hmac-sha256-hex>
Content-Type: application/json
{ "event": "link.created", "data": { "id": "clx...", "slug": "promo", "url": "https://example.com" }, "ts": "2026-01-01T12:00:00.000Z" }Сарварақи X-LinkTJ-Signature ин HMAC-SHA256-и бадани дархост аст, ки бо махфии вебхук (whsec_…) имзо шудааст. Онро муқоиса кунед, то боварӣ ҳосил кунед, ки дархост аз link.tj омадааст.
Шартҳо ва талабот
- URL бояд https-и оммавӣ бошад — суроғаҳои дохилӣ ва маҳаллӣ манъ аст (ҳифз аз SSRF).
- Ҳадди ақал ба як рӯйдод обуна шавед (link.created, subscription.created).
- X-LinkTJ-Signature = HMAC-SHA256(бадани дархост, махфии whsec_…)-ро тафтиш кунед.
- Суроға ҳангоми расонидан дубора тафтиш мешавад (ҳифз аз DNS-rebinding); редиректҳо иҷро намешаванд.
- Вақти расонидан 5 сония; бо коди 2xx ҷавоб диҳед.
Вазифаҳои банақшагирифташуда (cron)
Банақшагири берунӣ метавонад тамдиди обуна ва ҳисоботи ҳафтаинаро бо махфӣ оғоз кунад: ?secret=<CRON_SECRET>. Параметри task: renew, weekly ё all (пешфарз all).
Тарзи истифода: Банақшагири берунаро ба даъвати эндпоинт бо махфӣ танзим кунед.
/api/cron?secret=&task=renew|weekly|allcurl -X POST "https://link.tj/api/cron?secret=CRON_SECRET&task=renew"Шартҳо ва талабот
- ?secret=<CRON_SECRET>-ро фиристед (ё аз сессияи суперадмин даъват кунед).
- task: renew | weekly | all (пешфарз all).
- Усул GET ё POST.
Рамзҳои ҷавоб
| 200 / 201 | Бомуваффақият |
| 400 | Дархости нодуруст (масалан, URL ё slug-и нодуруст) |
| 401 | Калиди API нест ё нодуруст |
| 402 | Маҳдудияти тариф расид — баланд бардоштани тариф лозим аст |
| 403 | Дастрасӣ манъ аст (масалан, навъҳои wifi/vcard/text дар тарифи ройгон) |
| 404 | Пайванд ёфт нашуд |
| 409 | Slug аллакай ишғол шудааст |
| 429 | Дархостҳои аз ҳад зиёд — маҳдудияти суръат сар шуд |