# اتصال به CRM دیدار

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

## دو جهت، نه یکی

اتصال دیدار در «مدیریت» ← «یکپارچه‌سازی‌ها» (`/admin?sel=integrations`) است و مثل بقیه آن صفحه، حول دو جریان مخالف چیده شده. اگر این دو را از هم جدا نکنید، بقیه تنظیمات گیج‌کننده می‌شود:

| جهت                    | چه چیزی حرکت می‌کند               | چه چیزی را ممکن می‌کند                                     |
| ---------------------- | --------------------------------- | ---------------------------------------------------------- |
| ادپیکس ← دیدار (خروجی) | لید و فروش، با کانال و کمپین جذب  | تیم فروش روی کارت مخاطب می‌بیند این نفر از کجا آمده        |
| دیدار ← ادپیکس (ورودی) | معامله موفق، شکست، فاکتور، پرداخت | درآمد روی همان کمپینی می‌نشیند که بازدیدکننده را آورده بود |

جهت خروجی یک مقصد معمولی است و در [یکپارچه‌سازی‌ها و ماژول‌های CRM](analytics/admin/integrations) توضیح داده شده. این صفحه درباره جهت ورودی است — کاری که هیچ تگ مرورگری نمی‌تواند انجام دهد، چون معامله هفته‌ها بعد و بیرون از مرورگر بسته می‌شود.

> **چرا تگ صفحه کافی نیست**
>
> تگ ادپیکس سفر بازدیدکننده را تا لحظه ترک سایت می‌بیند. در فروش B2B یا پروژه‌ای، تصمیم خرید هفته‌ها بعد و در تماس تلفنی گرفته می‌شود. تا وقتی دیدار آن لحظه را برنگرداند، آن درآمد در ادپیکس وجود ندارد و کمپینی که آن را ساخته بود، در گزارش ROAS بدون فروش به نظر می‌رسد.

## چه چیزی در دیدار لازم دارید

پیش از شروع، در دیدار به این سه چیز نیاز دارید و هر سه دسترسی ادمین می‌خواهند:

1. یک **کلید API**: در دیدار به «تنظیمات» ← «اتصال به سرورهای دیگر» ← زبانه «اتصال به دیدار» بروید و کلید تازه بسازید. مقدارش **فقط یک بار** نمایش داده می‌شود.
2. **شناسه کاربر مالک**: دیدار هر مخاطب را به یک کاربر نسبت می‌دهد، پس این مقدار الزامی است. از فهرست کاربران دیدار برش دارید.
3. اختیاری — یک **فیلد سفارشی متنی** روی مخاطب با عنوان «شناسه بازدیدکننده ادپیکس». دیدار API ساخت فیلد سفارشی ندارد، پس این یکی را باید دستی بسازید؛ ادپیکس بعد خودش از روی عنوان پیدایش می‌کند. نبودنش خطا نیست، فقط ردیابی یک رکورد دیدار تا هویت ادپیکس را ممکن نمی‌کند.

## وصل کردن

در کارت «خواندن معامله ها از دیدار» کلید API و شناسه مالک را بگذارید و «محاسبه درآمد از» را انتخاب کنید. ادپیکس پیش از ذخیره، کلید را با یک فراخوانی سبک آزمایش می‌کند: اتصالی که نتواند با دیدار حرف بزند بدتر از نبود اتصال است، چون وب‌هوک روی کلیدی مرده راه‌اندازی می‌شود.

بعد از ذخیره، **آدرس وب‌هوک** یک بار نمایش داده می‌شود:

```text
https://api.adpix.io/api/v1/crm/didar/hook/dhk_7f3a9c1e…
```

> **این آدرس مثل رمز است**
>
> فرم وب‌هوک دیدار نه هدر سفارشی می‌گیرد و نه کلید امضا، پس توکن داخل آدرس تنها اعتبارنامه این مسیر است: هر کسی آن را داشته باشد می‌تواند برای این وب‌سایت رویداد بفرستد. ادپیکس فقط درهم‌شده‌اش را نگه می‌دارد و آدرس کامل دیگر هرگز نمایش داده نمی‌شود. آن را جایی امن بگذارید، در پیام عمومی نفرستید، و اگر لو رفت «آدرس تازه» بسازید و قبلی را «لغو» کنید.

