سير عمل API للتحقق من البريد الإلكتروني: من بيئة الاختبار إلى الإنتاج مع FairValid

سير عمل API للتحقق من البريد الإلكتروني: من اختبار بيئة الاختبار إلى نتائج الإنتاج

السؤال: أنت مطوّر تضيف التحقق من البريد الإلكتروني إلى نظامك الخاص. ما الخطوات التي تنقلك من أول استدعاء تجريبي إلى نتائج إنتاج موثوقة؟

الإجابة المختصرة: ابدأ بمفتاح Test وبيئة الاختبار المجانية. ثم انتقل إلى مفتاح Live لا يحمل إلا الصلاحيات التي تحتاجها. أرسل كل طلب مع مفتاح عدم تكرار. اقرأ حالة المهمة وتصفّح النتائج صفحةً تلو الأخرى. تعامل مع كل نتيجة وكل رمز خطأ على حدة. تتبع الخطوات أدناه مرجع API للعملاء من FairValid.

الخطوة 1: ابنِ التكامل على بيئة الاختبار أولًا

أنشئ مفتاح Test من صفحة مفاتيح API واحتفظ به على خادمك. يستخدم المرجع متغيري بيئة، هما FAIRVALID_API_KEY وFAIRVALID_BASE_URL. لا تُجري مفاتيح Test أي استدعاء لمزوّد الخدمة ولا تستهلك أي أرصدة.

لا تقبل مفاتيح Test إلا مجموعة صغيرة من العناوين المحجوزة على النطاق example.com. تحاكي هذه العناوين النتائج: صالح، وغير صالح، وعنوان شامل، وغير معروف، وقيد الانتظار، وغير متاح. ستجد العناوين بدقة في قسم "بيئة الاختبار المجانية" ضمن مرجع API. تُرجع المهام التجريبية حالات ثابتة وقابلة للتكرار: مكتملة، أو قيد الانتظار، أو فاشلة، أو ملغاة. تدعم المهام التجريبية المجمّعة الاستعلام عن الحالة والنتائج والإلغاء.

تعرض لك بيئة الاختبار هذه النتائج المحددة. لكنها لا تغطي كل المسارات التي قد يسلكها تكاملك، لذا خطّط لمعالجة منفصلة لرموز الأخطاء الموضحة في الخطوة 7.

تقتصر المهام التجريبية المجمّعة على 20 مهمة جديدة لكل مساحة عمل في الساعة، أو 100 مهمة لكل 30 يومًا. ويؤدي تجاوز أيٍّ من الحدّين إلى إرجاع HTTP 429. أما إعادة المحاولة المطابقة فتظل تُرجع المهمة الأصلية.

الخطوة 2: انتقل إلى مفتاح Live بالصلاحيات التي تحتاجها

للإنتاج، أنشئ مفتاح Live بصلاحية الإرسال. استخدم POST /api/v1/jobs للدفعات أو POST /api/v1/verifications لعنوان واحد. أضف صلاحية القراءة إذا كان المفتاح يحتاج أيضًا إلى قراءة حالة المهمة ونتائجها. ويمكن أن تحمل مفاتيح Live كذلك صلاحية الرصيد. وبشكل منفصل، يقرأ GET /api/v1/balance الأرصدة المتاحة والمحجوزة في مساحة العمل. لا يُعرض السر الكامل إلا مرة واحدة، لذا احفظه بأمان عند إنشاء المفتاح.

تستخدم مهام Live قائمة انتظار التحقق ورصيد الأرصدة في مساحة عملك. وتظل صلاحيات المفاتيح وحدودها القصوى وصلاحيات الوصول إلى مساحة العمل وحدود المعالجة سارية جميعها.

الخطوة 3: أرسل مهمة مع مفتاح عدم تكرار

تقبل المهمة من 1 إلى 5,000 عنوان بصيغة JSON، بحجم أقصاه 2 ميبيبايت. أرسل ترويسة Idempotency-Key مع كل إرسال لمهمة ومع كل إرسال مباشر لعنوان واحد. يجب أن يتراوح طول المفتاح بين 8 و128 حرفًا، ويمكن أن يتضمن حروفًا وأرقامًا ونقاطًا ونقطتين رأسيتين وشرطات سفلية أو واصلات.

• تُرجع المهمة الجديدة HTTP 202 مع معرّف job_id بصيغة UUID.
• تُرجع إعادة المحاولة المطابقة HTTP 200 مع المهمة نفسها.
• تؤدي إعادة استخدام مفتاح عدم التكرار مع نص طلب مُعدَّل إلى إرجاع HTTP 409 idempotency_conflict.

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

الخطوة 4: اقرأ المهمة وتصفّح النتائج صفحةً تلو الأخرى

