مفاهیم پایه دیدار

آشنایی ساده با Entityهای دیدار و رابطه میان آن‌ها در OpenAPI

مفاهیم پایه دیدار

این نمودار نشان می‌دهد اطلاعات مختلف دیدار چطور به هم وصل می‌شوند. لازم نیست برای شروع همه رابطه‌ها را حفظ کنید؛ کافی است اول Entity موردنیازتان را پیدا کنید، بعد فلش‌های متصل به آن و نام پراپرتی‌های روی خط‌ها را بخوانید.

راهنمای مطالعه ERD

کادرهای سبز پررنگ

هر کادر سبز پررنگ یک Entity است؛ یعنی یک نوع داده مشخص که در API با آن کار می‌کنید. برای مثال Person یک شخص، Deal یک معامله و Activity یک فعالیت را نشان می‌دهد.

کادرهای سبز کم‌رنگ

کادرهای کم‌رنگ فقط Entityهای هم‌خانواده را کنار هم قرار داده‌اند و خودشان لزوماً یک Entity مستقل نیستند:

• کادر Contact شامل Company و Person است.
• کادر Product شامل Product و Product Category است.
• کادر Invoice/Quote شامل Invoice و Quote است.
• کادر Activity/Note شامل Activity، Note و Activity Type است.
• کادر Pipelines شامل Deal Pipeline و Case Pipeline است.

خطی که فقط یک فلش دارد

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

Deal -- SourceId --> Source

یعنی در اطلاعات یک Deal، پراپرتی SourceId مشخص می‌کند منبع این معامله کدام رکورد از Entity Source است.

چند پراپرتی روی یک خط

اگر چند نام با / روی یک خط نوشته شده باشد، بیش از یک پراپرتی می‌تواند آن ارتباط را بسازد.

Deal -- personId/CompanyId/OtherContactIds --> Contact

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

اگر پراپرتی به‌شکل Tags[].TagId نوشته شده باشد، یعنی Tags یک آرایه است و TagId داخل هر عضو آن قرار دارد.

خطی که در هر دو سمت فلش دارد

دو فلش یعنی هر دو Entity می‌توانند به یکدیگر اشاره کنند و هر سمت پراپرتی خودش را دارد. برای مثال، رابطه Deal و Case در نمودار دوطرفه است:

Deal -- CaseId --> Case
Case -- DealId --> Deal

پس ممکن است در اطلاعات معامله، CaseId را ببینید و در اطلاعات کارت نیز DealId را دریافت کنید.

نکته مهم درباره جهت فلش‌ها

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

این ERD فقط Entityها و مسیر ارتباط آن‌ها را نشان می‌دهد. از روی نمودار نمی‌توان فهمید یک پراپرتی الزامی است یا اختیاری، یک رابطه چند رکورد می‌پذیرد یا هنگام حذف رکورد چه اتفاقی می‌افتد. برای این موارد، صفحه Endpoint مربوط را در API Reference بخوانید.

Entityهای دیدار

Contact

Contact اسم کلی مخاطبان در دیدار است. مخاطب می‌تواند یک فرد باشد که در Person ذخیره می‌شود یا یک کسب‌وکار باشد که در Company ذخیره می‌شود. بنابراین معمولاً رکورد مستقلی به نام Contact در رابط دیدار نمی‌بینید؛ این نام در مدل API برای کنار هم قرار دادن شخص و شرکت استفاده شده است.

مثلاً «سارا محمدی» یک Person و «شرکت پارس‌گستر» یک Company است. هر دو در مفهوم کلی‌تر Contact قرار می‌گیرند.

ارتباط‌های Contact در ERD

• Deal با personId، CompanyId یا OtherContactIds به مخاطبان یک معامله وصل می‌شود.
• Case با PersonId، CompanyId یا OtherContactId به مخاطبان یک کارت وصل می‌شود.
• Activity و Note با ContactId به مخاطب مرتبط وصل می‌شوند.
• مخاطب با OwnerId به کاربری وصل می‌شود که مسئول پیگیری آن است.
• SegmentIds مشخص می‌کند مخاطب در کدام Segmentها قرار گرفته است.
• CityId و ProvinceId مخاطب را به شهر و استان موجود در Locations وصل می‌کنند.
• Fields مقادیر فیلدهای اضافه مخاطب را نگه می‌دارد و به Custom Fields مربوط است.

Person

