المصادقة
يحمل كل طلب إلى API مفتاح API. ولا تُربط الطلبات أبدًا بجلسة متصفح.
إنشاء مفتاح API
أنشئ المفاتيح من مفاتيح API في حسابك، بحد أقصى 5. يمكنك نسخ المفتاح من تلك الصفحة في أي وقت ما دمت مسجّلًا الدخول: فنحن نحفظه مشفّرًا، ولا نعرضه إلا لك. أبقِه سريًا مثل كلمة المرور، وإذا كان من المحتمل أن أحدًا رآه، فألغِه وأنشئ مفتاحًا آخر.
إرسال مفتاح API
أرسله في ترويسة Authorization بكتابة Bearer متبوعة بالمفتاح. ويعمل X-API-Key أيضًا.
curl "https://api.talismanleads.io/v1/account" \
-H "Authorization: Bearer tl_live_your_key_here"ما يمكن لمفتاح API فعله
يمكن لمفتاح API الجديد فعل كل شيء: الاطلاع على رصيدك وأدوات الفحص وطلبياتك ونتائجها، واستخدام POST /uploads وPOST /estimates وPOST /orders، التي تخزّن قائمتك أو تنفق من رصيدك. أما مفتاح API الذي أُنشئ قبل 8 نوفمبر 2026 فقد يكون للقراءة فقط: يمكنه الاطلاع على كل شيء، لكن هذه الاستدعاءات الثلاثة ترفضه مع missing_scope.
انتهاء الصلاحية وعناوين IP
لا تنتهي صلاحية مفتاح API الجديد أبدًا، ويعمل من أي عنوان. أما مفتاح API الذي أُنشئ قبل 8 نوفمبر 2026 فقد يكون له تاريخ انتهاء صلاحية، يُرفض بعده مع expired_key، أو قد يكون مقصورًا على عناوين IP الخاصة بخادمك، فيُرفض أي طلب من مكان آخر مع ip_not_allowed. ولتغيير أيٍّ منهما، أنشئ مفتاحًا جديدًا وألغِ المفتاح القديم.
الحفاظ على أمان مفتاح API
- تعامل مع مفتاح API ككلمة مرور: كل من يحوزه يمكنه إنفاق رصيدك.
- استخدمه على خادمك فقط. لا تسمح API بالاستدعاءات من صفحة ويب.
- أبقِه خارج شيفرتك وخارج نظام التحكم في الإصدارات.
- إذا كان من المحتمل أن أحدًا رأى مفتاح API، فألغِه في حسابك فورًا. يتوقف عن العمل في الحال. وتستمر الطلبيات المقدَّمة مسبقًا في العمل.
- أرسله إلى API فقط. روابط الرفع والتنزيل تحمل إذنها الخاص، فلا ترسل مفتاح API إليها.
عند رفض مفتاح API
يُجاب بالرمز 401 عند استخدام مفتاح API خاطئ أو ملغى أو منتهي الصلاحية. ويُجاب بالرمز 403 عند حظر مفتاح API أو الحساب. راجع الأخطاء.