> lnk.tj

Ҳуҷҷатҳои API

REST API барои сохтани пайвандҳои кӯтоҳ ва гирифтани таҳлил. Барои ҳамгироӣ аз ҳар забон мувофиқ аст — танҳо калиди API-и худро фиристед.

Оғози зуд

  1. Бақайд гиред ва бахши Калидҳои API -ро дар кабинет кушоед.
  2. Калид созед ва нусха бардоред (як бор нишон дода мешавад).
  3. Калидро дар сарлавҳаи Authorization.
bash
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-и асосӣ:

text
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 бармегардад.

POST/api/auth/token

Воридшавӣ бо email/парол → JWT барои /api/v1/*. Бадан: email, password, code? (барои 2FA).

Тарзи истифода: email ва паролро фиристед, то JWT барои барнома гиред.

bash
curl -X POST https://link.tj/api/auth/token \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"••••••••"}'

Ҷавоб

json
{
  "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> фиристед.

Эндпоинтҳо

GET/api/v1/me

Ҳисоб, тариф ва сарфи маҳдудиятҳои моҳона.

Тарзи истифода: Профил, тариф ва истеъмоли моҳи ҷориро дархост кунед.

bash
curl https://link.tj/api/v1/me \
  -H "Authorization: Bearer lnktj_API_KEY"

Ҷавоб

json
{
  "data": {
    "email": "you@example.com",
    "plan": { "name": "Free", "linkLimit": 5, "clickLimit": 1000 },
    "usage": { "linksUsed": 2, "linksRemaining": 3, "clicksUsed": 87 }
  }
}

Шартҳо ва талабот

  • API-калид ё JWT-и эътиборнок лозим аст.
  • Ҳисоб набояд маҳкам бошад.
  • Танҳо GET — маълумот ба соҳиби калид тааллуқ дорад.
POST/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 (пайванди типӣ) фиристед.

bash
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 (тарифи пулакӣ)

bash
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

json
{
  "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 — маҳдудияти тариф расид

json
{
  "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 бо тарифи тавсияшуда.
GET/api/v1/links

Рӯйхати пайвандҳои шумо. Параметрҳо: limit (1–100), offset.

Тарзи истифода: Пайвандҳои худро бо саҳифабандӣ гиред.

bash
curl "https://link.tj/api/v1/links?limit=20&offset=0" \
  -H "Authorization: Bearer lnktj_API_KEY"

Ҷавоб — рӯйхат

json
{
  "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 — шумораи умумӣ.
GET/api/v1/links/{id_or_slug}

Тафсилоти пайванд ва таҳлили гузаришҳо (аз рӯи кишвар, дастгоҳ, манбаъ).

Тарзи истифода: id ё slug-и пайвандро фиристед, то тафсилот ва таҳлили кликҳоро гиред.

bash
curl https://link.tj/api/v1/links/promo \
  -H "Authorization: Bearer lnktj_API_KEY"

Ҷавоб — тафсилот ва таҳлил

json
{
  "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: тақсим аз рӯи кишвар, дастгоҳ ва манбаъ.
DELETE/api/v1/links/{id_or_slug}

Нест кардани пайванд ва таҳлили он.

Тарзи истифода: id ё slug-ро фиристед, то пайвандро нест кунед.

bash
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 }.
http
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).

Тарзи истифода: Банақшагири берунаро ба даъвати эндпоинт бо махфӣ танзим кунед.

POST/api/cron?secret=&task=renew|weekly|all
bash
curl -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Пайванд ёфт нашуд
409Slug аллакай ишғол шудааст
429Дархостҳои аз ҳад зиёд — маҳдудияти суръат сар шуд

Барои оғоз омодаед?

Ҳисоби ройгон созед ва дар як дақиқа калиди API гиред.

Гирифтани калид