Person یعنی یک فرد واقعی که اطلاعاتش را به‌عنوان مخاطب در دیدار ثبت کرده‌اید؛ مثلاً مشتری، سرنخ فروش، خریدار یا فردی که در یک شرکت کار می‌کند. Person را با User اشتباه نگیرید: شخص معمولاً مشتری یا مخاطب شماست، اما User کسی است که وارد دیدار می‌شود و با سیستم کار می‌کند.

مثلاً اگر «سارا محمدی» مدیر خرید شرکت پارس‌گستر باشد، سارا یک Person است و پارس‌گستر یک Company.

ارتباط‌های Person در ERD

• بین Person و Company فلش دوطرفه وجود دارد؛ یعنی می‌توان شخص را به شرکت مرتبط کرد و از سمت شرکت نیز به اشخاص مرتبط رسید. نام پراپرتی‌های این رابطه روی ERD نوشته نشده است.
• Deal، Case، Activity و Note می‌توانند از طریق پراپرتی‌های مربوط به Contact به یک Person وصل شوند.
• Person به‌عنوان یکی از انواع Contact می‌تواند مسئول، Segment، شهر و استان و فیلدهای اضافه داشته باشد.

Company

Company یعنی یک شرکت، سازمان یا کسب‌وکار که با آن در ارتباط هستید. این Entity خود شرکتی که اکانت دیدار را خریده نیست؛ یکی از شرکت‌هایی است که آن کسب‌وکار به‌عنوان مشتری، سرنخ یا طرف تجاری در CRM ثبت کرده است.

مثلاً اگر شرکت شما به «پارس‌گستر» نرم‌افزار می‌فروشد، پارس‌گستر در Company ذخیره می‌شود و کارکنان آن مثل سارا محمدی در Person قرار می‌گیرند.

ارتباط‌های Company در ERD

• بین Company و Person رابطه دوطرفه وجود دارد تا افراد شاغل یا مرتبط با یک شرکت به آن وصل شوند. ERD نام پراپرتی‌های این رابطه را مشخص نکرده است.
• Deal، Case، Activity و Note می‌توانند از طریق پراپرتی‌های مربوط به Contact به یک Company وصل شوند.
• Company به‌عنوان یکی از انواع Contact می‌تواند مسئول، Segment، شهر و استان و فیلدهای اضافه داشته باشد.

User (Owner)

User کسی است که اجازه دارد وارد اکانت دیدار شود و داخل آن کار کند؛ مثل مدیر فروش، کارشناس فروش یا ادمین. عبارت Owner هم معمولاً یعنی کاربری که مسئول پیگیری یک رکورد است.

مثلاً یک شرکت دیدار را می‌خرد، یک نفر را به‌عنوان ادمین و ۱۰ نفر را به‌عنوان کارشناس فروش اضافه می‌کند. در این حالت، آن اکانت در مجموع ۱۱ رکورد User دارد. مشتریان این شرکت User نیستند؛ آن‌ها در Person یا Company ثبت می‌شوند.

ارتباط‌های User در ERD

• Contact با OwnerId به کاربر مسئول مخاطب وصل می‌شود.
• Deal با OwnerId به مسئول معامله و با CreatorId به ایجادکننده معامله وصل می‌شود.
• Case با OwnerId به مسئول کارت و با UserIds به کاربران مرتبط با کارت وصل می‌شود.
• Activity و Note با OwnerId به کاربر مسئول وصل می‌شوند.
• Invoice و Quote با CreatorId به کاربری وصل می‌شوند که سند را ایجاد کرده است.

Deal

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

مثلاً شرکت پارس‌گستر برای خرید ۲۰ لایسنس درخواست دمو داده است. شما یک معامله به نام «فروش ۲۰ لایسنس به پارس‌گستر» می‌سازید و آن را از مرحله «درخواست دمو» به «مذاکره» و در نهایت «برنده‌شده» یا «شکست‌خورده» منتقل می‌کنید.

ارتباط‌های Deal در ERD

• با personId، CompanyId و OtherContactIds به شخص، شرکت و سایر مخاطبان معامله وصل می‌شود.
• با OwnerId به مسئول معامله و با CreatorId به ایجادکننده آن وصل می‌شود.
• با PipelineId و PipelineStageId به کاریز معامله و مرحله فعلی آن در Deal Pipeline وصل می‌شود.
• با DealItems به محصولات موجود در Product وصل می‌شود.
• با SourceId به منبع معامله، با LostReasonId به دلیل شکست و با LabelIds به برچسب‌های معامله وصل می‌شود.
• با Fields مقادیر فیلدهای اضافه معامله را نگه می‌دارد.
• رابطه Deal و Activity/Note دوطرفه است: Deal با ActivityId به فعالیت یا یادداشت وصل می‌شود و فعالیت یا یادداشت با DealId به معامله برمی‌گردد.
• رابطه Deal و Case نیز دوطرفه است: Deal با CaseId به کارت و Case با DealId به معامله مرتبط می‌شود.
• Invoice و Quote با DealId به معامله‌ای وصل می‌شوند که سند برای آن ساخته شده است.