## ساختن وب‌هوک‌ها در دیدار

این بخش دستی است و راه دیگری ندارد: دیدار API ساخت وب‌هوک ندارد. در دیدار به «تنظیمات» ← «اتصال به سرورهای دیگر» ← «وب‌هوک» بروید و برای هر سطر زیر یک وب‌هوک بسازید. **برای همه، همان یک آدرس را بگذارید** — پیام دیدار خودش می‌گوید چه چیزی است، پس یک نقطه ورود کافی است.

| موجودیت در دیدار | نوع            | برای چه لازم است                                    |
| ---------------- | -------------- | --------------------------------------------------- |
| معامله           | ایجاد و ویرایش | معامله موفق، شکست، و باز شدن معامله تازه            |
| شخص              | ایجاد و ویرایش | لید تازه و تبدیل شدنش به سرنخ واجد شرایط            |
| فاکتور           | ایجاد و ویرایش | تنها اگر «محاسبه درآمد از» را روی فاکتور گذاشته‌اید |
| پرداخت           | ویرایش         | تنها اگر «محاسبه درآمد از» را روی پرداخت گذاشته‌اید |

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

> **تا اولین رویداد، وضعیت «در انتظار اولین رویداد» می‌ماند**
>
> یک اشتباه تایپی در آدرس هیچ خطایی نمی‌دهد — نه در دیدار و نه در ادپیکس. تنها نشانه درست بودن کار این است که وضعیت اتصال سبز شود. اگر بعد از ساختن وب‌هوک‌ها و یک تغییر آزمایشی روی یک معامله، همچنان «در انتظار اولین رویداد» می‌بینید، آدرس را در دیدار دوباره بررسی کنید.

## نقشه رویدادها

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

| در دیدار                           | رویداد ادپیکس                | مبلغ              | پیش‌فرض            |
| ---------------------------------- | ---------------------------- | ----------------- | ------------------ |
| شخص تازه ثبت شد                    | `generate_lead`              | —                 | روشن               |
| مخاطب به سرنخ واجد شرایط تغییر کرد | `qualify_lead`               | —                 | روشن               |
| معامله تازه باز شد                 | `crm_deal_open`              | مبلغ تخمینی       | روشن               |
| **معامله موفق شد**                 | `purchase` یا `crm_deal_won` | مبلغ معامله       | روشن               |
| معامله شکست خورد                   | `crm_deal_lost`              | —                 | روشن               |
| معامله موفق حذف شد                 | `refund`                     | مبلغ معامله       | روشن               |
| فاکتور صادر شد                     | `purchase`                   | مبلغ نهایی فاکتور | فقط در حالت فاکتور |
| پرداخت وصول شد                     | `purchase`                   | مبلغ پرداخت       | فقط در حالت پرداخت |
| مرحله معامله عوض شد                | `crm_stage_change`           | —                 | **خاموش**          |

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

### واحد پول

همه مبالغ دیدار **تومان** خوانده می‌شوند. شناسه واحد پول در پیام دیدار یک عدد است و هیچ سرویسی برای ترجمه‌اش وجود ندارد، پس ادپیکس تنظیماتی برای آن نساخته و در عوض عدد خام را روی هر رویداد ثبت می‌کند. اگر مبالغ شما ریال است، پیش از اتصال با پشتیبانی تماس بگیرید.

## منبع درآمد: چرا یک فروش دو بار شمرده نمی‌شود

معامله موفق دیدار و سفارش ووکامرس می‌توانند **یک فروش** باشند، ولی شناسه‌هایشان هیچ ربطی به هم ندارند، پس ادپیکس نمی‌تواند آن‌ها را روی هم بنشاند. اگر هر دو شمرده شوند، درآمد دو برابر دیده می‌شود.

برای همین هر اتصال دقیقا یک «منبع درآمد» دارد و **ادپیکس خودش آن را تعیین می‌کند**:

