تقديم الطلبيات

1. اختر أداة فحصCopy Anchor Link

يعرض GET /checkers ما يمكن لحسابك طلبه، بأسعارك. لكل أداة id، مثل whatsapp_status_detection، وتقبل هواتف أو عناوين بريد إلكتروني أو أسماء مستخدمين. راجع أدوات الفحص.

curl "https://api.talismanleads.io/v1/checkers" \
  -H "Authorization: Bearer tl_live_your_key_here"

2. أرسل قائمتكCopy Anchor Link

ضع ما يصل إلى 100,000 إدخال و4 MB داخل الطلب في entries. للقائمة الأكبر، اطلب رابطًا من POST /uploads، وأرسل الملف إلى ذلك الرابط باستخدام PUT، ثم استخدم upload_id الخاص به. يبقى الرابط صالحًا ساعتين. لا ترسل مفتاح API إليه.

• الملف بصيغة .txt وفيه إدخال واحد في كل سطر، حتى 200 MB و10,000,000 إدخال.
• اكتب أرقام الهواتف مع رمز البلد، مثل +14155550142.
• ينبغي أن تكون أرقام الهواتف في الملف الواحد من بلد واحد: 90% منها على الأقل. قسّم القائمة المختلطة إلى ملف لكل بلد.
• سطر واحد غير صالح يؤدي إلى رفض القائمة كلها، وتعرض الاستجابة أمثلة.
• ينتظر الملف المرفوع طلبية لمدة 24 ساعة، ثم يُحذف.
• يمكن أن يكون لديك 20 ملفًا أو 100 MB قيد الانتظار في وقت واحد، مهما كان عدد مفاتيح API التي تستخدمها، و500 عملية رفع في اليوم. ويمكن إضافة ملف واحد بأي حجم مسموح به فوق ذلك ما دمت دون هذه الحدود.

اطلب رابطًا

curl -X POST "https://api.talismanleads.io/v1/uploads" \
  -H "Authorization: Bearer tl_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"file_name":"list.txt","size_bytes":1048576}'

أرسل الملف إليه

UPLOAD_URL="PASTE_upload_url_FROM_THE_ANSWER_ABOVE"
curl --upload-file list.txt "$UPLOAD_URL" \
  -H "Content-Type: text/plain" \
  -w "%{http_code}\n"

3. اطّلع على السعرCopy Anchor Link

يعدّ POST /estimates الإدخالات ويحسب السعر، ولا يخصم أي مبلغ. قد يكون billed_entries أكبر من entries، لأن كل ملف يُحتسب على أساس 2,000 على الأقل.

curl -X POST "https://api.talismanleads.io/v1/estimates" \
  -H "Authorization: Bearer tl_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"checker":"whatsapp_status_detection","entries":["+14155550142","+12125550187"]}'

4. قدّم الطلبيةCopy Anchor Link

يخصم POST /orders من رصيدك ويضع العمل في قائمة الانتظار. أرسل Idempotency-Key حتى لا يمكن لإعادة المحاولة أن تخصم منك مرتين: راجع إعادة المحاولة بأمان. لتتأكد من السعر، أرسل expected_charge، وستُرفض الطلبية مع price_changed إذا كانت تكلفتها أي مبلغ آخر. اترك ما يصل إلى 5 دقائق لوصول الاستجابة، فقراءة القائمة الكبيرة تستغرق وقتًا.

curl -X POST "https://api.talismanleads.io/v1/orders" \
  -H "Authorization: Bearer tl_live_your_key_here" \
  -H "Idempotency-Key: crm-export-2026-11-05" \
  -H "Content-Type: application/json" \
  -d '{"checker":"whatsapp_status_detection","entries":["+14155550142","+12125550187"]}'

5. تابع حالتهاCopy Anchor Link

استدعِ GET /orders/{id} كل 30 ثانية أو أكثر. يُقسَّم الملف الكبير إلى أجزاء في الخلفية، لكن للطلبية حالة واحدة وإجمالي واحد.

queued

بانتظار البدء.

processing

قيد التشغيل.

completed

انتهت، واكتمل كل جزء.

partially_completed

انتهت، مع فشل بعض الأجزاء. يُردّ مبلغ تلك الأجزاء: يعرض `refunded` ما أُعيد.

failed

تعذّر تنفيذ أي جزء. يُردّ المبلغ المخصوم: يعرض `refunded` ما أُعيد.

قد تُضاف حالات أخرى، لذا اعتبر أي حالة لا تعرفها قيد التشغيل.

curl "https://api.talismanleads.io/v1/orders/ord_8f2c1e7a-3b4d-4c5e-9f60-1a2b3c4d5e6f" \
  -H "Authorization: Bearer tl_live_your_key_here"

6. احصل على النتيجةCopy Anchor Link

يعطيك GET /orders/{id}/results رابط تنزيل لكل جزء، صالحًا لمدة 15 دقيقة. اطلب رابطًا جديدًا في أي وقت: فالنتائج محفوظة. عادةً ما يكون الملف بصيغة zip يضم all.csv وجدول بيانات وقوائم نصية، أو ملف CSV واحدًا. قد تُضاف أعمدة، فاقرأها بالاسم لا بالموضع. لا ترسل مفتاح API إلى هذه الروابط.

curl "https://api.talismanleads.io/v1/orders/ord_8f2c1e7a-3b4d-4c5e-9f60-1a2b3c4d5e6f/results" \
  -H "Authorization: Bearer tl_live_your_key_here"

المبالغ المخصومة والمردودةCopy Anchor Link

charge هو تكلفة الطلبية عند تقديمها، وrefunded هو ما أُعيد منها. يُردّ مبلغ الجزء الذي يفشل كاملًا، ويُعاد الفرق عن الجزء الذي احتسب له المزوّد عددًا أقل، وصولًا إلى الحد الأدنى الذي يُحتسب به ذلك الجزء. ويحدث كلاهما تلقائيًا.

القائمة نفسها على أداة الفحص نفسها خلال نحو يوم، بمفتاح Idempotency-Key جديد، يُخصم مبلغها مجددًا كطلبية جديدة، وقد تُعيد نتيجتك السابقة بدلًا من فحص جديد.

الطلبيات من أماكن أخرىCopy Anchor Link

تظهر أيضًا الطلبيات التي تقدمها على الموقع. وتظهر طلبيات API في مهامي على الموقع مع شارة API، ولا ترسل شيئًا إلى Telegram إلا إذا طلبت ذلك هناك.