مستندات جامع API

معرفی

API تی‌تی‌آر چیست؟

API تی‌تی‌آر یک وب‌سرویس REST مبتنی بر JSON است. با آن می‌توانید از داخل سایت، اپلیکیشن، CRM یا ابزار اتوماسیون خود لینک کوتاه بسازید و لینک‌های حساب خود را مشاهده، ویرایش یا حذف کنید.

REST + JSONساختار استاندارد و ساده

Bearer Tokenاحراز هویت امن

نسخه‌بندی‌شدهمسیر پایدار v1

شروع سریع

شروع به کار در سه مرحله

تهیه اشتراک API

با حساب کاربری وارد شوید و اشتراک ۳۰ روزه API را خریداری کنید.

ساخت توکن

پس از پرداخت موفق وارد پنل API شوید، برای توکن نام انتخاب کنید و آن را بسازید. توکن فقط یک‌بار کامل نمایش داده می‌شود.

ارسال اولین درخواست

توکن را در هدر Authorization قرار دهید و درخواست را به مسیر نسخه ۱ ارسال کنید.

اولین درخواست cURL

curl -X POST "https://ttr.ir/api/v1/links" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/article",
    "custom_alias": "my-campaign",
    "password": "secret123",
    "utm": {
      "source": "instagram",
      "medium": "social",
      "campaign": "summer"
    }
  }'

مشخصات API

همه درخواست‌ها از HTTPS استفاده می‌کنند و پاسخ‌ها JSON هستند. شماره نسخه بخشی از آدرس است تا تغییرات آینده اتصال فعلی شما را خراب نکند.

Base URLhttps://ttr.ir/api/v1

Content Typeapplication/json

احراز هویت با توکن

تمام endpointها نیازمند توکن هستند. مقدار توکن را با پیشوند Bearer در هدر Authorization بفرستید. توکن را داخل URL یا Query String قرار ندهید.

هدرهای الزامی

Authorization: Bearer YOUR_TOKEN
Accept: application/json
Content-Type: application/json

توکن مانند رمز عبور است. آن را در کد سمت مرورگر، مخزن عمومی یا لاگ‌ها قرار ندهید. اگر توکن افشا شد، فوراً از پنل حذف و توکن جدید بسازید.

Endpointهای لینک

GET/api/v1/links

دریافت فهرست لینک‌ها

لینک‌های متعلق به حساب توکن را به ترتیب جدیدترین دریافت می‌کند. نتیجه صفحه‌بندی شده است.

نیازمند توکن

GEThttps://ttr.ir/api/v1/links

پارامترها

نام	محل	نوع	وضعیت	توضیح
per_page	Query	integer	اختیاری	تعداد ردیف هر صفحه؛ از ۱ تا ۱۰۰. مقدار پیش‌فرض ۲۰ است.
page	Query	integer	اختیاری	شماره صفحه موردنظر؛ مقدار پیش‌فرض ۱ است.

نمونه درخواست

cURL

curl "https://ttr.ir/api/v1/links?per_page=20&page=1" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

نمونه پاسخ موفق

JSON

{
  "current_page": 1,
  "data": [
    {
      "id": 123,
      "url": "https://example.com/article",
      "alias": "a1b2c3",
      "short_url": "https://ttr.ir/a1b2c3",
      "type": "auto",
      "status": "active",
      "utm": null,
      "is_password_protected": false,
      "created_at": "2026-08-02T12:00:00.000000Z",
      "updated_at": "2026-08-02T12:00:00.000000Z"
    }
  ],
  "per_page": 20,
  "total": 1,
  "last_page": 1,
  "next_page_url": null,
  "prev_page_url": null
}

200موفق401توکن نامعتبر403اشتراک غیرفعال

POST/api/v1/links

ساخت لینک کوتاه

یک لینک کوتاه جدید می‌سازد. آدرس دلخواه، رمز و UTM همگی اختیاری هستند.

نیازمند توکن

POSThttps://ttr.ir/api/v1/links

پارامترها

