رستاک CRM

ورود شروع رایگان

توسعه‌دهندگان

Q: Idempotency-Key پشتیبانی میشود؟

بله. در POST، PUT و PATCH میتوانید هدر Idempotency-Key (حداکثر ۱۲۸ کاراکتر) بفرستید. پاسخ اول ذخیره میشود و تا ۲۴ ساعت replay میشود (هدر X-Idempotency-Replayed).

Q: Webhook بعد از ثبت رکورد دارید؟

بله. از تب Webhook در پنل توسعهدهندگان URL و رویدادها را تنظیم کنید. پس از created/updated/deleted، POST با امضای HMAC در هدر X-Rastak-Signature ارسال میشود.

Q: حداکثر چند کلید میتوان ساخت؟

تا ۸ کلید فعال برای هر فضای کاری. فقط مالک یا مدیر میتواند کلید بسازد یا باطل کند.

اتصال سایت، اپ، حسابداری یا دستیار هوش مصنوعی به فضای کاری رستاک با REST. این صفحه عمومی است؛ برای ساخت کلید وارد پنل شوید.

ثبت‌نام و دریافت کلید ورود شروع سریع

https://rastakcrm.ir/api/v1

معرفی

وب‌سرویس REST رستاک CRM

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

پروتکل: REST روی HTTPS
فرمت: JSON
احراز هویت: Bearer Token با پیشوند rstk_
عملیات استاندارد: لیست، ایجاد، دریافت، ویرایش و حذف (CRUD)

شروع سریع

سه قدم تا اولین درخواست

۱کلید بسازید

در پنل، بخش توسعه‌دهندگان → تب کلیدها. نام بگذارید (مثلاً «سایت فروش»).

۲هدر بفرستید

Authorization: Bearer rstk_…

۳منبع را صدا بزنید

/api/v1/contacts و بقیه منابع؛ پاسخ ok یا خطا با پیام فارسی.

لیست منابع فعال فضای کاری:

curl -X GET \
  "https://rastakcrm.ir/api/v1" \
  -H "Authorization: Bearer rstk_YOUR_TOKEN" \
  -H "Accept: application/json"

کلید API

نحوه دریافت کلید

ثبت‌نام رایگان یا ورود به حساب رستاک.
ارتقا به پلن PRO + (وب‌سرویس در BASIC و PRO بسته است).
رفتن به بخش توسعه‌دهندگان در پنل و ساخت کلید با نامی مثل «اتصال سایت فروش».
کپی متن کامل کلید (فقط یک‌بار نمایش داده می‌شود) و قرار دادن در سرور یا env.
فرستادن هدر Authorization: Bearer rstk_… در هر درخواست.

پلن PRO + برای فراخوانی زنده لازم است. مستندات این صفحه برای همه عمومی است. شروع رایگان

احراز هویت

هدرها و شکل پاسخ

پایهٔ همهٔ درخواست‌ها: https://rastakcrm.ir/api/v1

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

موفق: {"ok": true, "data": ...} — خطا: {"ok": false, "error": "..."} با ۴۰۱، ۴۰۳، ۴۰۴ یا ۴۲۲.

جستجو در لیست: پارامتر q — صفحه‌بندی: page و per_page (حداکثر ۱۰۰).

نمونه PHP (ثبت مخاطب)

$ch = curl_init('https://rastakcrm.ir/api/v1/contacts');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer rstk_YOUR_TOKEN',
        'Accept: application/json',
        'Content-Type: application/json',
    ],
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode([
        'first_name' => 'سارا',
        'mobile' => '09120000000',
        'status' => 'active',
    ], JSON_UNESCAPED_UNICODE),
]);
$response = curl_exec($ch);
curl_close($ch);
print_r(json_decode($response, true));

منابع

لیست وب‌سرویس‌ها

هر منبع زیر مسیر /api/v1/{resource} در دسترس است. برای سناریوهای کاربردی و FAQ هر بخش، لینک صفحه تفصیلی در سایدبار است.

منبع	مسیر
مخاطبین	`/api/v1/contacts`	مستندات
شرکت‌ها	`/api/v1/companies`	مستندات
لیدها	`/api/v1/leads`	مستندات
معاملات	`/api/v1/deals`	مستندات
وظایف	`/api/v1/tasks`	مستندات
فاکتورها	`/api/v1/invoices`	مستندات
یادداشت‌ها	`/api/v1/notes`	مستندات
پیام‌ها	`/api/v1/messages`	مستندات
دوره‌ها	`/api/v1/courses`	مستندات

مخاطبین /api/v1/contacts

افراد و ارتباط‌دهندگان فضای کاری. عملیات کامل ایجاد، خواندن، به‌روزرسانی و حذف.

