واجهة API: تسيير طلبيات COD من الكود الخاص بك

فيما تنفع الـAPI، ومتى لا تنفع في شيء

الـAPI تجيب على ثلاث حالات، وتقريبا على ثلاث فقط. الأولى هي متجر مبني خصيصا: في اللحظة التي يؤكد فيها الزبون سلته، يُنشئ كودك الليد ويتلقى مرجعه في الحين، فيُظهره للزبون. والثانية هي تطبيق هاتف، لأنه ليس له صفحة ويب تُنادى. والثالثة هي أداة داخلية — لوحة، أو مطابقة حسابية، أو سكريبت تقارير — تحتاج قراءة حالة الطلبيات لتجمعها مع معطياتها الخاصة.

وخارج هذه الحالات الثلاث لا تنفع كثيرا، ومن الأفضل قول ذلك قبل أن يُضيّع أحد أسبوعا فيها. فإذا كانت طلبياتك تأتي من متجر موجود، فربط المتجر يُدخلها بدون كود ومع قراءة احتياطية لم تكن ستكتبها بنفسك. وإذا كانت تأتي من استمارة أو صفحة هبوط، فملف الحسابات أسرع في التركيب وأسهل في التصحيح. وإذا كنت تريد فقط أن تُخبَر عند توصيل طلبية، فما تحتاجه هو webhook صادر، لا حلقة من النداءات على الـAPI.

والقاعدة المفيدة هي هذه: الـAPI مبرَّرة عندما يكون برنامج تتحكم فيه هو من يُنتج الطلبية. وفي جميع الحالات الأخرى، واحدة من الطرق الثلاث الأخرى تقوم بنفس العمل بمجهود أقل وصيانة أقل.

مفتاح API وما يساويه

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

والمفتاح يُنشأ من فضاء البائع، باسم يقول فيما يُستعمل. ويُعرض مرة واحدة فقط عند إنشائه: فلا تُحفظ إلا بصمته، ولا أحد — ولا حتى الدعم — يقدر يُعيد قراءته لك. فإذا فُقد يُنشأ آخر. وإذا سُحب فلا يعود صحيحا أبدا.

• مفتاح لكل تكامل — مفتاح لتطبيق الهاتف، وآخر لسكريبت التقارير. وسحب أحدهما لا يوقف الآخر، وسجل النداءات يقول من فعل ماذا.
• المفتاح يمكن أن يُربط بمتجر — وحينها تحمل الليدات المُنشأة بهذا المفتاح المتجر المقابل تلقائيا، دون أن يُضطر كودك إلى ذكره.
• المفتاح سر خاص بالسيرفور — ولا يجب أبدا أن يخرج في صفحة ويب، أو تطبيق هاتف موزّع، أو مستودع كود: فكل من يقرأه يقدر ينشئ طلبيات باسمك.
• آخر استعمال ظاهر — والمفتاح الذي لم يُستعمل منذ مدة طويلة هو مفتاح يجب سحبه.
• سجل النداءات ملك لك — الطريقة، والعنوان المُنادى، ورمز الجواب: وهذا ما يُجيب عن «علاش ماشي خدام» بدون تخمين.

ما يُقرأ وما يُكتب وما لا يُمسّ

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

• جوابان محتملان عند الإنشاء — الليد المقبول يُجيب «أُنشئ». والليد المشكوك فيه — مرجع غير معروف، أو مدينة غير معروفة، أو مبلغ غير منطقي، أو تكرار حديث — يُجيب «قُبل» مع لائحة الملاحظات: فهو موجود، كليد معطوب، وينتظر تصحيحا. ولا يُرفض أبدا في صمت.
• تصفيح بالمؤشر — لائحة الليدات تُقرأ بإعادة المعرّف الذي أرجعته الصفحة السابقة، لا برقم صفحة. فرقم الصفحة يتزحزح عند كل ليد جديد، ويتجاوز التكامل طلبيات دون أن يلاحظ.
• مرجعك الخاص يُحفظ — حقل المرجع الخارجي يُنقل كما هو ويُعرض من جديد في الواجهة: وهذا ما يسمح بمطابقة ليد مع الطلبية الأصلية في نظامك.
• ما لا تفعله الـAPI — لا تُغيّر حالة، ولا تُلغي طلبية، ولا تُطلق سحبا، ولا تقرأ أي شيء يخص بائعا آخر. فهذه الأفعال موجودة في الواجهة، حيث تُترك آثارها.

حدود النداءات ورموز الأخطاء

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

وعندما يُبلَغ الحد، يقول الجواب ذلك بصراحة ويُبيّن المدة التي يجب انتظارها. والعميل المكتوب بشكل صحيح يحترم هذه المدة بدل أن يُعيد في الحين؛ فالإعادة الفورية لا تفعل شيئا سوى استهلاك الدقيقة الموالية.

أين يوجد المرجع الكامل

هذه الصفحة تشرح فيما تنفع الـAPI وما تسمح به؛ وهي لا تعوّض المرجع. والمرجع يوجد في توثيق المطورين، وهو عمومي ولا يطلب أي حساب — فمبرمج البائع لا يملك معرّفات دخوله، وطلب التسجيل لقراءة عقد API لا يحمي شيئا.

وتجد فيه دليل الانطلاق، ومرجع العناوين بكل الحقول المنتظرة، وصفحة الـwebhooks الصادرة، ولائحة الأخطاء والحدود، وسجل الإصدارات. والوصف مكتوب مرة واحدة ويخدم كل شيء: الصفحة التي يقرأها إنسان، وملف OpenAPI تستورده أداتك لتوليد عميل، ومجموعة جاهزة للتجربة. وهذا ما يضمن أن الصفحة والملف لا يقولان شيئين مختلفين بعد ستة أشهر.

ورقم إصدار الـAPI يُرجَع في ترويسة كل جواب، وسجل الإصدارات يقول ما تغيّر. وإضافة الحقول أمر عادي ولا يُكسر شيئا: فالعميل المكتوب جيدا يتجاهل حقلا لا يعرفه بدل أن يفشل عنده.