نام	محل	نوع	وضعیت	توضیح
url	JSON Body	string	الزامی	آدرس کامل مقصد با http یا https؛ حداکثر ۴۰۰۰ کاراکتر.
custom_alias	JSON Body	string	اختیاری	آدرس دلخواه ۳ تا ۶۴ کاراکتر؛ فقط حروف انگلیسی، عدد، خط تیره و زیرخط.
password	JSON Body	string	اختیاری	رمز لینک با طول ۴ تا ۶۴ کاراکتر. رمز به‌صورت هش ذخیره می‌شود.
utm.source	JSON Body	string	اختیاری	منبع کمپین؛ حداکثر ۱۰۰ کاراکتر.
utm.medium	JSON Body	string	اختیاری	رسانه کمپین؛ حداکثر ۱۰۰ کاراکتر.
utm.campaign	JSON Body	string	اختیاری	نام کمپین؛ حداکثر ۱۲۰ کاراکتر.
utm.term	JSON Body	string	اختیاری	عبارت کمپین؛ حداکثر ۱۲۰ کاراکتر.
utm.content	JSON Body	string	اختیاری	محتوای کمپین؛ حداکثر ۱۲۰ کاراکتر.

نمونه درخواست

cURL

curl -X POST "https://ttr.ir/api/v1/links" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/article",
    "custom_alias": "my-campaign",
    "password": "secret123",
    "utm": {
      "source": "instagram",
      "medium": "social",
      "campaign": "summer"
    }
  }'

نمونه پاسخ موفق

JSON

{
  "data": {
    "id": 124,
    "url": "https://example.com/article",
    "alias": "my-campaign",
    "short_url": "https://ttr.ir/my-campaign",
    "type": "manual",
    "status": "active",
    "utm": {
      "source": "instagram",
      "medium": "social",
      "campaign": "summer"
    },
    "is_password_protected": true,
    "created_at": "2026-08-02T12:10:00.000000Z",
    "updated_at": "2026-08-02T12:10:00.000000Z"
  }
}

201ساخته شد401توکن نامعتبر403اشتراک غیرفعال422ورودی نامعتبر429محدودیت درخواست

GET/api/v1/links/{id}

مشاهده یک لینک

جزئیات یک لینک را دریافت می‌کند. فقط لینک‌های متعلق به صاحب توکن قابل مشاهده هستند.

نیازمند توکن

GEThttps://ttr.ir/api/v1/links/{id}

پارامترها

نام	محل	نوع	وضعیت	توضیح
id	Path	integer	الزامی	شناسه عددی لینک که هنگام ساخت یا دریافت فهرست برگردانده شده است.

نمونه درخواست

cURL

curl "https://ttr.ir/api/v1/links/124" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

نمونه پاسخ موفق

JSON

{
  "data": {
    "id": 124,
    "url": "https://example.com/article",
    "alias": "my-campaign",
    "short_url": "https://ttr.ir/my-campaign",
    "type": "manual",
    "status": "active",
    "utm": null,
    "is_password_protected": false,
    "created_at": "2026-08-02T12:10:00.000000Z",
    "updated_at": "2026-08-02T12:10:00.000000Z"
  }
}

200موفق401توکن نامعتبر403اشتراک غیرفعال404لینک یافت نشد

PUT/api/v1/links/{id}

ویرایش مقصد لینک

آدرس مقصد و اطلاعات UTM لینک را تغییر می‌دهد. نام کوتاه لینک در این عملیات تغییر نمی‌کند.

نیازمند توکن

PUThttps://ttr.ir/api/v1/links/{id}

پارامترها

نام	محل	نوع	وضعیت	توضیح
id	Path	integer	الزامی	شناسه عددی لینک.
url	JSON Body	string	الزامی	آدرس جدید مقصد با http یا https؛ حداکثر ۴۰۰۰ کاراکتر.
utm	JSON Body	object	اختیاری	مقادیر UTM جدید. برای حذف UTM مقدار null ارسال کنید.

نمونه درخواست

cURL

curl -X PUT "https://ttr.ir/api/v1/links/124" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/new-article",
    "utm": {
      "source": "newsletter",
      "medium": "email"
    }
  }'

نمونه پاسخ موفق

JSON

{
  "data": {
    "id": 124,
    "url": "https://example.com/new-article",
    "alias": "my-campaign",
    "short_url": "https://ttr.ir/my-campaign",
    "type": "manual",
    "status": "active",
    "utm": {
      "source": "newsletter",
      "medium": "email"
    },
    "is_password_protected": false
  }
}

200ویرایش شد401توکن نامعتبر403اشتراک غیرفعال404لینک یافت نشد422ورودی نامعتبر

DELETE/api/v1/links/{id}

حذف لینک

لینک متعلق به صاحب توکن را حذف می‌کند. پس از حذف، آدرس کوتاه دیگر قابل استفاده نیست.

نیازمند توکن

DELETEhttps://ttr.ir/api/v1/links/{id}