کار	متد	مسیر
لیست	GET	`https://rastakcrm.ir/api/v1/contacts`
ایجاد	POST	`https://rastakcrm.ir/api/v1/contacts`
یک رکورد	GET	`https://rastakcrm.ir/api/v1/contacts/{id}`
ویرایش	PUT	`https://rastakcrm.ir/api/v1/contacts/{id}`
حذف	DELETE	`https://rastakcrm.ir/api/v1/contacts/{id}`

بدنهٔ نمونهٔ ایجاد

{
    "first_name": "سارا",
    "last_name": "محمدی",
    "mobile": "09120000000",
    "email": "sara@example.com",
    "status": "active",
    "source": "website"
}

curl ایجاد

curl -X POST \
  "https://rastakcrm.ir/api/v1/contacts" \
  -H "Authorization: Bearer rstk_YOUR_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "سارا",
    "last_name": "محمدی",
    "mobile": "09120000000",
    "email": "sara@example.com",
    "status": "active",
    "source": "website"
}'

نمونه‌های لیست، دریافت، ویرایش و حذف

curl -X GET \
  "https://rastakcrm.ir/api/v1/contacts" \
  -H "Authorization: Bearer rstk_YOUR_TOKEN" \
  -H "Accept: application/json"

curl -X GET \
  "https://rastakcrm.ir/api/v1/contacts/12" \
  -H "Authorization: Bearer rstk_YOUR_TOKEN" \
  -H "Accept: application/json"

curl -X PUT \
  "https://rastakcrm.ir/api/v1/contacts/12" \
  -H "Authorization: Bearer rstk_YOUR_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "سارا",
    "last_name": "محمدی",
    "mobile": "09120000000",
    "email": "sara@example.com",
    "status": "active",
    "source": "website"
}'

curl -X DELETE \
  "https://rastakcrm.ir/api/v1/contacts/12" \
  -H "Authorization: Bearer rstk_YOUR_TOKEN" \
  -H "Accept: application/json"

شرکت‌ها /api/v1/companies

سازمان‌ها و مشتریان حقوقی.

کار	متد	مسیر
لیست	GET	`https://rastakcrm.ir/api/v1/companies`
ایجاد	POST	`https://rastakcrm.ir/api/v1/companies`
یک رکورد	GET	`https://rastakcrm.ir/api/v1/companies/{id}`
ویرایش	PUT	`https://rastakcrm.ir/api/v1/companies/{id}`
حذف	DELETE	`https://rastakcrm.ir/api/v1/companies/{id}`

بدنهٔ نمونهٔ ایجاد

{
    "name": "شرکت نمونه پارس",
    "city": "تهران",
    "phone": "02188000000",
    "status": "active"
}

curl ایجاد

curl -X POST \
  "https://rastakcrm.ir/api/v1/companies" \
  -H "Authorization: Bearer rstk_YOUR_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "شرکت نمونه پارس",
    "city": "تهران",
    "phone": "02188000000",
    "status": "active"
}'

نمونه‌های لیست، دریافت، ویرایش و حذف

curl -X GET \
  "https://rastakcrm.ir/api/v1/companies" \
  -H "Authorization: Bearer rstk_YOUR_TOKEN" \
  -H "Accept: application/json"

curl -X GET \
  "https://rastakcrm.ir/api/v1/companies/12" \
  -H "Authorization: Bearer rstk_YOUR_TOKEN" \
  -H "Accept: application/json"

curl -X PUT \
  "https://rastakcrm.ir/api/v1/companies/12" \
  -H "Authorization: Bearer rstk_YOUR_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "شرکت نمونه پارس",
    "city": "تهران",
    "phone": "02188000000",
    "status": "active"
}'

curl -X DELETE \
  "https://rastakcrm.ir/api/v1/companies/12" \
  -H "Authorization: Bearer rstk_YOUR_TOKEN" \
  -H "Accept: application/json"

لیدها /api/v1/leads

فرصت‌های فروش قبل از تبدیل به مخاطب.

کار	متد	مسیر
لیست	GET	`https://rastakcrm.ir/api/v1/leads`
ایجاد	POST	`https://rastakcrm.ir/api/v1/leads`
یک رکورد	GET	`https://rastakcrm.ir/api/v1/leads/{id}`
ویرایش	PUT	`https://rastakcrm.ir/api/v1/leads/{id}`
حذف	DELETE	`https://rastakcrm.ir/api/v1/leads/{id}`

بدنهٔ نمونهٔ ایجاد