| منبع درآمد | چه وقت                                    | معامله موفق چه می‌شود                                                       |
| ---------- | ----------------------------------------- | --------------------------------------------------------------------------- |
| وب‌سایت    | وب‌سایت در ۳۰ روز گذشته خرید ثبت کرده است | `crm_deal_won` بدون مبلغ — قیف فروش، کیفیت لید و دلایل شکست همه کار می‌کنند |
| دیدار      | وب‌سایت خودش فروش نمی‌فرستد               | `purchase` با مبلغ کامل                                                     |

کارت «منبع درآمد» در پنل همین تصمیم را با تعداد خریدهای ۳۰ روز گذشته توضیح می‌دهد. این مقدار **ذخیره** می‌شود و برای هر رویداد از نو حساب نمی‌شود: ردیف‌های تحلیلی فقط افزودنی‌اند و بازنویسی نمی‌شوند، پس مقداری که بین دو تحویل نوسان می‌کرد تاریخی می‌ساخت که هیچ‌کس نمی‌توانست توضیحش دهد.

همین قاعده **داخل** دیدار هم هست: «محاسبه درآمد از» سه گزینه دارد — معامله موفق، فاکتور، پرداخت — و دقیقا یکی فعال می‌شود. برای فروش قسطی «پرداخت» درست‌ترین انتخاب است، چون درآمد هنگام وصول پول ثبت می‌شود نه هنگام بستن معامله.

## هویت: چطور معامله به بازدیدکننده وصل می‌شود

ادپیکس برای هر رویداد دیدار از قوی‌ترین کلید موجود استفاده می‌کند:

| اولویت | کلید              | از کجا می‌آید                                                                         |
| ------ | ----------------- | ------------------------------------------------------------------------------------- |
| ۱      | شماره موبایل      | فیلد موبایل مخاطب — دیدار آن را منحصربه‌فرد می‌خواهد و تقریبا همیشه دارد              |
| ۲      | ایمیل             | فیلد ایمیل مخاطب                                                                      |
| ۳      | شناسه مخاطب دیدار | به‌عنوان شناسه مشتری CRM ذخیره می‌شود، پس رویدادهای بعدی به هیچ داده شخصی نیاز ندارند |

شماره موبایل اول است چون در بازار ایران تقریبا همیشه پر است. شماره با ارقام فارسی هم درست خوانده می‌شود و به همان هویتی می‌رسد که شکل بین‌المللی می‌سازد — یعنی «۰۹۱۲۳۴۵۶۷۸۹» و `+989123456789` یک نفرند.

اگر وب‌سایت شما حالت «داده مشتری» را روی چیزی جز «خام» گذاشته باشد، اتصال هرگز موبایل یا ایمیل خام نمی‌فرستد و پیش از ارسال درهم‌سازی می‌کند. در آن حالت **کد کشور الزامی است**، چون پیام وب‌هوک IP ندارد تا کشور از آن حدس زده شود.

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

## رویدادهای جامانده

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

این کار در پس‌زمینه و آهسته انجام می‌شود (دیدار هیچ سقف نرخی مستند نکرده، پس ادپیکس محافظه‌کارانه رفتار می‌کند). دکمه «بررسی رویدادهای جامانده» یک دور را همین حالا شروع می‌کند.

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

> **گزارش‌ها از تاریخ اتصال به بعد کامل‌اند**
>
> رویدادی که بیش از **هفت روز** قدیمی‌تر باشد ثبت نمی‌شود. دلیلش این نیست که سخت است: چنین رویدادی با تاریخ **امروز** ثبت می‌شد، و یک CRM چندساله در اولین دور خواندن، سال‌ها معامله را به‌صورت یک جهش درآمد ساختگی روی امروز می‌ریخت — و ردیف‌های تحلیلی بازنویسی نمی‌شوند، پس پاک کردنش ممکن نبود. وضعیت آن معامله‌ها خوانده و نگه داشته می‌شود، فقط رویدادی ساخته نمی‌شود.

## سلامت اتصال