پارامترها

نام	محل	نوع	وضعیت	توضیح
id	Path	integer	الزامی	شناسه عددی لینک.

نمونه درخواست

cURL

curl -X DELETE "https://ttr.ir/api/v1/links/124" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

پاسخ

HTTP 204

بدون بدنه پاسخ (No Content)

204حذف شد401توکن نامعتبر403اشتراک غیرفعال404لینک یافت نشد

ساختار شیء Link

در پاسخ endpointهای لینک، هر رکورد با ساختار زیر برگردانده می‌شود.

Link Object

{
  "id": 124,                  // شناسه داخلی لینک
  "url": "https://...",       // آدرس مقصد
  "alias": "a1b2c3",          // بخش کوتاه آدرس
  "short_url": "https://...", // آدرس کوتاه کامل
  "type": "auto",             // auto یا manual
  "status": "active",         // وضعیت لینک
  "utm": null,                // اطلاعات UTM یا null
  "is_password_protected": false,
  "created_at": "...",        // تاریخ ISO 8601
  "updated_at": "..."
}

صفحه‌بندی

endpoint فهرست لینک‌ها صفحه‌بندی می‌شود. با پارامترهای page و per_page صفحه موردنظر را انتخاب کنید. از next_page_url و prev_page_url نیز می‌توانید برای حرکت بین صفحات استفاده کنید.

فیلد	توضیح
current_page	شماره صفحه فعلی
data	آرایه لینک‌های همین صفحه
per_page	تعداد ردیف در هر صفحه
total	تعداد کل لینک‌ها
last_page	شماره آخرین صفحه
next_page_url	آدرس صفحه بعد یا null
prev_page_url	آدرس صفحه قبل یا null

خطاها

کد HTTP نتیجه درخواست را مشخص می‌کند. برای خطاهای اعتبارسنجی، جزئیات هر فیلد داخل errors قرار می‌گیرد.

کد	معنی	راه‌حل
200 / 201 / 204	درخواست موفق	پاسخ را بر اساس endpoint پردازش کنید.
401	توکن نامعتبر یا ارسال نشده	هدر Authorization و توکن را بررسی کنید.
403	اشتراک API فعال نیست یا مجوز کافی نیست	اشتراک را تمدید یا وضعیت حساب را بررسی کنید.
404	منبع وجود ندارد یا متعلق به شما نیست	شناسه لینک و مالکیت آن را بررسی کنید.
422	داده ورودی معتبر نیست	فیلدهای آبجکت errors را اصلاح کنید.
429	تعداد درخواست بیشتر از حد مجاز است	تا زمان Retry-After صبر کنید.
500	خطای داخلی سرویس	درخواست را بعداً تکرار و در صورت تداوم با پشتیبانی تماس بگیرید.

خطای اعتبارسنجی

HTTP 422

{
  "message": "The url field is required.",
  "errors": {
    "url": [
      "The url field is required."
    ]
  }
}

اشتراک غیرفعال

HTTP 403

{
  "message": "اشتراک API شما فعال نیست یا به پایان رسیده است.",
  "code": "api_subscription_required"
}

محدودیت تعداد درخواست

برای حفظ پایداری سرویس، هر حساب می‌تواند حداکثر ۶۰ درخواست در دقیقه ارسال کند. پس از عبور از حد، پاسخ 429 دریافت می‌کنید.

X-RateLimit-Limitحد مجاز

X-RateLimit-Remainingدرخواست باقی‌مانده

Retry-Afterزمان انتظار پس از محدودیت

مستندات API توسعه‌دهندگان TTR

لینک‌های TTR را از داخل محصول خود مدیریت کنید

API تی‌تی‌آر چیست؟

شروع به کار در سه مرحله

تهیه اشتراک API

ساخت توکن

ارسال اولین درخواست

مشخصات API

احراز هویت با توکن

دریافت فهرست لینک‌ها

پارامترها

نمونه درخواست

نمونه پاسخ موفق

ساخت لینک کوتاه

پارامترها

نمونه درخواست

نمونه پاسخ موفق

مشاهده یک لینک

پارامترها

نمونه درخواست

نمونه پاسخ موفق

ویرایش مقصد لینک

پارامترها

نمونه درخواست

نمونه پاسخ موفق

حذف لینک

پارامترها

نمونه درخواست

پاسخ

ساختار شیء Link

خطاها

خطای اعتبارسنجی

اشتراک غیرفعال

محدودیت تعداد درخواست