{
    "name": "علی رضایی",
    "phone": "09121112233",
    "company_name": "نیک‌پرداز",
    "status": "new",
    "source": "referral",
    "course_id": 1,
    "utm_source": "google",
    "utm_campaign": "spring-sale"
}

curl ایجاد

curl -X POST \
  "https://rastakcrm.ir/api/v1/leads" \
  -H "Authorization: Bearer rstk_YOUR_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "علی رضایی",
    "phone": "09121112233",
    "company_name": "نیک‌پرداز",
    "status": "new",
    "source": "referral",
    "course_id": 1,
    "utm_source": "google",
    "utm_campaign": "spring-sale"
}'

نمونه‌های لیست، دریافت، ویرایش و حذف

curl -X GET \
  "https://rastakcrm.ir/api/v1/leads" \
  -H "Authorization: Bearer rstk_YOUR_TOKEN" \
  -H "Accept: application/json"

curl -X GET \
  "https://rastakcrm.ir/api/v1/leads/12" \
  -H "Authorization: Bearer rstk_YOUR_TOKEN" \
  -H "Accept: application/json"

curl -X PUT \
  "https://rastakcrm.ir/api/v1/leads/12" \
  -H "Authorization: Bearer rstk_YOUR_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "علی رضایی",
    "phone": "09121112233",
    "company_name": "نیک‌پرداز",
    "status": "new",
    "source": "referral",
    "course_id": 1,
    "utm_source": "google",
    "utm_campaign": "spring-sale"
}'

curl -X DELETE \
  "https://rastakcrm.ir/api/v1/leads/12" \
  -H "Authorization: Bearer rstk_YOUR_TOKEN" \
  -H "Accept: application/json"

معاملات /api/v1/deals

معاملات و مراحل قیف فروش.

کار	متد	مسیر
لیست	GET	`https://rastakcrm.ir/api/v1/deals`
ایجاد	POST	`https://rastakcrm.ir/api/v1/deals`
یک رکورد	GET	`https://rastakcrm.ir/api/v1/deals/{id}`
ویرایش	PUT	`https://rastakcrm.ir/api/v1/deals/{id}`
حذف	DELETE	`https://rastakcrm.ir/api/v1/deals/{id}`

بدنهٔ نمونهٔ ایجاد

{
    "title": "قرارداد پشتیبانی سالانه",
    "amount": 25000000,
    "stage": "proposal"
}

curl ایجاد

curl -X POST \
  "https://rastakcrm.ir/api/v1/deals" \
  -H "Authorization: Bearer rstk_YOUR_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "قرارداد پشتیبانی سالانه",
    "amount": 25000000,
    "stage": "proposal"
}'

نمونه‌های لیست، دریافت، ویرایش و حذف

curl -X GET \
  "https://rastakcrm.ir/api/v1/deals" \
  -H "Authorization: Bearer rstk_YOUR_TOKEN" \
  -H "Accept: application/json"

curl -X GET \
  "https://rastakcrm.ir/api/v1/deals/12" \
  -H "Authorization: Bearer rstk_YOUR_TOKEN" \
  -H "Accept: application/json"

curl -X PUT \
  "https://rastakcrm.ir/api/v1/deals/12" \
  -H "Authorization: Bearer rstk_YOUR_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "قرارداد پشتیبانی سالانه",
    "amount": 25000000,
    "stage": "proposal"
}'

curl -X DELETE \
  "https://rastakcrm.ir/api/v1/deals/12" \
  -H "Authorization: Bearer rstk_YOUR_TOKEN" \
  -H "Accept: application/json"

وظایف /api/v1/tasks

کارها و پیگیری‌های روزانه.

کار	متد	مسیر
لیست	GET	`https://rastakcrm.ir/api/v1/tasks`
ایجاد	POST	`https://rastakcrm.ir/api/v1/tasks`
یک رکورد	GET	`https://rastakcrm.ir/api/v1/tasks/{id}`
ویرایش	PUT	`https://rastakcrm.ir/api/v1/tasks/{id}`
حذف	DELETE	`https://rastakcrm.ir/api/v1/tasks/{id}`

بدنهٔ نمونهٔ ایجاد

{
    "title": "تماس پیگیری پیشنهاد",
    "priority": "high",
    "status": "pending"
}

curl ایجاد

curl -X POST \
  "https://rastakcrm.ir/api/v1/tasks" \
  -H "Authorization: Bearer rstk_YOUR_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "تماس پیگیری پیشنهاد",
    "priority": "high",
    "status": "pending"
}'

نمونه‌های لیست، دریافت، ویرایش و حذف

curl -X GET \
  "https://rastakcrm.ir/api/v1/tasks" \
  -H "Authorization: Bearer rstk_YOUR_TOKEN" \
  -H "Accept: application/json"