کارت سلامت چهار شمارنده دارد که مستقیم از پایگاه داده خوانده می‌شوند: تحویل‌ها، نگاشت‌شده‌ها، نادیده‌گرفته‌شده‌ها و ردشده‌ها. همراهشان دلیل آخرین مورد نادیده‌گرفته‌شده هم می‌آید.

«نادیده گرفته شد» خطا نیست. تغییر مرحله روی تنظیمات پیش‌فرض، یا وب‌هوکی که برای موجودیتی ساخته شده که ادپیکس نگاشت نمی‌کند، همین‌جا شمرده می‌شوند. اگر تعداد تحویل‌ها بالا باشد و تقریبا همه‌شان نادیده گرفته شده باشند، یعنی وب‌هوک‌های اشتباهی در دیدار ساخته‌اید — دلیل کنار شمارنده همین را می‌گوید.

عدد پنجره «از زمان شروع پنجره» شمرده می‌شود، نه «در ۲۴ ساعت گذشته»: پنجره وقتی از ۲۴ ساعت بگذرد صفر می‌شود و از نو شروع می‌کند.

## تغییر و قطع اتصال

- **آدرس تازه**: یک آدرس دوم می‌سازد و آدرس قبلی هم‌زمان کار می‌کند. ترتیب درست این است: آدرس تازه بسازید، در دیدار جایش بگذارید، بعد قبلی را لغو کنید. این‌طور هیچ رویدادی گم نمی‌شود.
- **لغو**: آدرس را بی‌اعتبار می‌کند. ادپیکس اجازه نمی‌دهد آخرین آدرس فعال یک اتصال روشن را لغو کنید، چون دیدار همچنان به آدرسی پیام می‌فرستاد که دیگر پذیرفته نمی‌شود و هیچ‌کس خبردار نمی‌شد.
- **حذف اتصال**: همه آدرس‌ها را لغو و اتصال را خاموش می‌کند. رویدادهایی که قبلا ثبت شده‌اند در گزارش‌ها می‌مانند.

## دسترسی لازم

دیدن این کارت با دسترسی خواندن گزارش ممکن است و کلید API فقط با چند نویسه ابتدایی‌اش نمایش داده می‌شود. ساختن اتصال، تغییر تنظیمات، ساختن یا لغو آدرس و حذف اتصال، همگی اختیار ویرایش تنظیمات وب‌سایت می‌خواهند و در گزارش ممیزی ثبت می‌شوند.

## پرسش‌های پرتکرار

### چرا آدرس وب‌هوک فقط یک بار نمایش داده می‌شود؟

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

### معامله موفق شد ولی درآمدی در گزارش‌ها نیست. چرا؟

اگر وب‌سایت خودتان هم فروش می‌فرستد (مثلا ووکامرس)، ووکامرس منبع درآمد می‌ماند و معامله موفق دیدار به‌عنوان رویداد `crm_deal_won` بدون مبلغ ثبت می‌شود. این کار از دو بار شمردن یک فروش جلوگیری می‌کند. کارت «منبع درآمد» در پنل همین تصمیم را توضیح می‌دهد.

### معامله‌های قدیمی دیدار هم به گزارش‌ها می‌آیند؟

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

### مبالغ دیدار ریال است یا تومان؟

ادپیکس همه مبالغ دیدار را تومان می‌خواند. شناسه واحد پول دیدار یک عدد است و هیچ سرویسی برای ترجمه‌اش ندارد، پس تنظیماتی برای آن ساخته نشده؛ در عوض عدد خام روی هر رویداد ثبت می‌شود تا اگر لازم شد، داده واقعی موجود باشد.

## مطالب مرتبط

- [یکپارچه‌سازی‌ها و ماژول‌های CRM](https://docs.adpix.io/fa/analytics/admin/integrations/)
- [ردیابی سمت سرور](https://docs.adpix.io/fa/analytics/collect/server-side-tracking/)
- [وب هوک ها و امضای HMAC](https://docs.adpix.io/fa/developers/analytics/developers/webhooks-and-hmac/)
- [رویدادهای تجارت الکترونیک](https://docs.adpix.io/fa/analytics/collect/ecommerce-events/)

---

[مستندات](https://docs.adpix.io/fa/analytics/admin/didar-crm/) · AdPix
