راهنمای تخصصی API - سی‌آر‌ام سیمین

مقدمه

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

آدرس پایه (Base URL):
https://app.simincrm.ir/api/api.php

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

احراز هویت

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

در هر درخواست، پارامتر apikey باید همراه با سایر داده‌ها ارسال شود.

متدها و فراخوانی‌ها

ثبت سفارش و مشتری جدید

POST

این متد برای ثبت یک فروش جدید به کار می‌رود. اگر شماره موبایل ارسالی در سیستم موجود نباشد، یک رکورد مشتری جدید نیز به صورت خودکار ایجاد می‌شود.

پارامترهای ارسالی (Action: `orders_neworder`)

پارامتر	نوع	توضیحات
`action`	رشته	باید برابر با `orders_neworder` باشد.
`apikey`	رشته	کلید اختصاصی API شما.
`mobile`	عدد	شماره موبایل مشتری (اجباری).
`name`	رشته	نام و نام خانوادگی مشتری.
`amount`	عدد	مبلغ کل سفارش.
`productid`	عدد	شناسه محصول تعریف شده در سیستم.
`qty`	عدد	تعداد محصول.
`detail`	رشته	توضیحات تکمیلی سفارش.

ثبت یا ویرایش شخص

POST

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

پارامترهای ارسالی (Action: `person_save`)

پارامتر	نوع	توضیحات
`action`	رشته	باید برابر با `person_save` باشد.
`id`	عدد	در صورت ارسال، رکورد با این شناسه ویرایش می‌شود. در غیر این صورت رکورد جدید ساخته می‌شود.
`name`	رشته	نام و نام خانوادگی.
`mobile`	عدد	شماره تلفن همراه اصلی.
`email`	رشته	آدرس ایمیل.
`address`	رشته	آدرس پستی مشتری.
`info`	رشته	توضیحات و یادداشت‌ها.

دریافت لیست اشخاص

POST

دریافت لیست مشتریان ثبت شده در سیستم همراه با قابلیت فیلتر و جستجو.

پارامترهای ارسالی (Action: `person_list`)

پارامتر	نوع	توضیحات
`action`	رشته	باید برابر با `person_list` باشد.
`startRow`	عدد	شروع از رکورد شماره (برای صفحه‌بندی). پیش‌فرض 0.
`sortby`	رشته	نام فیلد جهت مرتب‌سازی (مانند `id` یا `name`).
`sort`	رشته	جهت مرتب‌سازی (`asc` یا `desc`).

لیست فعالیت‌ها

POST

دریافت لیست فعالیت‌ها، وظایف، تیکت‌ها و پیگیری‌ها با قابلیت فیلتر بر اساس وضعیت، نوع و کارشناس.

پارامترهای ارسالی (Action: `task_list`)

پارامتر	نوع	توضیحات
`action`	رشته	باید برابر با `task_list` باشد.
`taskstatus`	عدد	فیلتر لیست: 1 (منتظر انجام)، 2 (در حال پیگیری)، 3 (سررسید نشده)، 4 (راکد)، 5 (انجام شده)، 6 (امروز)، 7 (فردا).
`tasktype`	عدد	فیلتر نوع فعالیت (مثلاً 1 برای تیکت).
`userid`	عدد	شناسه کارشناس جهت مشاهده فعالیت‌های محول شده (در صورت داشتن دسترسی).
`filter`	JSON	فیلترهای پیشرفته در قالب JSON (مانند جستجو در عنوان یا توضیحات).
`startRow`	عدد	شروع از رکورد شماره (برای صفحه‌بندی).
`sortby`	رشته	نام فیلد جهت مرتب‌سازی.
`sort`	رشته	جهت مرتب‌سازی (`asc` یا `desc`).

ثبت یا ویرایش فعالیت

POST

ثبت وظیفه، تماس، قرار ملاقات یا تیکت جدید و یا ویرایش موارد موجود.

پارامترهای ارسالی (Action: `task_save`)