curl -X GET \
  "https://rastakcrm.ir/api/v1/tasks/12" \
  -H "Authorization: Bearer rstk_YOUR_TOKEN" \
  -H "Accept: application/json"

curl -X PUT \
  "https://rastakcrm.ir/api/v1/tasks/12" \
  -H "Authorization: Bearer rstk_YOUR_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "تماس پیگیری پیشنهاد",
    "priority": "high",
    "status": "pending"
}'

curl -X DELETE \
  "https://rastakcrm.ir/api/v1/tasks/12" \
  -H "Authorization: Bearer rstk_YOUR_TOKEN" \
  -H "Accept: application/json"

فاکتورها /api/v1/invoices

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

کار	متد	مسیر
لیست	GET	`https://rastakcrm.ir/api/v1/invoices`
ایجاد	POST	`https://rastakcrm.ir/api/v1/invoices`
یک رکورد	GET	`https://rastakcrm.ir/api/v1/invoices/{id}`
ویرایش	PUT	`https://rastakcrm.ir/api/v1/invoices/{id}`
حذف	DELETE	`https://rastakcrm.ir/api/v1/invoices/{id}`

بدنهٔ نمونهٔ ایجاد

{
    "type": "invoice",
    "title": "فاکتور خدمات مشاوره",
    "issue_date": "2026-08-16",
    "status": "draft",
    "items": [
        {
            "description": "مشاوره فروش",
            "quantity": 2,
            "unit_price": 1500000
        }
    ]
}

curl ایجاد

curl -X POST \
  "https://rastakcrm.ir/api/v1/invoices" \
  -H "Authorization: Bearer rstk_YOUR_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "invoice",
    "title": "فاکتور خدمات مشاوره",
    "issue_date": "2026-08-16",
    "status": "draft",
    "items": [
        {
            "description": "مشاوره فروش",
            "quantity": 2,
            "unit_price": 1500000
        }
    ]
}'

نمونه‌های لیست، دریافت، ویرایش و حذف

curl -X GET \
  "https://rastakcrm.ir/api/v1/invoices" \
  -H "Authorization: Bearer rstk_YOUR_TOKEN" \
  -H "Accept: application/json"

curl -X GET \
  "https://rastakcrm.ir/api/v1/invoices/12" \
  -H "Authorization: Bearer rstk_YOUR_TOKEN" \
  -H "Accept: application/json"

curl -X PUT \
  "https://rastakcrm.ir/api/v1/invoices/12" \
  -H "Authorization: Bearer rstk_YOUR_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "invoice",
    "title": "فاکتور خدمات مشاوره",
    "issue_date": "2026-08-16",
    "status": "draft",
    "items": [
        {
            "description": "مشاوره فروش",
            "quantity": 2,
            "unit_price": 1500000
        }
    ]
}'

curl -X DELETE \
  "https://rastakcrm.ir/api/v1/invoices/12" \
  -H "Authorization: Bearer rstk_YOUR_TOKEN" \
  -H "Accept: application/json"

یادداشت‌ها /api/v1/notes

یادداشت روی مخاطب، شرکت، لید یا معامله.

کار	متد	مسیر
لیست	GET	`https://rastakcrm.ir/api/v1/notes`
ایجاد	POST	`https://rastakcrm.ir/api/v1/notes`
یک رکورد	GET	`https://rastakcrm.ir/api/v1/notes/{id}`
ویرایش	PUT	`https://rastakcrm.ir/api/v1/notes/{id}`
حذف	DELETE	`https://rastakcrm.ir/api/v1/notes/{id}`

بدنهٔ نمونهٔ ایجاد

{
    "related_type": "contact",
    "related_id": 1,
    "body": "جلسه دمو برای چهارشنبه هماهنگ شد."
}

curl ایجاد

curl -X POST \
  "https://rastakcrm.ir/api/v1/notes" \
  -H "Authorization: Bearer rstk_YOUR_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "related_type": "contact",
    "related_id": 1,
    "body": "جلسه دمو برای چهارشنبه هماهنگ شد."
}'

نمونه‌های لیست، دریافت، ویرایش و حذف

curl -X GET \
  "https://rastakcrm.ir/api/v1/notes" \
  -H "Authorization: Bearer rstk_YOUR_TOKEN" \
  -H "Accept: application/json"

curl -X GET \
  "https://rastakcrm.ir/api/v1/notes/12" \
  -H "Authorization: Bearer rstk_YOUR_TOKEN" \
  -H "Accept: application/json"

curl -X PUT \
  "https://rastakcrm.ir/api/v1/notes/12" \
  -H "Authorization: Bearer rstk_YOUR_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "related_type": "contact",
    "related_id": 1,
    "body": "جلسه دمو برای چهارشنبه هماهنگ شد."
}'

