رهگیری کاربران

مستندات API کاربران

زمان‌های مورد نیاز برای فراخوانی API کاربران

در کسب‌وکار ما، دو موقعیت اصلی برای فراخوانی این API وجود دارد:

1. ثبت‌نام کاربر: هنگام ثبت‌نام یا ایجاد حساب کاربری جدید، باید این API را برای ایجاد کاربر در سیستم فراخوانی کنید.
2. به‌روزرسانی اطلاعات کاربر: در برخی سناریوهای کسب‌وکار، نیاز است که ویژگی‌های کاربران را به‌روزرسانی کنیم، که در این صورت نیز باید این API فراخوانی شود.

ارسال داده به سرور

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

curl --location --globoff 'https://api.zebline.com/v1/accounts/LICENSE_CODE/users' \
  --header 'authorization: ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "userId": "TX61",
    "firstName": "sample",
    "attributes": {}
  }'

پاسخ سرور

{
    "response": {
        "status": "queued",
        "trackID": "bfb7428a-f017-4b4b-b8f5-fd39c4bad20f"
    }
}

Bulk Mode (Batch Create/Update Users)

Bulk Mode به شما اجازه می‌دهد چندین آبجکت رهگیری (Tracking Object) را در قالب یک درخواست ارسال کنید.

• Bulk endpoint: همان endpoint تک‌درخواستی + مسیر /bulk
• Request body: یک آرایه از آبجکت‌ها با همان schema حالت تک‌درخواستی
• پردازش مستقل: هر آیتم به‌صورت مستقل پردازش می‌شود
• موفقیت/شکست جزئی: ممکن است بعضی آیتم‌ها موفق و بعضی ناموفق باشند (Partial success)

در Bulk Mode می‌توانید چندین کاربر/لید را در یک درخواست ثبت یا به‌روزرسانی کنید. این حالت دقیقاً همان رفتار تک‌درخواستی را برای هر آیتم حفظ می‌کند:

• اگر userId یا anonymousId وجود داشته باشد → به‌روزرسانی (Update)
• اگر وجود نداشته باشد → ایجاد (Create)

Endpoint

الگوی URL در حالت Bulk فقط با اضافه شدن /bulk به انتهای همان endpoint تک‌درخواستی ساخته می‌شود:

• Single:

POST {BASE_URL}/v1/accounts/{LICENSE_CODE}/users

• Bulk:

POST {BASE_URL}/v1/accounts/{LICENSE_CODE}/users/bulk

مقدار BASE_URL معمولاً https://api.zebline.com است و LICENSE_CODE را از داشبورد دریافت می‌کنید.

Request Body (Array of Users)

در حالت Bulk، بدنه درخواست یک آرایه از همان آبجکت‌هایی است که در حالت Single ارسال می‌کنید. یعنی هر عنصر آرایه یک کاربر/لید مستقل است و باید حداقل یکی از کلیدهای userId یا anonymousId را داشته باشد (و طبق مستندات، attributes نیز حتی اگر خالی است ارسال شود).

نکته مهم: هر عنصر آرایه به‌صورت مستقل پردازش می‌شود؛ شکست یک آیتم لزوماً باعث شکست کل batch نمی‌شود.

اگر در attributes فیلدهای زمانی (مثل last_login یا یک ویژگی سفارشی مانند event_time) ارسال می‌کنید، مقدار آن باید به فرمت استاندارد ISO DateTime باشد.

نمونه کامل:

[
  {
    "userId": "user_123",
    "firstName": "Ali",
    "lastName": "Ahmadi",
    "phone": "09123456789",
    "attributes": {
      "event_time": "2026-02-16T10:05:00Z",
      "membership_level": "gold",
      "purchase_count": 5
    }
  },
  {
    "anonymousId": "anon_456",
    "device_type": "mobile",
    "utm_source": "google_ads",
    "attributes": {}
  }
]

Response Body (Bulk)

در Bulk Mode، پاسخ به صورت یک آرایه در کلید response برمی‌گردد که برای هر آیتم ورودی یک نتیجه دارد. ترتیب عناصر در response[] با ترتیب آیتم‌های ارسالی در بدنه درخواست یکسان است.

