توسعهدهندگان
Agent Purchase API
API لیدورا برای ساخت تجربه خرید لید داخل محصول شماست: احراز هویت Bearer، JSON، و مراحل صریح از Preview تا Export.
نمای کلی
Base URL
https://back.leadora.company/api/v1
Authentication
Authorization: Bearer <AGENT_API_TOKEN>
توکن از پنل ادمین برای نماینده صادر میشود و باید scopeهای لازم را داشته باشد.
API Overview
| مرحله | Method | Path |
|---|---|---|
| پروفایل | GET | /agent/profile |
| کاربر نهایی | POST | /users |
| پیشنمایش | POST | /leads/preview |
| Quote | POST | /leads/quote |
| سفارش | POST | /orders |
| پرداخت | POST | /orders/{order_id}/pay |
| ساخت Export | POST | /orders/{order_id}/exports |
| وضعیت Export | GET | /exports/{export_id} |
| دانلود | GET | /exports/{export_id}/download |
برای orders / pay / exports هدر Idempotency-Key اجباری است.
فیلتر لید
نمونه فیلدهای مجاز در filter: province_ids، city_ids، municipal_district_nos، postal_prefixes، gender، age_from/age_to، birth_year_from/to، mobile_operator_ids، mobile_prefixes، segment_ids.
فیلدهای حساس مانند نام، کد ملی و آدرس در این مسیر مجاز نیستند.
نمونه Request — Quote
curl -sS -X POST "$BASE_URL/leads/quote" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"user_id": "usr_XXXX",
"requested_count": 3000,
"filter": {
"city_ids": [371],
"gender": "male",
"age_from": 25,
"age_to": 40
}
}'نمونه Response
{
"quote": {
"id": "qt_XXXX",
"matched_count": 120000,
"requested_count": 3000,
"unit_price": 10000,
"subtotal_amount": 30000000,
"tax_amount": 2700000,
"total_amount": 32700000,
"expires_at": "2026-07-25T10:30:00Z",
"pricing_breakdown": {}
}
}مبالغ به ریال هستند. اعداد نمونه برای توضیح ساختار پاسخاند.
نمونه Request — Order
curl -sS -X POST "$BASE_URL/orders" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-cust1001-3000-1" \
-d '{ "quote_id": "qt_XXXX" }'نمونه Response
{
"order": {
"id": "ord_XXXX",
"status": "pending_payment"
}
}billing_mode
prepaid
موجودی کیف پول بررسی و مبلغ کسر میشود.
postpaid
در توافق خاص، کسر کیف پول انجام نمیشود و مصرف برای تسویه ثبت میگردد.
سوالات متداول توسعهدهندگان
توکن را از کجا بگیرم؟
پس از تأیید نمایندگی، توکن از پنل ادمین صادر میشود.
آیا API نسخهبندی شده است؟
بله؛ مسیر پایه /api/v1 است.
Idempotency-Key چه چیزی باید باشد؟
یک کلید یکتا برای همان عملیات منطقی تا retry تکراری ایجاد نکند.
Preview اجباری است؟
خیر؛ اما برای UX محصول توصیه میشود.
gender چه مقادیری دارد؟
male، female یا unknown.
آیا Webhook دارید؟
جریان اصلی روی request/response و استعلام وضعیت Export است؛ نیازهای event-driven در همکاری فنی بررسی میشود.
Rate limit چقدر است؟
سقفها در دسترسی نماینده و توافق فنی اعلام میشود.
خطاها چه فرمتی دارند؟
پاسخهای خطا JSON هستند؛ برای validation و وضعیتهای کسبوکاری کد/پیام مشخص برمیگردد.
آیا SDK رسمی دارید؟
در حال حاضر تمرکز روی HTTP JSON است؛ میتوانید client خود را بسازید.
مستندات کاملتر کجاست؟
پس از شروع همکاری، مستندات عملیاتی و مثالهای بیشتر در اختیار تیم فنی قرار میگیرد. این صفحه خلاصه عمومی API است.
دسترسی API میخواهید؟
درخواست همکاری نمایندگی را ارسال کنید تا onboarding فنی شروع شود.