curl -X DELETE \
  "https://rastakcrm.ir/api/v1/notes/12" \
  -H "Authorization: Bearer rstk_YOUR_TOKEN" \
  -H "Accept: application/json"

پیام‌ها /api/v1/messages

ثبت پیام واتساپ/تلگرام در اینباکس (ارسال واقعی از کانال جداست).

کار	متد	مسیر
لیست	GET	`https://rastakcrm.ir/api/v1/messages`
ایجاد	POST	`https://rastakcrm.ir/api/v1/messages`
یک رکورد	GET	`https://rastakcrm.ir/api/v1/messages/{id}`
ویرایش	PUT	`https://rastakcrm.ir/api/v1/messages/{id}`
حذف	DELETE	`https://rastakcrm.ir/api/v1/messages/{id}`

بدنهٔ نمونهٔ ایجاد

{
    "channel": "whatsapp",
    "direction": "out",
    "destination": "09120000000",
    "body": "سلام، پیگیری مذاکره را انجام می‌دهم."
}

curl ایجاد

curl -X POST \
  "https://rastakcrm.ir/api/v1/messages" \
  -H "Authorization: Bearer rstk_YOUR_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp",
    "direction": "out",
    "destination": "09120000000",
    "body": "سلام، پیگیری مذاکره را انجام می‌دهم."
}'

نمونه‌های لیست، دریافت، ویرایش و حذف

curl -X GET \
  "https://rastakcrm.ir/api/v1/messages" \
  -H "Authorization: Bearer rstk_YOUR_TOKEN" \
  -H "Accept: application/json"

curl -X GET \
  "https://rastakcrm.ir/api/v1/messages/12" \
  -H "Authorization: Bearer rstk_YOUR_TOKEN" \
  -H "Accept: application/json"

curl -X PUT \
  "https://rastakcrm.ir/api/v1/messages/12" \
  -H "Authorization: Bearer rstk_YOUR_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp",
    "direction": "out",
    "destination": "09120000000",
    "body": "سلام، پیگیری مذاکره را انجام می‌دهم."
}'

curl -X DELETE \
  "https://rastakcrm.ir/api/v1/messages/12" \
  -H "Authorization: Bearer rstk_YOUR_TOKEN" \
  -H "Accept: application/json"

دوره‌ها /api/v1/courses

کاتالوگ دوره برای فضای آموزشی.

کار	متد	مسیر
لیست	GET	`https://rastakcrm.ir/api/v1/courses`
ایجاد	POST	`https://rastakcrm.ir/api/v1/courses`
یک رکورد	GET	`https://rastakcrm.ir/api/v1/courses/{id}`
ویرایش	PUT	`https://rastakcrm.ir/api/v1/courses/{id}`
حذف	DELETE	`https://rastakcrm.ir/api/v1/courses/{id}`

بدنهٔ نمونهٔ ایجاد

{
    "title": "فروش مشاوره‌ای",
    "price": 4900000,
    "status": "open",
    "capacity": 20
}

curl ایجاد

curl -X POST \
  "https://rastakcrm.ir/api/v1/courses" \
  -H "Authorization: Bearer rstk_YOUR_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "فروش مشاوره‌ای",
    "price": 4900000,
    "status": "open",
    "capacity": 20
}'

نمونه‌های لیست، دریافت، ویرایش و حذف

curl -X GET \
  "https://rastakcrm.ir/api/v1/courses" \
  -H "Authorization: Bearer rstk_YOUR_TOKEN" \
  -H "Accept: application/json"

curl -X GET \
  "https://rastakcrm.ir/api/v1/courses/12" \
  -H "Authorization: Bearer rstk_YOUR_TOKEN" \
  -H "Accept: application/json"

curl -X PUT \
  "https://rastakcrm.ir/api/v1/courses/12" \
  -H "Authorization: Bearer rstk_YOUR_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "فروش مشاوره‌ای",
    "price": 4900000,
    "status": "open",
    "capacity": 20
}'

curl -X DELETE \
  "https://rastakcrm.ir/api/v1/courses/12" \
  -H "Authorization: Bearer rstk_YOUR_TOKEN" \
  -H "Accept: application/json"

پلتفرم

سیاست‌ها و محدودیت‌های فنی

Sandbox، Idempotency، Webhook، UTM و فیلدهای سفارشی فعال هستند. جزئیات در بخش‌های زیر.

Rate limit: ۶۰ درخواست در دقیقه به ازای هر کلید
Timeout پیشنهادی کلاینت: ۳۰ ثانیه
حداکثر per_page: ۱۰۰
اسکیمای زنده: GET /api/v1/schema یا /api/v1/schema/leads