{
  "response": [
    {
      "status": "queued",
      "trackID": "4d0a469b-3f70-4131-8eb9-72c8889e39c5"
    },
    {
      "status": "queued",
      "trackID": "1e13173a-bedf-4cc5-b7b3-00066bffb80d"
    }
  ]
}

Partial Failures

در Bulk Mode ممکن است بعضی آیتم‌ها پذیرفته شوند و بعضی آیتم‌ها به دلیل خطای اعتبارسنجی رد شوند. در پاسخ Bulk، برای هر آیتم یک نتیجه برمی‌گردد (هم‌راستا با اندیس/ترتیب آیتم ورودی).

نمونه خطاهای اعتبارسنجی برای یک آیتم:

• نبودن شناسه کاربر: وقتی هیچ‌کدام از userId یا anonymousId ارسال نشود.
• زمان نامعتبر: وقتی یک فیلد زمانی (مثل last_login یا attributes.event_time) با فرمت ISO ارسال نشود.
• نوع نامعتبر attributes: وقتی attributes به جای Object، مقدار دیگری (مثل String/Array) داشته باشد.
• نوع نامعتبر یک ویژگی سفارشی: وقتی نوع یک ویژگی که قبلاً ثبت شده تغییر کند (طبق هشدار مهم همین صفحه).

استراتژی HTTP Status (پیشنهادی):

• 200 OK: همیشه 200 برگردانید و نتیجه هر آیتم را در response[] مشخص کنید.

Limits & Best Practices

• حداکثر تعداد آیتم در هر درخواست: در Bulk Mode حداکثر 100 آیتم را در هر درخواست ارسال کنید.
• Chunk کردن داده‌ها: برای importهای بزرگ (مثلاً ده‌ها هزار رکورد)، داده‌ها را به batchهای کوچک‌تر تقسیم کنید.
• Idempotency / تکرارپذیری: اگر درخواست تکراری ارسال شود، به دلیل رفتار UPSERT، آیتم‌ها بر اساس userId/anonymousId دوباره به‌روزرسانی می‌شوند؛ بنابراین بهتر است شناسه‌ها ثابت و یکتا باشند.
• Rate limiting و backoff: اگر با محدودیت نرخ مواجه شدید، بین batchها تأخیر بگذارید و از backoff (مثلاً افزایش تدریجی فاصله زمانی) استفاده کنید.

Notes for Integrations

چه زمانی از Bulk Mode استفاده کنیم؟

• وارد کردن (Import) لیدهای تاریخی
• همگام‌سازی کاربران CRM با Zebline
• به‌روزرسانی‌های شبانه/دوره‌ای (Nightly batch updates)

چه زمانی از Bulk Mode استفاده نکنیم؟

• رخدادهای real-time یا جریان‌های حساس به تاخیر (latency-sensitive) که بهتر است تک‌درخواستی ارسال شوند

---

رفتار API مشابه UPSERT

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

دریافت ACCESS_TOKEN و LICENSE_CODE

می‌توانید ACCESS_TOKEN و LICENSE_CODE خود را از طریق داشبورد در بخش Credentials دریافت کنید. همچنین، با مراجعه به Setup در داشبورد و کلیک بر روی بلوک HTTP، می‌توانید نمونه درخواست‌های cURL را مشاهده کنید و به‌خصوص از GET Users Endpoint برای دریافت این اطلاعات استفاده کنید.

کلیدهای رزرو شده در درخواست

در هر درخواست، باید دو کلید ضروری در بدنه درخواست تعریف شوند:

1. userId یا anonymousId:
   • در صورتی که بخواهید ترافیک شناخته‌شده ارسال کنید، باید مقدار userId را قرار دهید.
   • اگر بخواهید ترافیک ناشناس ارسال کنید، باید از anonymousId استفاده کنید.
   • برای ادغام یک پروفایل ناشناس با یک userId، هر دو کلید anonymousId و userId را در درخواست قرار دهید. در این صورت، سیستم پروفایل ناشناس را با userId ادغام می‌کند.