اقرأ المهمة باستخدام GET /api/v1/jobs/{id}. قد تكون حالتها: في قائمة الانتظار، أو قيد التشغيل، أو متوقفة مؤقتًا، أو قيد الإلغاء، أو ملغاة، أو مكتملة. اقرأ النتائج باستخدام GET /api/v1/jobs/{id}/results. تُرجع كل صفحة ما يصل إلى 50 نتيجة إضافةً إلى next_cursor موقّع. مرّر هذه القيمة بوصفها معامل الاستعلام cursor. وهي تحافظ على عامل التصفية والبحث الأصليين.

عوامل التصفية هي all وvalid وinvalid وcatch_all وunknown وstill_checking وnot_checked. لإيقاف مهمة، يطلب POST /api/v1/jobs/{id}/cancel الإلغاء، لكن العمل الجاري بالفعل قد يكتمل رغم ذلك.

يصف المرجع أيضًا حدث اكتمال موقّعًا ويتضمن روابط إلى إدارة خطافات الويب.

الخطوة 5: تعامل مع كل نتيجة بوصفها حالة مستقلة

يشرح دليل النتائج معنى كل نتيجة:

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

يصف الدليل حالات الإخفاق التقني والعناصر غير المعالجة بشكل منفصل عن حالة غير معروف، وتوفّر API عوامل التصفية unknown وstill_checking وnot_checked بشكل منفصل. احتفظ بهذه الحالات في حقول أو حالات منفصلة ضمن بياناتك بدلًا من دمجها في حالة غير معروف.

الخطوة 6: افهم حجوزات الأرصدة قبل المطابقة

يذكر مرجع API أن أرصدة مساحة العمل تُحجز عند قبول عمليات الفحص للمعالجة. ثم تخضع النتائج لقواعد الاحتساب والإرجاع نفسها المتبعة في لوحة التحكم. وتذكر صفحة أسعار FairValid أن حجز الأرصدة يُبقي مساحة لعملية فحص جارية، وأن النتيجة النهائية هي التي تحدد الرسوم:

• صالح أو غير صالح: 1 رصيد لكل نتيجة مكتملة.
• غير معروف أو عنوان شامل: لا تُخصم أي أرصدة تحقق في المحصلة. تُحرَّر الأرصدة المحجوزة أو تُعاد.
• لا يزال قيد الفحص: لا يوجد خصم نهائي بعد. الحجز ليس خصمًا مكتملًا.
• حالات الإخفاق التقني والعمل غير المعالج: لا تُخصم أي أرصدة تحقق في المحصلة. تُحرَّر الحجوزات أو تُعاد.

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

الخطوة 7: تعامل مع الأخطاء بحسب سببها، لا بقاعدة إعادة محاولة واحدة

• 401: المفتاح مفقود أو ملغى أو يفتقر إلى الصلاحية المطلوبة. أصلح بيانات الاعتماد أو صلاحياتها.
• 402 key_cap_reached: سيتجاوز الطلب الجديد الحد الأقصى الإجمالي للمفتاح طوال عمره، ولم تُنشأ أي مهمة أو حجز. يحتسب هذا الحد الأرصدة المخصومة بالفعل إضافةً إلى الأرصدة المحجوزة للهويات الفريدة المقبولة. ولأنه حد إجمالي طوال عمر المفتاح، فإنه لا يتجدد مع مرور الوقت، والانتظار لن يزيله. اطلب من شخص يملك صلاحية الوصول مراجعة إعداد الحد الأقصى لهذا المفتاح. ولا يمكن للحد الأقصى أن يضيف أرصدة إلى مساحة العمل.
• 422: عناوين غير صالحة أو تجاوز حدود القائمة. صحّح المدخلات.
• 503 live_verification_unavailable: أثناء توقف تشغيلي مؤقت، قد يُرجع إرسال مباشر جديد هذا الخطأ دون حجز أي أرصدة. أعد المحاولة لاحقًا بمفتاح عدم التكرار نفسه. ولا يُثبت الخطأ 503 بعد إرسال غير مؤكد أنه لم تُنشأ أي مهمة، لذا أعد استخدام المفتاح الأصلي.

يتضمن كل خطأ رمزًا ورسالة ومعرّف طلب. سجّل الثلاثة جميعًا لتكون متاحة لديك إذا تواصلت مع الدعم.

ترتيب منطقي للعمل

1. ابنِ التكامل على بيئة الاختبار وتأكد من أن كل نتيجة محاكاة تنتهي حيث تتوقع.
2. أضف معالجة صريحة لرموز الأخطاء المذكورة أعلاه.
3. أنشئ مفتاح Live بأضيق الصلاحيات التي تحتاجها وبحد أقصى يناسب ميزانيتك.
4. ابدأ بمهمة مباشرة صغيرة. قارن نتائجها وحالات أرصدتها بلوحة التحكم، ثم توسّع تدريجيًا.

إذا أردت تجربة سير العمل هذا، فإن بيئة الاختبار المجانية تتيح لك اختبار النتائج المحاكاة دون استهلاك أي أرصدة. ويتضمن مرجع API تفاصيل الطلبات بدقة.