هدرهای پیشنهادی (شامل Idempotency اختیاری):

Authorization: Bearer rstk_YOUR_TOKEN
Accept: application/json
Content-Type: application/json
Idempotency-Key: unique-key-per-write-op

نمونه schema لید (UTM و course_id):

curl -X GET \
  "https://rastakcrm.ir/api/v1/schema/leads" \
  -H "Authorization: Bearer rstk_YOUR_TOKEN" \
  -H "Accept: application/json"

Sandbox اختصاصی

فعال

کلید sandbox با پیشوند rstk_sbx_؛ دادهٔ جدا از پروداکشن و مخفی از پنل وب.

هنگام ساخت کلید در پنل، محیط Sandbox را انتخاب کنید.
رکوردهای sandbox با api_environment=sandbox ذخیره می‌شوند و در لیست‌های پنل دیده نمی‌شوند.
کلید production فقط رکوردهای واقعی (غیر-sandbox) را می‌بیند.

Idempotency Key

فعال

هدر Idempotency-Key برای POST/PUT/PATCH؛ replay تا ۲۴ ساعت.

هدر اختیاری است؛ اگر نباشد رفتار قبلی حفظ می‌شود.
پاسخ موفق ذخیره و با X-Idempotency-Replayed: true برگردانده می‌شود.
اگر همان کلید در حال پردازش باشد، 409 Conflict.

Rate-limit رسمی

فعال

۶۰ درخواست در دقیقه به ازای هر کلید API (middleware throttle:60,1).

پاسخ 429 با Retry-After در هدر (رفتار پیش‌فرض Laravel) ممکن است برگردد.
لیست‌های بزرگ را با page و per_page (حداکثر ۱۰۰) صفحه‌بندی کنید.

Retry policy رسمی

فعال

هدر X-Api-Retry-Policy در هر پاسخ API.

روی 429: exponential backoff (۱، ۲، ۴ ثانیه) و Retry-After.
روی 5xx: حداکثر ۳ retry؛ با Idempotency-Key برای POST امن‌تر است.
روی 4xx (به‌جز 429): retry نکنید.

Timeout پیشنهادی

فعال

هدر X-Recommended-Client-Timeout: ۳۰ ثانیه (۶۰ برای فاکتور سنگین).

مقدار در هدر پاسخ API اعلام می‌شود.
در صورت قطع اتصال، وضعیت را با GET تأیید کنید.

Webhook callback نتیجه ثبت

فعال

تنظیم از پنل توسعه‌دهندگان؛ رویدادهای resource.created|updated|deleted.

امضا: X-Rastak-Signature: sha256=HMAC(body, secret).
هدرهای X-Rastak-Event و X-Rastak-Delivery برای ردیابی.
Webhookهای ورودی واتساپ/تلگرام جدا از خروجی API هستند.

Custom fields

فعال

مخاطب و شرکت در API؛ کلید custom_fields با slug.

تعریف فیلد: /custom-fields در پنل (پلن PRO).
GET /api/v1/schema/contacts یا companies تعاریف را برمی‌گرداند.
در پاسخ detail، custom_fields با slug پر می‌شود.

ارتباط Lead ↔ Course

فعال

فیلد course_id روی لید؛ ارجاع به دوره همان فضای کاری.

course_id اختیاری و nullable است.
ثبت‌نام واقعی دوره همچنان از enrollment در پنل انجام می‌شود.
برای کمپین آموزشی: لید + course_id + UTM.

فیلدهای UTM اختصاصی

فعال

utm_source، utm_medium، utm_campaign، utm_term، utm_content روی لید.

همه اختیاری؛ حداکثر ۱۲۰ کاراکتر.
source همچنان منبع از پیش‌تعریف‌شده (website، referral و…) است.
schema: GET /api/v1/schema/leads

Validation

اسکیمای فیلدها (مرجع)

قواعد اعتبارسنجی سمت سرور در ApiCrudService. برای enumها و فیلدهای UTM/course_id از GET /api/v1/schema/{resource} استفاده کنید. خطای 422 با errors جزئی برمی‌گردد.

مخاطبین /api/v1/contacts