مثال‌ها برای ارسال کاربران:

ارسال یک کاربر ثبت‌نام شده:

{
  "userId": "user_123",
  "firstName": "Ali",
  "lastName": "Ahmadi",
  "city": "Tehran",
  "phone": "09123456789",
  "attributes": {
   
  }
}

ارسال یک کاربر ناشناس:

{
  "anonymousId": "anon_456",
  "device_type": "mobile",
  "utm_source": "google_ads",
  "attributes": {
   
  }
}

ادغام کاربر ناشناس با شناسه کاربری:

{
  "userId": "user_789",
  "anonymousId": "anon_456",
  "attributes": {

  }
}

اضافه کردن ویژگی‌های سفارشی

برای اضافه کردن یک ویژگی سفارشی جدید، مقدار آن باید در کلید attributes قرار گیرد. به عنوان مثال:

{
  "userId": "user_123",
  "attributes": {
    "favorite_color": "blue",
    "membership_level": "gold"
  }
}

سیستم به‌طور خودکار ویژگی‌های جدید را در پروفایل کاربران ذخیره می‌کند.

danger

توجه:

در همه درخواست‌ها می‌بایست کلید attributes را ارسال نمایید حتی اگر خالی باشد و شما ویژگی سفارشی ندارید.

{
    "userId": "TX61",
    "firstName": "sample",
    "attributes": {}
}

قراردادهای نام‌گذاری

• تمامی کلیدها باید به‌صورت حروف کوچک (lowercase) باشند.
• برای نام‌گذاری کلیدهایی که بیش از یک کلمه دارند، از زیرخط (_) استفاده کنید.
  • مثال: first_name، membership_level، favorite_color

انواع ویژگی‌های سفارشی کاربران

در هنگام ارسال ویژگی‌های سفارشی کاربران، می‌توان از چهار نوع داده استفاده کرد:

اعداد (Numeric Values): مقادیر عددی مانند امتیاز، تعداد خریدها، یا درآمد سالیانه.

رشته‌ها (Strings): مقادیری مانند نام، نام خانوادگی، شهر، یا سطح عضویت.

مقادیر بولی (Booleans): مقادیر true یا false برای مواردی مانند عضویت در خبرنامه.

تاریخ و زمان (Datetime): که باید به فرمت استاندارد ISO DateTime باشد.

مثال‌هایی از ویژگی‌های سفارشی در درخواست API:

{
"userId": "user_123",
"attributes": {
    "purchase_count": 5,
    "membership_level": "gold",
    "verified_user": true,
    "last_login": "2024-02-10T12:30:00Z"
  }
}

توجه:

در همه درخواست‌ها می‌بایست کلید attributes را ارسال نمایید حتی اگر خالی باشد و شما ویژگی سفارشی ندارید.

---

نمونه درخواست HTTP

{
    "userId": "TX61",
    "firstName": "sample",
    "attributes": {}
}

---

---

خطاهای متداول

• اگر اعتبارنامه‌های نادرست (مانند کد لایسنس یا توکن دسترسی) ارسال کنید، خطای 401 Unauthorized دریافت خواهید کرد.

  • مثال: ارسال یک توکن منقضی شده یا اشتباه.
  • راه‌حل: اطمینان حاصل کنید که توکن معتبر و به‌روز است.

• اگر فرمت درخواست نادرست باشد، خطای 400 Bad Request دریافت خواهید کرد.

  • مثال: ارسال داده‌هایی با ساختار اشتباه یا مقدار نامعتبر در فیلدها.
  • راه‌حل: از فرمت استاندارد JSON استفاده کنید و از صحت داده‌ها اطمینان حاصل کنید.

• اگر چیزی ارسال کنید که با ساختار سرویس ناسازگار باشد، خطای 500 Internal Server Error دریافت خواهید کرد.

  • مثال: ارسال داده‌هایی که سیستم قادر به پردازش آن‌ها نیست.
  • راه‌حل: بررسی کنید که آیا داده‌ها مطابق مستندات API ارسال شده‌اند و درخواست را دوباره ارسال کنید.

