تاینی لینک
خدمت‌دهنده
بازارچه پادیوم
مقدمه
سرویس لینک کوتاه امکان ایجاد لینک کوتاه برای لینک/متن را برای کاربران مهیا می‌سازد.به کمک این سرویس، قادر خواهید بود بجای ارسال لینک‌های/متن‌های با طول زیاد، لینک کوتاه شده آن را دریافت نمایید. پس از کلیک بر روی لینک کوتاه، اگر لینک کوتاه حاوی یک لینک باشد، به لینک مورد نظر redirect خواهید شد، درغیر اینصورت، متن مورد نظر برای کاربر نمایش داده خواهد شد. علاوه بر این، با کمک این سرویس می‌توان آمار کلیک بر روی لینک‌ها را هم رؤیت نمود.
پیش از شروع
- URL فراخوانی سرویس ها: https://api.pod.ir/srv/sc/nzh/doServiceCall
- تمامی درخواست ها با متد POST ارسال میشوند.
- Header درخواست:
پارامترهای زیر در Header تمام درخواست ها ثابت است:
| پارامتر | توضیحات |
|---|---|
| _token_ | API token دریافتی از پنل کسب و کاری |
| _token_issuer_ | این پارامتر دارای مقدار ثابت "1" است. |
| Content-Type | application/x-www-form-urlencoded |
- بدنه درخواست:
پارامترهای زیر در بدنه تمام درخواست ها ثابت است:
| پارامتر | توضیحات |
|---|---|
| scProductId | شناسه سرویس در حال استفاده |
| scApiKey | API Key دریافتی برای سرویس مورد نظر از پنل کسب و کاری |
- json Object ها در پارامتری به نام body ارسال میشوند.
- ساختار پاسخ دریافتی پس از فراخوانی سرویس به صورت زیر است که پاسخ دریافتی از endpoint مورد نظر در پارامتر result قرار دارد.
{
"hasError": false/true,
"messageId": 0,
"referenceNumber": "",
"errorCode": 0,
"count": 0,
"ott": "",
"result": {
"result": "response",
"header": {},
"statusCode":
}
}
افزودن لینک کوتاه
از این سرویس برای افزودن لینک کوتاه استفاده میشود.
نکته: آدرس لینک کوتاه شده پس از فراخوانی این سرویس به صورت زیر است:
که مقدار {hash} را در خروجی این سرویس دریافت میکنید.
- شناسه سرویس: 46410
- پارامترهای ورودی:
| پارامتر | اجباری/اختیاری | توضیحات |
|---|---|---|
| urlOrContent | اجباری | لینک یا متنی که قرار است لینک کوتاه آن ایجاد گردد |
| shortenObjectKind | اجباری | نوع لینک کوتاه شده file,link یا content |
| hash | اختیاری | یک کد یکتا که می تواند توسط خود فرد و یا سیستم اتخاذ گردد. اگر ارسال نشود، سیستم به صورت خودکار یک hash به لینک مربوطه اختصاص میدهد |
| tags | اختیاری | تگ هایی که روی لینک کوتاه ثبت میکنید (با ، جدا شوند). |
- پاسخ برگشتی در صورت موفقیت آمیز بودن:
{
"error": false,
"code": 200,
"result": {
"urlOrContent": "this is sample content",
"hash": "sample20",
"visitCount": 0,
"shortenObjectKind": content
}
}
- خطاهایی که ممکن است در کار با این متد پیش آید:
| کد | پارامتر | شرح |
|---|---|---|
| 401 | UNAUTHORIZED | عدم احراز هویت |
| 114 | URL_OR_Content_IS_NULL_OR_EMPTY | عدم مقداردهی urlOrContent |
| 116 | INVALID_PARAMETER | مقدار غیرمجاز برای پارامتر |
| 119 | CUSTOM_HASH_REPETETIVE | هش تکراری |
| 120 | HASH_IS_LONG | طول زیاد برای هش |
| 121 | URL_OR_CONTENT_REPETITIVE | لینک یا متن تکراری |
| 999 | INTERNAL_SERVER_EXCEPTION | خطای داخلی سرور |
مشاهده لینک، متن، فایل
از این سرویس برای فراخوانی یک مشاهده برای لینک/متن/فایل استفاده میشود. این سرویس، مقدارhash را دریافت می‌کند و برای لینک/متن متناظر با این لینک کوتاه، یک مشاهده ثبت می‌کند.
- شناسه سرویس: 46411
- پارامترهای ورودی:
| پارامتر | توضیحات |
|---|---|
| hash | کدی که نماینده یک لینک/متن می‌باشد |
- پاسخ برگشتی:
اگر لینک کوتاه مربوط به یک متن باشد، متن مربوط به ان نمایش داده میشود. در صورتی که لینک کوتاه مربوط به یک لینک باشد، کاربر مستقیما به لینک مربوطه redirect خواهد شد.
- خطاهایی که ممکن است در کار با این متد پیش آید:
| کد | پارامتر | شرح |
|---|---|---|
| 116 | INVALID_PARAMETER | مقدار غیرمجاز برای پارامتر |
| 404 | NOT_FOUND | خطا در یافتن hash |
| 999 | INTERNAL_SERVER_EXCEPTION | خطای داخلی سرور |
لیست لینک ها، متن ها، فایل ها
این سرویس لیستی از تمام لینک‌ها/متن‌ها/فایل‌های کاربر را برمیگرداند. این سرویس قابلیت pagination نیز دارد، به این صورت که offset و count را نیز از ورودی دریافت می‌کند.
- شناسه سرویس: 46412
- پارامترهای ورودی:
نکته: هیچکدام از پارامترها اجباری نیستند.
| پارامتر | شرح |
|---|---|
| offset | مشخص کننده شماره offset لیست می باشد. پیش فرض 0 است. |
| count | مشخص کننده تعداد عناصر لیست درخواستی با شروع از offset می باشد. پیش فرض 10 است. |
| order_by | نام فیلدی که مرتب سازی بر اساس آن انجام می‌گیرد. می‌تواند مقادیر “hash”، “createTime”، “expireTime” و یا “visitCount” را داشته باشد. پیش فرض مقدار “createTime” دارد. |
| order_asc | اگر true باشد مرتب سازی صعودی و درغیراینصورت نزولی خواهد بود. پیش فرض نزولی است. |
| search_sub_string | زیررشته مورد جستجو. پیش فرض جستجو انجام نمی گیرد و تمام نتایج بر می‌گردد. |
| date_from | تاریخ ابتدا جهت گزارش‌گیری |
| date_to | تاریخ انتها جهت گزارش‌گیری |
| hashGeneratedMethod | مقدار auto به این معنی که کد لینک کوتاه (hash) به صورت سیستمی و تصادفی انتخاب شده است و مقدار custom که یعنی از لینک اختصاصی استفاده شده است. |
| shortenObjectKind | نوع محتوای کوتاه شده: file, link یا content |
| filter_tags | فیلتر بر اساس تگ ها (تگ ها با ، جدا میشوند) |
| search_tags | سرچ در تگ ها (تگ ها با ، جدا میشوند) |
- پاسخ برگشتی: در صورت موفقیت آمیز بودن پاسخ برگشتی به این شکل خواهد بود:
{
"error": false,
"code": 200,
"result": {
"totalCount": 245,
"linkVos": [
{
"urlOrContent": "this is sample content",
"hash": "sample20",
"hashURL": "http://example.com/news/2",
"expireTime": 1618991112111,
"createTime": 1555919112111,
"visitCount": 1,
"isDeleted": false,
"hashGeneratedMethod": "custom",
"shortenObjectKind": "file",
"tags": "tag1,tag2"
},
{
"urlOrContent": "http://www.salavizadeh.com",
"hash": "sadegh",
"hashURL": " http://example.com/news/2",
"expireTime": 1618387401566,
"createTime": 1555315401566,
"visitCount": 3,
"isDeleted": false,
"hashGeneratedMethod": "custom",
"shortenObjectKind": "link",
"tags": "tag3"
},
{
"urlOrContent": "متن تستی",
"hash": "تست",
"hashURL": " http://example.com/news/2",
"expireTime": 1618300087215,
"createTime": 1555228087215,
"visitCount": 5,
"isDeleted": false,
"hashGeneratedMethod": "custom",
"shortenObjectKind": "content",
"tags": "text,sample"
}
]
}
}
- خطاهایی که ممکن است در کار با این سرویس پیش آید:
| کد | پارامتر | شرح |
|---|---|---|
| 401 | UNAUTHORIZED | عدم احراز هویت |
| 116 | INVALID_PARAMETER | مقدار غیرمجاز برای پارامتر |
| 999 | INTERNAL_SERVER_EXCEPTION | خطای داخلی سرور |
فعال یا غیرفعال سازی لینک
از این سرویس برای فعال/غیرفعال کردن لینک استفاده میشود.
- شناسه سرویس: 46413
- پارامترهای ورودی:
| پارامتر | اجباری/اختیاری | توضیحات |
|---|---|---|
| hash | اجباری | یک کد یکتا که می تواند توسط خود فرد و یا سیستم اتخاذ گردد. اگر ارسال نشود، سیستم به صورت خودکار یک hash به لینک مربوطه اختصاص میدهد |
| setStatus | اجباری | فعال (مقدار active) یا غیرفعال (deactive) کردن لینک |
- پاسخ برگشتی:
{
"error":false,
"code":200,
"result":true
}
- خطاهایی که ممکن است در کار با این متد پیش آید:
| کد | پارامتر | شرح |
|---|---|---|
| 401 | ANAUTHORIZED | عدم احراز هویت |
| 116 | INVALID_PARAMETER | مقدار غیرمجاز برای پارامتر |
| 119 | HASH_IS_NULL_OR_EMPTY | عدم مقدادهی hash |
| 404 | NOT_FOUND | خطا در یافتن hash |
| 999 | INTERNAL_SERVER_EXCEPTION | خطای داخلی سرور |
دریافت آمار کلیک ها
این سرویس آمار کلیک‌های انجام شده برای یک لینک کوتاه را میدهد.
- شناسه سرویس: 46414
- پارامترهای ورودی:
| پارامتر | اجباری/اختیاری | توضیحات |
|---|---|---|
| hash | اجباری | یک کد یکتا که می تواند توسط خود فرد و یا سیستم اتخاذ گردد. اگر ارسال نشود، سیستم به صورت خودکار یک hash به لینک مربوطه اختصاص میدهد |
| kind | اختیاری | یک رشته که نشان دهنده نوع آمار درخواستی می باشد. minute برای آمار دقیقه ای، hour برای آمار ساعتی، day برای آمار روزانه و month برای آمار ماهانه می‌باشد. بصورت پیش فرض مقدار month در نظر گرفته میشود |
| fromTimestamp | اختیاری | زمان ابتدا جهت گزارش‌گیری |
| toTimestamp | اختیاری | زمان انتها جهت گزارش‌گیری |
توجه داشته باشید که بازه گزارش گیری مجاز برای minute دو ساعت، برای hour یک هفته، برای day یک ماه و برای month برابر 20 سال می باشد.
- پاسخ برگشتی: در صورت موفقیت آمیز بودن پاسخ به صورت زیر است:
{
"error": false,
"code": 200,
"result": {
"totalCount": 7,
"createTime": 1552911699532,
"urlOrContent": "https://g.varzesh3.ir/",
"isURL": true,
"countries": [
{
"name": "Unknown",
"count": 7,
"cities": [
{
"name": "Unknown",
"count": 7
}
]
}
],
"referers": [
{
"name": "Unknown",
"count": 6
},
{
"name": "192.168.6.2",
"count": 1
}
],
"browsers": [
{
"name": "Unknown",
"count": 3
},
{
"name": "Chrome",
"count": 4
}
],
"clickIntervals": {
"intervals": [
1551398400000,
1554076800000
],
"clicksCount": [
1,
6
]
},
"hashURL": "http://172.16.110.235:8003/srv/tinylink/playpod2",
"oses": [
{
"name": "Unknown",
"count": 3
},
{
"name": "Windows 10",
"count": 4
}
]
}
}
- خطاهایی که ممکن است در کار با این متد پیش آید:
| کد | پارامتر | شرح |
|---|---|---|
| 401 | ANAUTHORIZED | عدم احراز هویت |
| 116 | INVALID_PARAMETER | مقدار غیرمجاز برای پارامتر |
| 404 | NOT_FOUND | هش یافت نشد |
| 999 | INTERNAL_SERVER_EXCEPTION | خطای داخلی سرور |