پارامتر	نوع	توضیحات
`action`	رشته	باید برابر با `task_save` باشد.
`id`	عدد	شناسه فعالیت (فقط برای ویرایش).
`personid`	عدد	شناسه مشتری مرتبط.
`mobile`	رشته	شماره موبایل مشتری (در صورت عدم ارسال `personid`).
`tasktype`	عدد	نوع فعالیت (1 برای تیکت، سایر مقادیر برای وظایف و تماس‌ها).
`productid`	عدد	شناسه محصول مرتبط.
`title`	رشته	عنوان فعالیت.
`info`	رشته	جزئیات و شرح فعالیت.
`userid`	عدد	شناسه کارشناس مسئول.
`assigntime`	Timestamp	زمان تخصیص فعالیت (یونیکس تایم - فقط برای ثبت جدید).
`scheduledtime`	Timestamp	زمان سررسید یا یادآوری (یونیکس تایم).
`taskstatus`	عدد	0: انجام نشده، 1: در حال پیگیری، 2: راکد، 3: انجام شده.
`priority`	عدد	اولویت: 0 (کم)، 1 (متوسط)، 2 (فوری).
`departmentid`	عدد	شناسه دپارتمان مرتبط.
`comment`	رشته	متن پاسخ (مخصوص تیکت‌ها - tasktype=1).
`file`	رشته	نام فایل آپلود شده (در صورت ارسال پاسخ در تیکت).

بارگذاری اطلاعات فعالیت

POST

دریافت جزئیات کامل یک فعالیت، شامل تاریخچه گفتگوها (در تیکت‌ها) و تنظیمات فرم.

پارامترهای ارسالی (Action: `task_load`)

پارامتر	نوع	توضیحات
`action`	رشته	باید برابر با `task_load` باشد.
`id`	عدد	شناسه فعالیت مورد نظر.

حذف فعالیت

POST

حذف یک فعالیت یا تیکت از سیستم.

پارامترهای ارسالی (Action: `task_delete`)

پارامتر	نوع	توضیحات
`action`	رشته	باید برابر با `task_delete` باشد.
`id`	عدد	شناسه فعالیت جهت حذف.

جستجوی کالر آیدی (Caller ID)

POST

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

پارامترهای ارسالی (Action: `person_callerid`)

پارامتر	نوع	توضیحات
`action`	رشته	باید برابر با `person_callerid` باشد.
`number`	رشته	شماره تلفن تماس‌گیرنده (بدون صفر اول یا با فرمت استاندارد).

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

POST

جستجوی هوشمند در نام و شماره موبایل مخاطبان. این متد برای پیاده‌سازی قابلیت Autocomplete در فیلدهای جستجو یا دستیارهای صوتی پیشنهاد می‌شود.

پارامترهای ارسالی (Action: `person_quicksearch`)

پارامتر	نوع	توضیحات
`action`	رشته	باید برابر با `person_quicksearch` باشد.
`search`	رشته	متن مورد نظر برای جستجو در نام یا شماره موبایل.

دریافت لیست محصولات

POST

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

پارامترهای ارسالی (Action: `product_list`)

پارامتر	نوع	توضیحات
`action`	رشته	باید برابر با `product_list` باشد.

درخواست پیگیری خودکار

POST

با فراخوانی این متد، سیستم به صورت خودکار عملیات‌های تعریف شده برای پیگیری (مانند ارسال پیامک خوش‌آمدگویی یا ثبت وظیفه برای کارشناس) را برای شخص مورد نظر اجرا می‌کند.

پارامترهای ارسالی (Action: `person_followup`)

پارامتر	نوع	توضیحات
`action`	رشته	باید برابر با `person_followup` باشد.
`mobile`	عدد	شماره موبایل شخص جهت شناسایی و اجرای عملیات.
`name`	رشته	نام شخص (در صورت عدم وجود، رکورد ساخته می‌شود).

تغییر مرحله فروش

POST

مدیریت وضعیت مشتری در قیف فروش. این متد به دستیار هوشمند شما اجازه می‌دهد تا پس از یک مکالمه یا اقدام خاص، وضعیت مشتری را به مرحله بعدی (مثلاً از "سرنخ" به "مذاکره") تغییر دهد.

پارامترهای ارسالی (Action: `person_changephase`)

پارامتر	نوع	توضیحات
`action`	رشته	باید برابر با `person_changephase` باشد.
`mobile`	رشته	شماره موبایل مشتری.
`oldphase`	عدد	شناسه مرحله فعلی.
`newphase`	عدد	شناسه مرحله جدید.

دریافت لیست پیام‌های آماده

POST

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

پارامترهای ارسالی (Action: `message_list`)

پارامتر	نوع	توضیحات
`action`	رشته	باید برابر با `message_list` باشد.

ارسال پیام (SMS، واتساپ و ...)

POST

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

پارامترهای ارسالی (Action: `outbox_save`)

پارامتر	نوع	توضیحات
`action`	رشته	باید برابر با `outbox_save` باشد.
`personlist`	رشته	شناسه مخاطبان (جدا شده با کاما).
`messageid`	عدد	شناسه قالب پیام (در صورت استفاده از قالب).
`channelid`	عدد	شناسه کانال ارسال (پیامک، واتساپ و ...).
`sendtime`	Timestamp	زمان ارسال (خالی برای ارسال فوری).