فیلد	نوع	الزامی	قواعد
`first_name`	string	ایجاد	max:100
`last_name`	string	اختیاری	max:100
`email`	email	اختیاری	max:190، یکتا با mobile در فضای کاری
`phone`	string	اختیاری	max:30
`mobile`	string	اختیاری	max:30، نرمال‌سازی 09…، یکتا با email
`position`	string	اختیاری	max:120
`job_field`	string	اختیاری	max:120
`source`	enum	اختیاری	مقادیر Contact::sources()
`status`	enum	ایجاد	active\|inactive\|… (Contact::statuses())
`notes`	text	اختیاری	max:5000
`next_follow_up_at`	date	اختیاری	ISO یا شمسی در ورودی
`company_id`	integer	اختیاری	باید متعلق به همان فضای کاری باشد
`custom_fields`	object	اختیاری	slug => value؛ پلن PRO

شرکت‌ها /api/v1/companies

فیلد	نوع	الزامی	قواعد
`name`	string	ایجاد	max:190
`industry`	string	اختیاری	max:120
`phone`	string	اختیاری	max:30
`email`	email	اختیاری	max:190
`website`	string	اختیاری	max:190
`city`	string	اختیاری	max:100
`economic_code`	string	اختیاری	max:50
`business_national_id`	string	اختیاری	max:50
`address`	text	اختیاری	max:500
`notes`	text	اختیاری	max:5000
`status`	enum	ایجاد	Company::statuses()
`custom_fields`	object	اختیاری	slug => value؛ پلن PRO

لیدها /api/v1/leads

فیلد	نوع	الزامی	قواعد
`name`	string	ایجاد	max:190
`email`	email	اختیاری	max:190
`phone`	string	اختیاری	max:30
`company_name`	string	اختیاری	max:190
`source`	enum	اختیاری	Lead::sources() — فیلد عمومی منبع، نه UTM اختصاصی
`status`	enum	ایجاد	new\|contacted\|qualified\|converted\|lost
`estimated_value`	integer	اختیاری	min:0، تومان/ریال طبق پنل
`notes`	text	اختیاری	max:5000
`next_follow_up_at`	date	اختیاری	ISO یا شمسی
`course_id`	integer	اختیاری	دوره همان فضای کاری
`utm_source`	string	اختیاری	max:120
`utm_medium`	string	اختیاری	max:120
`utm_campaign`	string	اختیاری	max:120
`utm_term`	string	اختیاری	max:120
`utm_content`	string	اختیاری	max:120

معاملات /api/v1/deals

فیلد	نوع	الزامی	قواعد
`title`	string	ایجاد	max:190
`amount`	number	اختیاری	min:0
`stage`	enum	ایجاد	Deal::stages()
`expected_close_date`	date	اختیاری
`notes`	text	اختیاری	max:5000
`contact_id`	integer	اختیاری	همان فضای کاری
`company_id`	integer	اختیاری	همان فضای کاری

وظایف /api/v1/tasks

فیلد	نوع	الزامی	قواعد
`title`	string	ایجاد	max:190
`description`	text	اختیاری	max:5000
`due_at`	datetime	اختیاری
`priority`	enum	ایجاد	Task::priorities()
`status`	enum	ایجاد	Task::statuses()
`contact_id`	integer	اختیاری
`company_id`	integer	اختیاری
`deal_id`	integer	اختیاری

فاکتورها /api/v1/invoices

فیلد	نوع	الزامی	قواعد
`type`	enum	ایجاد	Invoice::types()
`title`	string	ایجاد	max:190
`issue_date`	date	ایجاد
`due_date`	date	اختیاری	بعد یا مساوی issue_date
`status`	enum	ایجاد	draft\|sent\|paid\|cancelled
`discount_amount`	integer	اختیاری	min:0
`tax_amount`	integer	اختیاری	min:0
`notes`	text	اختیاری	max:5000
`items`	array	ایجاد	حداقل یک ردیف: description, quantity, unit_price
`send_sms`	boolean	اختیاری	پیش‌فرض true در ایجاد
`deal_id`	integer	اختیاری
`contact_id`	integer	اختیاری
`company_id`	integer	اختیاری

یادداشت‌ها /api/v1/notes

فیلد	نوع	الزامی	قواعد
`related_type`	enum	ایجاد	contact\|company\|deal\|lead
`related_id`	integer	ایجاد	شناسه معتبر همان نوع
`body`	text	ایجاد	max:5000

پیام‌ها /api/v1/messages

فیلد	نوع	الزامی	قواعد
`channel`	enum	ایجاد	Message::channels()
`direction`	enum	ایجاد	Message::directions()
`contact_id`	integer	اختیاری
`lead_id`	integer	اختیاری
`destination`	string	اختیاری	max:120
`counterpart_name`	string	اختیاری	max:160
`body`	text	ایجاد	max:5000

دوره‌ها /api/v1/courses

ثبت‌نام دوره (enrollment) از API جدا نیست؛ از پنل دوره انجام می‌شود.