Deal Pipeline

Deal Pipeline همان کاریز معامله است؛ یعنی مسیری که معامله‌ها در طول فرایند فروش طی می‌کنند. هر کاریز چند مرحله دارد و هر معامله در هر لحظه داخل یکی از آن مرحله‌ها قرار می‌گیرد.

مثلاً یک کاریز می‌تواند مراحل «سرنخ جدید»، «دمو»، «ارسال پیشنهاد» و «مذاکره» داشته باشد. با جابه‌جایی معامله بین این مراحل می‌توانید بفهمید فروش در چه وضعیتی است.

ارتباط‌های Deal Pipeline در ERD

• Deal با PipelineId کاریز خود و با PipelineStageId مرحله فعلی خود را مشخص می‌کند.
• این Entity در کادر گروهی Pipelines کنار Case Pipeline قرار گرفته است، اما کاریز معامله و کاریز کارت دو ساختار جدا هستند.

Source

Source مشخص می‌کند یک معامله از چه راهی وارد فرایند فروش شده است. این اطلاعات کمک می‌کند بفهمید مشتری از تبلیغات، معرفی، سایت، نمایشگاه یا هر مسیر دیگری آمده است.

مثلاً اگر مشتری بعد از پر کردن فرم سایت با شما تماس گرفته باشد، Source معامله می‌تواند «وب‌سایت» باشد.

ارتباط‌های Source در ERD

• Deal با SourceId به یک رکورد از Source وصل می‌شود.

Lost Reason

Lost Reason دلیل شکست یک معامله را نگه می‌دارد؛ یعنی وقتی فروش انجام نمی‌شود، مشخص می‌کنید چرا مشتری خرید نکرده است.

مثلاً «قیمت بالا بود»، «رقیب را انتخاب کرد» یا «در حال حاضر بودجه ندارد» می‌توانند Lost Reason باشند.

ارتباط‌های Lost Reason در ERD

• Deal با LostReasonId به دلیل شکست انتخاب‌شده وصل می‌شود.
• این ارتباط زمانی معنا پیدا می‌کند که معامله شکست‌خورده باشد؛ قواعد الزامی‌بودن آن را باید در Endpoint مربوط بررسی کنید.

Deal Label

Deal Label همان برچسب معامله است. برچسب کمک می‌کند معامله‌ها را با یک نشانه قابل‌فهم دسته‌بندی یا سریع‌تر پیدا کنید.

مثلاً می‌توانید برچسب‌هایی مثل «مهم»، «تمدید» یا «نیاز به پیگیری مدیر» داشته باشید.

ارتباط‌های Deal Label در ERD

• Deal با LabelIds به یک یا چند Deal Label وصل می‌شود.
• این برچسب مخصوص معامله است و با Case Label که برای کارت‌ها استفاده می‌شود یکی نیست.

Case

Case همان کارت در دیدار است. کارت برای پیگیری کارهایی استفاده می‌شود که الزاماً یک فروش و مبلغ مشخص نیستند. بسته به ساختاری که کسب‌وکار ساخته، کارت می‌تواند برای یک فرایند داخلی، کانبان، تیکت یا یک مسیر کاری دیگر استفاده شود.

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

ارتباط‌های Case در ERD

• با PersonId، CompanyId و OtherContactId به شخص، شرکت یا مخاطب دیگر مرتبط با کارت وصل می‌شود.
• با OwnerId به مسئول کارت و با UserIds به کاربران مرتبط با آن وصل می‌شود.
• با PipelineStageId به مرحله فعلی خود در Case Pipeline وصل می‌شود.
• با LabelIds به برچسب‌های کارت در Case Label وصل می‌شود.
• با Fields مقادیر فیلدهای اضافه کارت را نگه می‌دارد.
• Activity و Note با caseId به کارت مرتبط وصل می‌شوند.
• رابطه Case و Deal دوطرفه است: Case با DealId به معامله و Deal با CaseId به کارت مرتبط می‌شود.

Case Pipeline

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