دریافت نوبت‌ها و زمان‌های رزرو شده (getbooked)

POST

این متد برای استخراج تمامی نوبت‌ها، جلسات و رزروهای پر شده در بازه یک روز مشخص برای ممانعت از ایجاد هرگونه تداخل زمانی یا ثبت نوبت‌های همزمان برای کارشناسان یا پزشکان استفاده می‌شود.

پارامترهای ارسالی (Action: `task_getbooked`)

پارامتر	نوع	توضیحات
`action`	رشته	باید برابر با `task_getbooked` باشد.
`day_start`	Timestamp	برچسب زمان یونیکس (Unix Timestamp) شروع روز انتخابی (ساعت 00:00:00).
`day_end`	Timestamp	برچسب زمان یونیکس پایان روز انتخابی (ساعت 23:59:59).
`userid`	عدد	شناسه کارشناس یا پزشک جهت فیلتر کردن نوبت‌های او (اختیاری).
`departmentid`	عدد	شناسه دپارتمان کاری جهت فیلتر نوبت‌های بخش مربوطه (اختیاری).
`productid`	عدد	شناسه لاین خدمات یا محصول مرتبط (اختیاری).
`id`	عدد	شناسه تسک در حال ویرایش. ارسال این شناسه مانع از تداخل نوبت با خودش در فرآیند ویرایش (Self-Conflict) می‌گردد.

ثبت و تنظیم وب‌هوک بات‌های پیام‌رسان

POST

این متد برای تعریف توکن خصوصی، پلتفرم و ثبت امن وب‌هوک بات‌های بله و تلگرام در سیستم به کار می‌رود. درخواست ارسال شده با اکشن settings_set_webhook در هسته بک‌اند از طریق کنترلر تنظیمات مدیریت می‌شود.

پارامترهای ارسالی (Action: `settings_set_webhook`)

پارامتر	نوع	توضیحات
`action`	رشته	باید برابر با `settings_set_webhook` باشد.
`token`	رشته	توکن محرمانه و اختصاصی بات دریافتی از BotFather تلگرام یا بله.
`platform`	عدد	شناسه نوع پلتفرم: مقدار `1` برای پیام‌رسان بله و مقدار `2` برای تلگرام.
`secret`	رشته	هش MD5 توکن محرمانه بات که برای تایید هویت در وب‌هوک ارسالی استفاده می‌شود.

آدرس پردازشگر وب‌هوک دریافت پیام بات

POST

آدرس پایه وب‌هوک که باید در سرورهای بله و تلگرام ثبت شود تا پیام‌ها و تعاملات مراجعین را به تیکت‌های سیستم سیمین تبدیل کند. این آدرس مجهز به لایه امنیتی توکن هش است.

فرمت آدرس ثبت وب‌هوک (WebHook URL)

https://app.simincrm.ir/api/botwebhook.php?secret={MD5_HASH_OF_TOKEN}

توضیح رفتار دریافت و ارسال:

تایید امنیتی: وب‌هوک در صورت غیاب یا مغایرت پارامتر secret از پذیرش پیام‌ها ممانعت کرده و امنیت درگاه را تضمین می‌کند.
ثبت تیکت و پاسخ: پیام‌های کاربران بات به صورت تیکت‌های پشتیبانی (tasktype = 1) و پاسخ‌های مراجعین به عنوان پاسخ تیکت (comment) به همراه ضمیمه‌سازی خودکار عکس، PDF یا ZIP به فرمت WebP تبدیل و ثبت می‌گردد.

ایده‌های خلاقانه برای استفاده از API

دستیار هوشمند و AI

با اتصال مدل‌های زبانی (مانند ChatGPT) به API، می‌توانید دستیاری بسازید که به صورت خودکار:

خلاصه مکالمات را در بخش task_save ثبت کند.
بر اساس نیاز مشتری، محصولات را جستجو کرده و قیمت بدهد.
مرحله فروش مشتری را پس از تایید نهایی تغییر دهد.

یکپارچه‌سازی با VOIP

با استفاده از متد person_callerid، به محض زنگ خوردن تلفن:

نام و سوابق خرید مشتری را روی مانیتور اپراتور نمایش دهید.
در صورت VIP بودن مشتری، تماس را به اولویت بالاتر منتقل کنید.
اگر مشتری جدید است، بلافاصله فرم ثبت‌نام را باز کنید.