فیلد	نوع	الزامی	قواعد
`title`	string	ایجاد	max:190
`code`	string	اختیاری	max:50
`price`	integer	اختیاری	min:0
`capacity`	integer	اختیاری	1–100000
`status`	enum	ایجاد	Course::statuses()
`starts_on`	date	اختیاری
`ends_on`	date	اختیاری	بعد یا مساوی starts_on
`description`	text	اختیاری	max:5000
`notes`	text	اختیاری	max:2000

هوش مصنوعی

اتصال MCP (ChatGPT، Claude، Cursor)

برای اتصال دستیار هوش مصنوعی بدون کدنویسی REST، از مسیر https://rastakcrm.ir/mcp و اسکیل آماده در پنل استفاده کنید.

صفحه معرفی MCP

FAQ

سؤالات متداول

بله. خواندن مستندات و نمونه کدها عمومی است. برای فراخوانی زنده API باید وارد شوید، کلید بسازید و پلن PRO + داشته باشید.

همهٔ منابع زیر مسیر /api/v1 قرار دارند. مثال: GET /api/v1/contacts برای لیست مخاطبین.

موفق: {"ok": true, "data": ...}. خطا: {"ok": false, "error": "پیام فارسی"} با کدهای ۴۰۱، ۴۰۳، ۴۰۴ یا ۴۲۲.

بله. هنگام ساخت کلید، محیط Sandbox را انتخاب کنید. کلیدهای sandbox با پیشوند rstk_sbx_ شروع می‌شوند و فقط به رکوردهای تستی (api_environment=sandbox) دسترسی دارند؛ این داده‌ها در پنل وب نمایش داده نمی‌شوند.

بله. در POST، PUT و PATCH می‌توانید هدر Idempotency-Key (حداکثر ۱۲۸ کاراکتر) بفرستید. پاسخ اول ذخیره می‌شود و تا ۲۴ ساعت replay می‌شود (هدر X-Idempotency-Replayed).

۶۰ درخواست در دقیقه برای هر کلید API (پس از احراز هویت). در صورت عبور، پاسخ 429 Too Many Requests برمی‌گردد.

بله. از تب Webhook در پنل توسعه‌دهندگان URL و رویدادها را تنظیم کنید. پس از created/updated/deleted، POST با امضای HMAC در هدر X-Rastak-Signature ارسال می‌شود.

بله برای مخاطب و شرکت (پلن PRO). در بدنه custom_fields با slug فیلد مقدار بفرستید. GET /api/v1/schema/contacts تعاریف را برمی‌گرداند.

از بخش اتصال هوش مصنوعی در پنل، اسکیل MCP آماده را دانلود کنید. مسیر /mcp برای دستیارهاست.

تا ۸ کلید فعال برای هر فضای کاری. فقط مالک یا مدیر می‌تواند کلید بسازد یا باطل کند.

توسعه‌دهندگان

وب‌سرویس REST رستاک CRM

سه قدم تا اولین درخواست

نحوه دریافت کلید

هدرها و شکل پاسخ

نمونه PHP (ثبت مخاطب)

لیست وب‌سرویس‌ها

بدنهٔ نمونهٔ ایجاد

curl ایجاد

بدنهٔ نمونهٔ ایجاد

curl ایجاد

بدنهٔ نمونهٔ ایجاد

curl ایجاد

بدنهٔ نمونهٔ ایجاد

curl ایجاد

بدنهٔ نمونهٔ ایجاد

curl ایجاد

بدنهٔ نمونهٔ ایجاد

curl ایجاد

بدنهٔ نمونهٔ ایجاد

curl ایجاد

بدنهٔ نمونهٔ ایجاد

curl ایجاد

بدنهٔ نمونهٔ ایجاد

curl ایجاد

سیاست‌ها و محدودیت‌های فنی

Sandbox اختصاصی

Idempotency Key

Rate-limit رسمی

Retry policy رسمی

Timeout پیشنهادی

Webhook callback نتیجه ثبت

Custom fields

ارتباط Lead ↔ Course

فیلدهای UTM اختصاصی

اسکیمای فیلدها (مرجع)

اتصال MCP (ChatGPT، Claude، Cursor)

سؤالات متداول

آیا این مستندات بدون ورود قابل استفاده است؟

پایهٔ آدرس API چیست؟

شکل پاسخ موفق و خطا چگونه است؟

آیا sandbox اختصاصی دارید؟

Idempotency-Key پشتیبانی می‌شود؟

محدودیت نرخ (rate limit) چقدر است؟

Webhook بعد از ثبت رکورد دارید؟

فیلدهای سفارشی (custom fields) در API هست؟

اتصال ChatGPT یا Claude چطور است؟

حداکثر چند کلید می‌توان ساخت؟