• اگر userId یا Anonymous ID نادرست باشد، خطای مرتبط با آن دریافت خواهید کرد.

  • مثال: ارسال userId که با فرمت نا معتبر.
  • راه‌حل: مطمئن شوید که userId به صورت رشته و معتبر است.

---

⚠️ هشدار مهم

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

✅ مثال صحیح:

{
    "userId": "TX61",
    "firstName": "sample",
    "attributes": {
        "age": 30
    }
}

در درخواست بعدی باید مقدار age همچنان عددی باشد.

❌ مثال نادرست:

{
    "userId": "TX61",
    "firstName": "sample",
    "attributes": {
        "age": "thirty"
    }
}

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

ویژگی‌های سیستمی کاربران

نام فیلد	نوع داده	توضیحات
userid	STRING	شناسه کاربر
anonymousid	STRING	شناسه ناشناس
firstname	STRING	نام
lastname	STRING	نام خانوادگی
email	STRING	ایمیل
birth_date	TIMESTAMPTZ	تاریخ تولد
gender	STRING	جنسیت
maritial_status	STRING	وضعیت تأهل
children	INT	تعداد فرزندان
education	STRING	تحصیلات
title	STRING	عنوان
address	STRING	آدرس
city	STRING	شهر
state	STRING	استان
zipcode	STRING	کد پستی
country	STRING	کشور
phone	STRING	تلفن
job_position	STRING	موقعیت شغلی
company	STRING	شرکت
number_of_employees	INT	تعداد کارمندان
annual_revenue	INT	درآمد سالیانه
opt_in_sms	BOOL	رضایت برای پیامک (پیش‌فرض: true)
opt_in_email	BOOL	رضایت برای ایمیل (پیش‌فرض: true)
mobile	STRING	موبایل
last_active	TIMESTAMPTZ	آخرین فعالیت
updated_at	TIMESTAMPTZ	آخرین بروزرسانی
date_identified	TIMESTAMPTZ	تاریخ شناسایی (پیش‌فرض: NOW())
points	INT4	امتیاز (پیش‌فرض: 0)
device_type	STRING	نوع دستگاه
utm_source	STRING	منبع UTM

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

بررسی صحت اطلاعات ارسال‌شده

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

---

سوالات متداول (FAQ)

1. چگونه می‌توان یک کاربر جدید را ثبت کرد؟

برای ثبت کاربر جدید، باید درخواست API را با مقدار userId ارسال کنید. در صورتی که userId موجود نباشد، یک کاربر جدید ایجاد می‌شود.

2. آیا می‌توان اطلاعات کاربر را بعد از ارسال تغییر داد؟

بله، در صورتی که userId یا Anonymous ID در سیستم موجود باشد، ویژگی‌های جدید به‌روزرسانی خواهند شد.

3. چه نوع داده‌هایی را می‌توان در ویژگی‌های سفارشی ارسال کرد؟

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

4. چرا خطای 401 Unauthorized دریافت می‌کنم؟

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

5. آیا می‌توان هم userId و هم Anonymous ID را در یک درخواست ارسال کرد؟

بله، در این صورت سیستم پروفایل ناشناس را با userId ادغام می‌کند.

6. چرا نوع داده‌ی یک ویژگی سفارشی را نمی‌توان تغییر داد؟

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

7. اگر اطلاعاتی را به اشتباه ارسال کنم، آیا می‌توان آن را اصلاح کرد؟

بله، می‌توانید یک درخواست جدید با userId مشابه ارسال کرده و مقدار صحیح را در attributes قرار دهید.

8. چرا خطای 400 Bad Request دریافت می‌کنم؟

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

9. آیا مقدار attributes همیشه باید ارسال شود؟

بله، حتی اگر ویژگی سفارشی ندارید، باید attributes را به صورت {} ارسال کنید.

10. چگونه می‌توان صحت اطلاعات ارسال‌شده را بررسی کرد؟

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

---