پاسخ‌های سیستم

سیستم در پاسخ به هر درخواست یک شیء JSON برمی‌گرداند که وضعیت موفقیت عملیات را مشخص می‌کند.

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

{
    "success": true,
    "msg": "عملیات با موفقیت انجام شد",
    "id": 123
}

نمونه پاسخ خطا:

{
    "success": false,
    "err": 1,
    "msg": "شماره موبایل تکراری است"
}

نمونه کدها

<?php
$apiUrl = 'https://app.simincrm.ir/api/api.php';
$data = [
    'apikey' => 'YOUR_API_KEY',
    'action' => 'orders_neworder',
    'mobile' => '09120000000',
    'name' => 'نام مشتری',
    'amount' => 500000,
    'productid' => 1
];

$ch = curl_init($apiUrl);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));
$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
print_r($result);
?>

import requests

url = "https://app.simincrm.ir/api/api.php"
payload = {
    "apikey": "YOUR_API_KEY",
    "action": "orders_neworder",
    "mobile": "09120000000",
    "name": "نام مشتری",
    "amount": 500000,
    "productid": 1
}

response = requests.post(url, data=payload)
print(response.json())

const formData = new FormData();
formData.append('apikey', 'YOUR_API_KEY');
formData.append('action', 'orders_neworder');
formData.append('mobile', '09120000000');
formData.append('name', 'نام مشتری');
formData.append('amount', '500000');

fetch('https://app.simincrm.ir/api/api.php', {
    method: 'POST',
    body: formData
})
.then(response => response.json())
.then(data => console.log(data));

مقدمه

احراز هویت

متدها و فراخوانی‌ها

ثبت سفارش و مشتری جدید

پارامترهای ارسالی (Action: orders_neworder)

ثبت یا ویرایش شخص

پارامترهای ارسالی (Action: person_save)

دریافت لیست اشخاص

پارامترهای ارسالی (Action: person_list)

لیست فعالیت‌ها

پارامترهای ارسالی (Action: task_list)

ثبت یا ویرایش فعالیت

پارامترهای ارسالی (Action: task_save)

بارگذاری اطلاعات فعالیت

پارامترهای ارسالی (Action: task_load)

حذف فعالیت

پارامترهای ارسالی (Action: task_delete)

جستجوی کالر آیدی (Caller ID)

پارامترهای ارسالی (Action: person_callerid)

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

پارامترهای ارسالی (Action: person_quicksearch)

دریافت لیست محصولات

پارامترهای ارسالی (Action: product_list)

درخواست پیگیری خودکار

پارامترهای ارسالی (Action: person_followup)

تغییر مرحله فروش

پارامترهای ارسالی (Action: person_changephase)

دریافت لیست پیام‌های آماده

پارامترهای ارسالی (Action: message_list)

ارسال پیام (SMS، واتساپ و ...)

پارامترهای ارسالی (Action: outbox_save)

دریافت نوبت‌ها و زمان‌های رزرو شده (getbooked)

پارامترهای ارسالی (Action: task_getbooked)

ثبت و تنظیم وب‌هوک بات‌های پیام‌رسان

پارامترهای ارسالی (Action: settings_set_webhook)

آدرس پردازشگر وب‌هوک دریافت پیام بات

فرمت آدرس ثبت وب‌هوک (WebHook URL)

توضیح رفتار دریافت و ارسال:

ایده‌های خلاقانه برای استفاده از API

دستیار هوشمند و AI

یکپارچه‌سازی با VOIP

پاسخ‌های سیستم

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

نمونه پاسخ خطا:

نمونه کدها

پارامترهای ارسالی (Action: `orders_neworder`)

پارامترهای ارسالی (Action: `person_save`)

پارامترهای ارسالی (Action: `person_list`)

پارامترهای ارسالی (Action: `task_list`)

پارامترهای ارسالی (Action: `task_save`)

پارامترهای ارسالی (Action: `task_load`)

پارامترهای ارسالی (Action: `task_delete`)

پارامترهای ارسالی (Action: `person_callerid`)

پارامترهای ارسالی (Action: `person_quicksearch`)

پارامترهای ارسالی (Action: `product_list`)

پارامترهای ارسالی (Action: `person_followup`)

پارامترهای ارسالی (Action: `person_changephase`)

پارامترهای ارسالی (Action: `message_list`)

پارامترهای ارسالی (Action: `outbox_save`)

پارامترهای ارسالی (Action: `task_getbooked`)

پارامترهای ارسالی (Action: `settings_set_webhook`)