مستندات API لینک پرو
همه درخواست‌ها به آدرس پایه https://link.pro.plus/api/v1 ارسال می‌شوند. بدنه درخواست و پاسخ JSON است و مبالغ به تومان هستند.
احراز هویت
از بخش «کلیدهای API» در پنل یک کلید بسازید و آن را در هدر Authorization یا X-Api-Key ارسال کنید. محدودیت نرخ: ۳۰۰ درخواست در دقیقه برای هر کلید.
Authorization: Bearer lp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx Accept: application/json
محتوای HTML و پیوست‌ها
فیلدهای content (پیام لینک‌دار) و body (تیکت) HTML می‌پذیرند؛ می‌توانید یک قطعه HTML یا کل سند (<html><body>…</body></html>) را بفرستید. ساختار و استایل‌های inline حفظ می‌شوند و موارد ناامن حذف می‌شوند.
- مجاز: تیترها، پاراگراف، لیست، جدول (با width، border، cellpadding، bgcolor)، تصویر، لینک، نقل‌قول، کد، section، article، header، footer، figure، div و span.
- استایل inline: رنگ، پس‌زمینه، فونت، اندازه، تراز، فاصله‌ها (margin/padding)، border، عرض/ارتفاع و line-height.
- جهت متن: ویژگی
dir="rtl|ltr|auto"روی بلوک‌ها پشتیبانی می‌شود وdirectionجهت پایه صفحه است. - ویدیو: iframe فقط برای embed آپارات و یوتیوب مجاز است.
- حذف می‌شود: script، style و head، رویدادها (onclick و …)، فرم‌ها و iframe سایر دامنه‌ها.
هر پیوست یکی از این سه شکل است. تصاویر در صفحه پیام به‌صورت گالری با نمایش تمام‌صفحه، فایل‌های صوتی و ویس با پخش‌کننده، و PDF و فایل‌ها با دکمه مشاهده و دانلود نمایش داده می‌شوند.
{ "media_id": 12 } // uploaded via /api/v1/media
{ "media_id": 13, "type": "voice" } // show an audio upload as a voice note
{ "type": "link", "url": "https://…", "title": "…" } // link card
{ "type": "image|audio|voice|video|pdf|file", "url": "https://…", "name": "…" } // external fileحساب
/api/v1/accountاطلاعات حساب و موجودی کیف پول
{
"company": { "name": "فروشگاه من", "slug": "myshop", "portal_url": "https://link.pro.plus/myshop" },
"wallet_balance": 125000,
"currency": "IRT",
"package": { "name": "حرفه‌ای", "expires_at": "2026-11-16T10:00:00Z" }
}مشتریان
مشتریان را می‌توانید با شناسه عددی یا با شناسه سیستم خودتان به شکل ext:{external_id} آدرس‌دهی کنید.
/api/v1/customers?phone=&external_id=&email=&per_page=50فهرست و جستجوی مشتریان
/api/v1/customersساخت یا به‌روزرسانی مشتری (upsert)
اگر external_id قبلا وجود داشته باشد، همان مشتری به‌روزرسانی می‌شود؛ پس برای همگام‌سازی کاربران سایت خود امن است.
{
"external_id": "user-1024",
"name": "مریم احمدی",
"phone": "09121234567",
"email": "maryam@example.com",
"meta": { "plan": "gold" }
}{ "customer": { "id": 17, "external_id": "user-1024", ... }, "created": true }/api/v1/customers/{id | ext:external_id}دریافت یک مشتری
/api/v1/customers/{id | ext:external_id}ویرایش مشتری
/api/v1/customers/{id | ext:external_id}حذف مشتری
/api/v1/customers/{id | ext:external_id}/portal-linkلینک ورود یک‌بارمصرف به پرتال
کاربر شما بدون کد پیامکی مستقیما وارد پرتال پشتیبانی می‌شود. ttl بر حسب دقیقه است (پیش‌فرض ۶۰).
{ "ttl": 30 }{ "url": "https://link.pro.plus/myshop?access=...", "expires_at": "..." }تیکت‌ها
/api/v1/tickets?status=&customer_id=&external_id=&updated_since=فهرست تیکت‌ها
/api/v1/ticketsثبت تیکت
مشتری را با customer_id یا با شیء customer مشخص کنید؛ اگر وجود نداشته باشد ساخته می‌شود. author می‌تواند customer (پیش‌فرض) یا agent باشد.
{
"customer": { "external_id": "user-1024", "name": "مریم", "phone": "09121234567" },
"subject": "پیگیری سفارش ۱۲۳۴",
"body": "<p>سفارش من هنوز ارسال نشده است.</p>",
"direction": "rtl",
"priority": "high",
"category": "orders",
"attachments": [{ "media_id": 12 }, { "media_id": 13, "type": "voice" }]
}/api/v1/tickets/{id}دریافت تیکت به همراه پیام‌ها
/api/v1/tickets/{id}/messagesافزودن پاسخ
body یا attachments (یا هر دو) لازم است؛ مثلا فقط یک ویس یا تصویر.
{
"body": "<p>سفارش شما امروز ارسال شد.</p>",
"author": "agent",
"status": "answered",
"attachments": [{ "media_id": 15 }, { "type": "link", "url": "https://track.post.ir/123", "title": "پیگیری مرسوله" }]
}/api/v1/tickets/{id}تغییر وضعیت/اولویت
{ "status": "closed" }آپلود فایل (رسانه)
ابتدا فایل را آپلود کنید و شناسه آن (media_id) را در attachments پیام لینک‌دار یا تیکت قرار دهید. حداکثر حجم هر فایل ۱۰۰ مگابایت است. نوع فایل خودکار تشخیص داده می‌شود: image، audio، video، pdf یا file؛ برای پیام صوتی ضبط‌شده type=voice بفرستید.
/api/v1/mediaآپلود فایل (multipart/form-data)
فرمت‌های مجاز: تصاویر (jpg، png، gif، webp، heic)، صوت (mp3، wav، ogg، opus، m4a، aac، webm، amr)، ویدیو (mp4، mov، mkv)، pdf، zip، rar، 7z، اسناد Office، txt و csv. فایل‌های SVG و HTML به دلایل امنیتی پذیرفته نمی‌شوند.
curl -X POST https://link.pro.plus/api/v1/media \ -H "Authorization: Bearer lp_xxx" \ -F "file=@invoice.pdf" # پیام صوتی: curl -X POST https://link.pro.plus/api/v1/media \ -H "Authorization: Bearer lp_xxx" \ -F "file=@voice.ogg" -F "type=voice"
{
"media": {
"id": 12, "media_id": 12, "type": "pdf",
"url": "https://link.pro.plus/storage/media/3/2026/10/x7Yk….pdf",
"name": "invoice.pdf", "mime": "application/pdf", "size": 482113
}
}/api/v1/media?type=image&per_page=50فهرست فایل‌های آپلودشده
/api/v1/media/{id}حذف فایل
پیام‌های لینک‌دار
یک صفحه با محتوای HTML و پیوست‌ها (گالری تصاویر، PDF، فایل صوتی، ویس، ویدیو، لینک) بسازید و لینک کوتاه آن را پیامک کنید. هزینه از کیف پول کسر و در صورت شکست ارسال بازگردانده می‌شود. حریم خصوصی: اگر پیام برای حداقل یک شماره ارسال شده باشد، بازکننده لینک باید شماره موبایل یکی از گیرندگان را وارد کند تا محتوا نمایش داده شود (بدون کد تایید). پیامی که گیرنده ندارد برای همه قابل مشاهده است.
/api/v1/link-messages/quote?recipients=3محاسبه هزینه پیش از ارسال
/api/v1/link-messagesساخت صفحه و ارسال پیامک
برای یک گیرنده phone و برای چند گیرنده phones را بفرستید. بدون شماره، فقط صفحه و لینک ساخته می‌شود. sender_name (اختیاری، حداکثر ۶۰ کاراکتر) نامی است که بالای صفحه پیام نمایش داده می‌شود؛ اگر ارسال نشود نام کسب‌وکار استفاده می‌شود. متن پیامک ثابت است: «کاربر گرامی، پیرو گفتگو با شما موارد لازم در لینک زیر قرارداده شده است: link.pro.plus/token». پیامک بلافاصله در همان درخواست ارسال و وضعیت واقعی هر گیرنده برگردانده می‌شود.
{
"title": "Invoice #1234",
"sender_name": "فروشگاه آنلاین مهر",
"content": "<section dir=\"ltr\" style=\"padding:16px\"><h2>Payment received</h2><p>Thank you!</p></section>",
"direction": "ltr",
"phones": ["09121234567", "09351234567"],
"expires_at": "2026-12-01T00:00:00Z",
"attachments": [
{ "media_id": 12 },
{ "media_id": 14 },
{ "media_id": 15, "type": "voice" },
{ "type": "link", "url": "https://shop.example.com/orders/1234", "title": "مشاهده سفارش" },
{ "type": "image", "url": "https://cdn.example.com/banner.jpg" }
]
}{
"link_message": {
"id": 41, "token": "7kq3m9xa", "url": "https://link.pro.plus/7kq3m9xa",
"recipients": [
{ "phone": "09121234567", "token": "4hd8s2wq", "url": "https://link.pro.plus/4hd8s2wq", "status": "sent" }
]
}
}/api/v1/link-messages/{id}وضعیت ارسال و بازدید هر گیرنده
/api/v1/link-messages/{id}ویرایش محتوا، پیوست‌ها یا نام فرستنده
{ "content": "<p>متن جدید</p>", "attachments": [{ "media_id": 12 }] }/api/v1/link-messages/{id}/sendارسال مجدد به شماره‌های دیگر
{ "phones": ["09121234567"] }وب‌هوک
رویدادهای ticket.created، ticket.replied و ticket.status_changed به آدرس ثبت‌شده POST می‌شوند. صحت درخواست را با HMAC-SHA256 بدنه و کلید امضا بررسی کنید. در صورت خطا تا ۴ بار تلاش مجدد انجام می‌شود.
X-LinkPro-Event: ticket.replied
X-LinkPro-Signature: sha256=<hmac_sha256(body, webhook_secret)>
{
"event": "ticket.replied",
"sent_at": "2026-10-16T09:30:00+00:00",
"data": {
"ticket": { "id": 12, "number": 58, "subject": "...", "status": "open", "customer_external_id": "user-1024" },
"message": { "id": 99, "author_type": "customer", "body": "<p>...</p>" }
}
}// PHP
$valid = hash_equals('sha256=' . hash_hmac('sha256', $rawBody, $secret), $_SERVER['HTTP_X_LINKPRO_SIGNATURE']);
// Node.js
const valid = crypto.timingSafeEqual(
Buffer.from('sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex')),
Buffer.from(req.headers['x-linkpro-signature'])
);خطاها
| 401 | کلید API ارسال نشده یا نامعتبر است. |
| 402 | موجودی کیف پول کافی نیست (code: insufficient_balance). |
| 403 | محدودیت پکیج یا غیرفعال بودن حساب (code: plan_limit). |
| 404 | منبع پیدا نشد. |
| 422 | خطای اعتبارسنجی؛ جزئیات در فیلد errors. |
| 429 | تعداد درخواست‌ها بیش از حد مجاز است. |
{ "message": "موجودی کیف پول کافی نیست.", "code": "insufficient_balance", "required": 900, "balance": 300 }