مثلاً برای فرایند راه‌اندازی مشتری می‌توانید مراحل «دریافت اطلاعات»، «تنظیمات اولیه»، «آموزش» و «تحویل» را داشته باشید.

ارتباط‌های Case Pipeline در ERD

• Case با PipelineStageId به مرحله فعلی خود در Case Pipeline وصل می‌شود.
• این Entity داخل کادر Pipelines کنار Deal Pipeline قرار دارد، اما کارت‌ها و معامله‌ها از Pipelineهای جدا استفاده می‌کنند.

Case Label

Case Label همان برچسب کارت است. این برچسب برای دسته‌بندی یا علامت‌گذاری کارت‌ها استفاده می‌شود، نه معامله‌ها.

مثلاً کارت‌های «فوری»، «نیازمند بررسی فنی» یا «در انتظار مشتری» می‌توانند برچسب جدا داشته باشند.

ارتباط‌های Case Label در ERD

• Case با LabelIds به یک یا چند Case Label وصل می‌شود.
• Case Label با Deal Label فرق دارد: اولی برای کارت و دومی برای معامله است.

Activity

Activity کاری است که یک کاربر باید انجام دهد یا قبلاً انجام داده است؛ مثل تماس، جلسه، پیگیری، ارسال پیام یا هر اقدام دیگری که تیم در دیدار تعریف کرده باشد. فعالیت می‌تواند زمان، مسئول، نوع و رکورد مرتبط داشته باشد.

مثلاً کارشناس فروش برای فردا ساعت ۱۰ یک فعالیت «تماس برای پیگیری پیشنهاد قیمت» می‌سازد و آن را به معامله پارس‌گستر وصل می‌کند.

ارتباط‌های Activity در ERD

• با ActivityTypeId به نوع فعالیت در Activity Type وصل می‌شود.
• با OwnerId به کاربری وصل می‌شود که مسئول انجام فعالیت است.
• با ContactId به مخاطب مرتبط وصل می‌شود.
• با DealId به معامله و با caseId به کارت مرتبط وصل می‌شود.

Note

Note همان یادداشت است؛ یک متن آزاد برای ثبت اطلاعاتی که لازم است کنار مخاطب، معامله یا کارت باقی بماند. یادداشت کار قابل‌زمان‌بندی نیست، اما در مدل API کنار Activity قرار گرفته است.

مثلاً بعد از تماس می‌توانید بنویسید: «مشتری تا پایان هفته قیمت نهایی را بررسی می‌کند.» این متن یک Note است.

ارتباط‌های Note در ERD

• با ActivityTypeId به نوع مربوط در Activity Type وصل می‌شود.
• با OwnerId به کاربر مسئول یا ثبت‌کننده مرتبط می‌شود.
• با ContactId به مخاطب، با DealId به معامله و با caseId به کارت مرتبط وصل می‌شود.

Activity Type

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

مثلاً فعالیت «تماس برای پیگیری» می‌تواند به Activity Type با عنوان «تماس» متصل باشد.

ارتباط‌های Activity Type در ERD

• Activity و Note هر دو با ActivityTypeId به Activity Type وصل می‌شوند.
• Activity Type از مسیر Tags[].TagId به Tags متصل شده است؛ یعنی شناسه Tag داخل اعضای آرایه Tags قرار می‌گیرد.

Tags

Tags تگ‌هایی را نگه می‌دارد که در این ERD برای دسته‌بندی یا تکمیل اطلاعات نوع فعالیت استفاده می‌شوند.

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

ارتباط‌های Tags در ERD

• Activity Type با Tags[].TagId به تگ‌های مرتبط وصل می‌شود.

Product

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

مثلاً «لایسنس یک‌ساله نرم‌افزار»، «جلسه مشاوره» یا «دستگاه حضور و غیاب» هرکدام می‌توانند یک Product باشند.

ارتباط‌های Product در ERD

• با ProductCategoryId به گروه خود در Product Category وصل می‌شود.
• Deal با DealItems محصولات معامله را به Productها وصل می‌کند.
• Invoice و Quote با Items[] محصولات یا اقلام داخل سند را به Productها وصل می‌کنند.
• با Fields مقادیر فیلدهای اضافه محصول را نگه می‌دارد.

Product Category

Product Category همان گروه محصول است و برای مرتب‌کردن محصولات مشابه استفاده می‌شود.

مثلاً محصولات «نرم‌افزار»، «سخت‌افزار» و «خدمات آموزشی» می‌توانند در سه گروه جدا قرار بگیرند.

