مرجع api / leads/get-records/
دریافت سرنخ‌های پولی
سرنخ‌های مطابق با فیلتر، همراه با فیلدهای درخواست‌شده، صفحه‌بندی شده برمی‌گرداند. این اندپوینت پولی است و هزینه فقط برای ترکیبات (lead_id, field) جدید کسر می‌شود.
leads/get-records/سرنخ‌های مطابق با مجموعه فیلتر را همراه با فیلدهای درخواست‌شده، صفحه‌بندی شده برمی‌گرداند. این تنها endpoint پولی در سطح api عمومی است و هزینه دقیقاً برای ترکیبات (lead_id, field) جدید کسر می‌شود — موارد قبلاً خریداری‌شده رایگان برمی‌گردند (حذف خودکار تکرار).
هدرها
X-API-KEYstringبلهکلید api شما. هزینه از کیف‌پول دارنده همین کلید کسر می‌شود.
Content-Typestringبلهapplication/jsonباید برابر application/json باشد.
بدنه درخواست
filtersFilter[]بلهآرایه فیلترها با ساختار { key, operand, value }. مشابه leads/get-count/.
requested_fieldsstring[]بلهحداقل یک فیلد قابل خرید: زیرمجموعه‌ای از { phone, email, owner_name, owner_national_id }. آرایه خالی یا فاقد فیلد قابل خرید موجب خطای 400 می‌شود.
idempotency_keystringبلهUUID یکتا برای هر «نیت کاربر» (نه برای هر تلاش http). در صورت تلاش مجدد همان درخواست، از همان کلید استفاده کنید — سرور نتیجه تراکنش قبلی را برمی‌گرداند و کیف‌پول را دو بار کسر نمی‌کند.
pageinteger1شماره صفحه. صفحه‌بندی همان فیلترها برای ترکیبات قبلاً خریداری‌شده رایگان است.
limitinteger50تعداد سرنخ در هر صفحه.
requesting_userstringشماره تلفن ایران کاربر نهایی که این کمپین به نام او ثبت می‌شود. در صورت عدم وجود، حسابی به‌صورت خودکار ساخته می‌شود (قابل ادعا توسط همان کاربر بعداً).
campaign_idstringشناسه آزاد کمپین (حداکثر ۲۵۵ کاراکتر). در صورت ارسال requesting_user الزامی است؛ این کاربر کمپین را در داشبورد خود می‌بیند.
نمونه درخواست
curl -X POST 'https://www.saravar.com/api/leads/get-records/' \-H 'X-API-KEY: <YOUR_API_KEY>' \-H 'Content-Type: application/json' \-d '{"filters": [{ "key": "city_of_residence", "operand": "in", "value": [1, 5] },{ "key": "gender", "operand": "equals", "value": 2 }],"requested_fields": ["phone"],"idempotency_key": "550e8400-e29b-41d4-a716-446655440000","page": 1,"limit": 50}'
پاسخ
countintegerبلهتعداد کل سرنخ‌های مطابق با فیلتر (نه فقط صفحه فعلی).
previousbooleanبلهآیا صفحه قبلی وجود دارد؟
nextbooleanبلهآیا صفحه بعدی وجود دارد؟
debit_transaction_idintegerبلهشناسه تراکنش کسر اعتبار. در داشبورد قابل ردگیری است.
total_chargedstringبلهمبلغ کسر شده بر حسب IRR. اگر تمام ترکیبات (lead_id, field) قبلاً برای این کلید خریداری شده‌اند، مقدار "0" خواهد بود.
resultsLead[]بلهآرایه سرنخ‌ها. هر شیء شامل lead_id، lead_type ("phonenumber" یا "email")، lead_data (مقدار اصلی، فقط در صورت خرید)، و فیلدهای درخواست‌شده (در صورت عدم خرید مقدار null).
نکات قیمت‌گذاری و رفتار
- هزینه از کیف‌پول دارنده کلید (X-API-KEY) کسر می‌شود — نه از requesting_user.
- حذف تکرار: ترکیبات (lead_id, field) که قبلاً برای دارنده کلید خریداری شده‌اند، در فراخوانی‌های بعدی رایگان برمی‌گردند و در total_charged لحاظ نمی‌شوند. این یعنی صفحه‌بندی نتایج همان فیلتر هزینه دوباره ندارد.
- اگر requesting_user و campaign_id ارسال شوند، آن کاربر کمپین را در بخش «کمپین‌های همکار» داشبورد خود می‌بیند بدون اینکه چیزی پرداخت کند.
- برای جلوگیری از پرداخت دوگانه در قطعی شبکه، idempotency_key را در پایگاه داده محلی خود ذخیره کنید و در تلاش مجدد همان را ارسال کنید — UUID جدید فقط برای نیت کاربری جدید بسازید.
خطاها
400کد وضعیت401کد وضعیت409کد وضعیت429کد وضعیت