ارتباط‌های Product Category در ERD

• Product با ProductCategoryId به گروه محصول خودش وصل می‌شود.
• هر Product به شناسه یک Product Category اشاره می‌کند؛ تعداد و الزامی‌بودن این رابطه را باید در Endpoint محصول بررسی کنید.

Invoice

Invoice همان فاکتور است؛ سندی که اقلام، تعداد، قیمت و مبلغ فروش را ثبت می‌کند. فاکتور معمولاً بعد از قطعی‌شدن فروش یا برای ثبت مبلغی که باید پرداخت شود ساخته می‌شود.

مثلاً بعد از نهایی‌شدن فروش ۲۰ لایسنس، یک فاکتور شامل همان ۲۰ لایسنس و مبلغ آن‌ها ایجاد می‌شود.

ارتباط‌های Invoice در ERD

• با Items[] به محصولات یا اقلام موجود در Product وصل می‌شود.
• با DealId به معامله مرتبط وصل می‌شود.
• با CreatorId به کاربری وصل می‌شود که فاکتور را ایجاد کرده است.
• Invoice و Quote در ERD داخل یک کادر قرار گرفته‌اند، چون روابط اصلی مشابهی دارند؛ با این حال دو نوع سند متفاوت‌اند.

Quote

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

مثلاً قبل از توافق نهایی، پیش‌فاکتوری برای ۲۰ لایسنس به شرکت پارس‌گستر ارسال می‌شود تا قیمت را بررسی کند.

ارتباط‌های Quote در ERD

• با Items[] به محصولات یا اقلام موجود در Product وصل می‌شود.
• با DealId به معامله مرتبط وصل می‌شود.
• با CreatorId به کاربری وصل می‌شود که پیش‌فاکتور را ایجاد کرده است.

Custom Fields

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

مثلاً یک شرکت می‌تواند روی مخاطب فیلد «کد ملی»، روی معامله فیلد «نام رقیب» و روی محصول فیلد «مدت گارانتی» بسازد. تعریف این فیلدها در Custom Fields قرار می‌گیرد و مقدار هر فیلد داخل Fields همان رکورد ارسال یا دریافت می‌شود.

ارتباط‌های Custom Fields در ERD

• Contact، Deal، Case و Product با پراپرتی Fields به فیلدهای اضافه مربوط به نوع خود وصل می‌شوند.
• کلیدهای داخل Fields برای همه Entityها یکسان نیستند. قبل از ارسال مقدار، باید کلید فیلد اضافه همان نوع Entity را دریافت کنید.

Segment

Segment برای گروه‌بندی مخاطبان استفاده می‌شود. Segment کمک می‌کند چند شخص یا شرکت را براساس یک ویژگی یا کاربرد کنار هم قرار دهید.

مثلاً می‌توانید Segmentهایی مثل «مشتریان تهران»، «مشتریان VIP» یا «سرنخ‌های نمایشگاه» داشته باشید.

ارتباط‌های Segment در ERD

• Contact با SegmentIds به یک یا چند Segment وصل می‌شود.
• Segment در این ERD مستقیماً به Entity دیگری وصل نشده است.

Locations

Locations اطلاعات مرجع شهر و استان را نگه می‌دارد. به‌جای فرستادن نام شهر و استان در رابطه ERD، شناسه آن‌ها روی مخاطب قرار می‌گیرد.

مثلاً یک Company می‌تواند با شناسه استان تهران و شناسه شهر تهران ذخیره شود.

ارتباط‌های Locations در ERD

• Contact با CityId و ProvinceId به شهر و استان موجود در Locations وصل می‌شود.

خلاصه نام Entityها در دیدار

نام در ERD و API	نامی که در دیدار می‌بینید
Contact	مخاطب
Person	شخص
Company	شرکت
User (Owner)	کاربر / مسئول
Deal	معامله
Deal Pipeline	کاریز معامله
Source	شیوه آشنایی معامله
Lost Reason	دلیل شکست
Deal Label	برچسب معامله
Case	کارت
Case Pipeline	کاریز کارت
Case Label	برچسب کارت
Activity	فعالیت
Note	یادداشت
Activity Type	نوع فعالیت
Tags	تگ فعالیت و یادداشت
Product	محصول
Product Category	گروه محصول
Invoice	فاکتور
Quote	پیش‌فاکتور
Custom Fields	فیلدهای اضافه
Segment	دسته‌بندی مخاطبان / Segment
Locations	شهر و استان