أدير Prisma Reviews، وهي واجهة API صغيرة تُعيد تقييمات العملاء من 84 منصةً بصيغة JSON واحدة موحّدة. هذه المقالة ليست عن المنتج نفسه، بل عن ثلاث مشكلات هندسية استهلكت معظم وقتنا: تصميم مخطط (schema) يتلاءم مع مصادر تختلف أشكالها اختلافًا كبيرًا، وضمان ثبات المعرّفات (IDs) حتى لا تظهر التقييم الواحد مرتين أبدًا، واختبار العقد (contract) بحيث لا يؤدي أي تغيير في المنبع إلى تعطيل العملاء في المصبّ بصمت.
أمر واحد أولًا، لأنه يحدد شكل كل ما سيأتي: ليس كل مصدر تقييمات هو واجهة API. من بين مصادرنا البالغة 84، هناك 59 لديها واجهة API رسمية. أما الـ 25 الباقية فلا، ونقرأ صفحاتها العامة أو موجباتها (feeds) بدلًا من ذلك.
ليس كل مصدر هو واجهة API
كل منصة في إعداداتنا لديها ثلاث خصائص: كيف يربطها صاحب العمل، وهل يمكننا نشر ردّ، وكيف تصلنا التقييمات الجديدة. وبترتيب المصادر الـ 84 حسب طريقة قراءتها نحصل على أربع مجموعات:
| المجموعة | المصادر | أمثلة |
|---|---|---|
| واجهة API رسمية ببيانات اعتماد صاحب العمل نفسه أو عبر OAuth | 50 | Google Business Profile (الوصول قيد الانتظار)، App Store، Google Play، Trustpilot (الوصول قيد الانتظار)، Judge.me، Yotpo، eBay، Wix، WooCommerce، Shopware، ومديرو عقارات مثل Hostaway وGuesty |
| واجهة API عامة رسمية دون بيانات اعتماد صاحب العمل | 9 | Steam، Etsy، Salesforce AppExchange، Atlassian Marketplace، VS Code Marketplace، Open VSX، JetBrains Marketplace، Thunderbird Add-ons، Viator |
| بدون واجهة API: صفحة عامة أو موجب (feed) | 3 | Shopify App Store (صفحة تقييمات HTML)، WordPress.org (موجب تقييمات RSS)، Apple Podcasts (موجب تقييمات عام) |
| بدون واجهة API: مزوّد بيانات مدفوع | 22 | Google Maps، Yelp، Tripadvisor، Booking.com، Facebook، Airbnb، Expedia، Capterra، OpenTable |
تختلف هذه المجموعات بطرق تنعكس على تصميم الـ API:
- المصادقة. المجموعة الأولى تتطلب تدفّق OAuth أو مفتاحًا يلصقه صاحب العمل. أما المجموعات الثلاث الأخرى فتحتاج فقط إلى الرابط العام لصفحة القائمة (listing).
- الردود. فقط 25 من أصل 84 مصدرًا تسمح لطرف ثالث بنشر ردّ، واثنان منها، وهما Google Business Profile وTrustpilot، ما زالا بانتظار موافقة المنصة على وصولنا. وجود واجهة API ليس كافيًا: فنقطة نهاية الردود لدى Atlassian تجيب الآن بـ
410 API_DEPRECATED، كما أن واجهة الردود في Microsoft Store معطّلة من جهة Microsoft نفسها، لذا فكلاهما للقراءة فقط. - التكلفة والوتيرة. الواجهات الرسمية لا تكلفنا شيئًا لكل استدعاء، لذا نفحصها كثيرًا. أما القراءة عبر مزوّد بيانات فتُحتسب لكل تقييم، وبعض المزوّدين يفرضون رسومًا عن كل تشغيل على كل ما هو جديد، لذا تُفحص تلك المصادر مرة واحدة يوميًا.
- لماذا لا توجد واجهة API. واجهة الشركاء لدى Expedia مع الردود مفتوحة فقط لمديري القنوات الكاملين، وقد رفضت طلبنا. أما واجهة Airbnb فهي بالدعوة فقط. وShopify ليس لديها واجهة API للتقييمات؛ فمطوّرو التطبيقات يردّون من لوحة التحكم الخاصة بهم.
بعض المنصات تظهر مرتين. فتقييمات Airbnb وBooking.com قد تأتي من صفحة عامة (قراءة فقط)، أو عبر واجهة API رسمية لمدير عقارات، وهي تسمح بالردود. وهذا هو سبب وجود أحد الحقول أدناه.
مخطط واحد للجميع
كل تقييم، من كل مصدر، لديه الحقول الـ 14 نفسها، وكلها موجودة دائمًا. فعندما لا تمنحنا المنصة شيئًا، تكون قيمة الحقل null، ولا يكون الحقل غائبًا أبدًا. فالحقل المفقود والقيمة null يعنيان الشيء نفسه للبشر، لكنهما مختلفان بالنسبة لعميل مكتوب بأنواع صارمة (typed client)، كما أن شرط "موجود دائمًا" سهل الاختبار.
{ "id": "rev_01KJ8Q2M4T7HX3VB9CWD6NRZ5E", "platform": "google", "location_id": "loc_01KJ8P9W2C4D6F8G0H2J4K6M8N", "rating": 4, "title": null, "text": "Great flat white, a bit slow at lunchtime.", "author": "Marta G.", "language": "en", "url": null, "source": null, "created_at": "2026-10-19T12:41:07.000Z", "updated_at": "2026-10-19T12:41:07.000Z", "deleted_at": null, "reply": null } الحقل rating عدد صحيح من 1 إلى 5، أو null. فBooking.com تعطي درجات من 10، لذا نقسم على اثنين ونقرّب ونحدّ النطاق إلى 1-5. وSteam لا لديها نجوم، بل فقط "مُوصى به" أو "غير مُوصى به"، ونحن نربطهما بالقيمتين 5 و1. وبعض المصادر تسمح بتقييم بلا درجة على الإطلاق، وعندها يكون الحقل null. نحن لا نكتب أبدًا القيمة 0: فهي تبدو كدرجة حقيقية وتخفض المتوسطات.
الحقلان text وtitle يمكن أن يكونا null. فالتقييمات المكونة من درجة فقط شائعة في متاجر التطبيقات، وبعض المنصات فقط لديها عناوين. ولا نخترع عنوانًا من الجملة الأولى.
الحقل url له معنى محدد على المنصات للقراءة فقط. فعندما لا نستطيع نشر ردّ، يكون url هو المكان الذي يستطيع فيه صاحب العمل الردّ يدويًا. وإذا حاول عميل الردّ رغم ذلك، يحمل الخطأ الرابط نفسه.
الحقل source موجود بسبب المُجمِّعات (aggregators). فعلى سبيل المثال، تعيد Viator تقييمات كُتبت على Viator وعلى Tripadvisor. ومدير العقارات يعيد تقييمات Airbnb وBooking.com وVrbo عبر اتصال واحد. ويحدد حقل platform الاتصال الذي جاء منه التقييم؛ بينما يحدد حقل source الموقع الذي كُتب عليه.
الحقلان created_at وupdated_at منفصلان لأن الناس يعدّلون تقييماتهم. فتقييم بنجمة واحدة تم تعديله ليصبح أربع نجوم يجب أن يكون تحديثًا، لا صفًا جديدًا.
الحقل reply كائن له حالة، وليس سلسلة نصية. والحالة هي إما published أو queued أو failed أو unknown. والحالة الأخيرة تحتاج إلى توضيح. فأحيانًا يُرسل الطلب إلى المنصة ولا يعود أي جواب، والمنصة ليس لديها وسيلة لقراءة الردّ مرة أخرى. وإعادة المحاولة قد تنشر الردّ نفسه مرتين، وذلك باسم صاحب العمل. لذا نتوقف، ونضع الحالة unknown، ونطلب من العميل التحقق من المنصة قبل النشر مرة أخرى. فالحالة التي تقول "لا نعرف" أنفع من التخمين.
وتُفحص حدود طول الردّ لكل منصة قبل إضافته إلى قائمة الانتظار: 4096 بايت على Google Business Profile، و350 حرفًا على Google Play، و80 على eBay. فالإيموجي حرف واحد لكنه أربعة بايتات، لذا نحتس الوحدات (code points) لحدود الأحرف والبايتات لحدود البايتات.
المعرّفات الثابتة وإزالة التكرار
التكرارات هي الخلل الذي يلاحظه العملاء أولًا. قاعدتنا بسيطة: يجب أن يعيد كل موصل (connector) المعرّف الخاص بالمنصة لكل تقييم، وقاعدة البيانات لديها فهرس فريد على (location_id, external_id). فالمزامنة الثانية للتقييم نفسه هي تحديث، وليست إدراجًا أبدًا. وتعمل المواقع بالطريقة نفسها، بفهرس فريد على (connection_id, external_id).
أما الجزء الصعب فهو أن "المعرّف الخاص بالمنصة" ليس موجودًا دائمًا:
- تقييمات Etsy ليس لها معرّف خاص بها. فكل تقييم يتبع معاملة واحدة بالضبط، لذا يكون معرّف المعاملة هو معرّف التقييم.
- WordPress.org لا يعطي معرّف تقييم في موجبه. وكل تقييم هو موضوع في منتدى، لذا نستخدم المعرّف النصي للموضوع (slug).
- صفحة Shopify App Store تحمل معرّف محتوى التقييم داخل HTML الخاصة بها. ونعتمد عليه، علمًا بأن إعادة تصميم الصفحة قد تغيّره.
- Google Play لديه معرّفات حقيقية، لكن واجهته تعيد فقط التقييمات التي أُنشئت أو عُدّلت خلال الأيام السبعة الأخيرة. فالسجل المخزّن هو سجلنا، ولا نستطيع إعادة قراءته.
العملاء لا يرون معرّفات المنصات أبدًا كمفاتيح أساسية. فهم يحصلون على معرّفاتنا الخاصة ببادئة نوع وجسم مرتب زمنيًا (rev_01KJ…، loc_01KJ…، req_01KJ…). فالبادئة تجعل المعرّف الموضوع في المكان الخطأ واضحًا في السجلات، كما أن الترتيب يساعد في التقسيم إلى صفحات: إذ يُضمّن المؤشر (cursor) الطابع الزمني والمعرّف الخاص بآخر عنصر، فيبقى حد الصفحة ثابتًا في حين تصل تقييمات جديدة.
إعادة الربط. يفصل صاحب عمل حسابًا ثم يعيد ربطه بعد أسبوع. فإنشاء مواقع جديدة سيكرّر كل تقييم. وبدلًا من ذلك، يُعاد تنشيط الموقع الذي فُصل قبل أقل من 30 يومًا ويحمل المعرّف الخارجي نفسه: معرّفات ذاتها، ولا تقييمات مكرّرة.
الحذف. التقييم الذي يُزال من المنصة يختفي ببساطة، ولا شيء يخبرك بذلك. فعند 60 من أصل 84 مصدرًا نستطيع قراءة السجل الكامل، لذا نعيد قراءته دوريًا (كل 25 يومًا في حالة Google Business Profile، إذ لا تسمح شروطها بالاحتفاظ بمحتوى غير مؤكد لأكثر من 30 يومًا؛ وأسبوعيًا لمعظم الآخرين) ونضع على التقييمات التي لم تعد المنصة تعيدها علامة deleted_at، مع إرسال webhook باسم review.deleted. والضمانة الأساسية: إذا توقفت القراءة مبكرًا، بسبب مهلة انتهاء أو حد للصفحات، لا نضع أي علامة. فمعاملة "لم أره" على أنها "لقد حُذف" ستحذف تقييمات حقيقية. ويُستثنى Google Play بسبب نافذته التي تبلغ سبعة أيام.
اختبار العقد مقابل مواصفة OpenAPI
العقد عبارة عن مستند OpenAPI 3.1 يضم 18 مسارًا و30 مخططًا و9 أحداث webhook. ونوعان من الاختبارات يحافظان على صدقه.
الأول رخيص ويعمل عند كل إيداع (commit): يجب أن تتطابق قوائم التعداد (enums) في المواصفة مع الشيفرة تمامًا. فيجب أن تساوي معرّفات المنصات في المواصفة القائمة الموجودة في إعدادات المنصات، ويجب أن تساوي أحداث webhook في المواصفة أنواع الأحداث التي تستطيع الشيفرة إصدارها. فالعملاء المولَّدة ترفض قيم التعداد التي لا تعرفها، لذا فإن منصة تُضاف إلى الشيفرة دون المواصفة ستعطّل هؤلاء العملاء عند أول مزامنة لهم.
الثاني هو وضع الاختبار. فمفاتيح API نوعان، pk_live_… وpk_test_…، وكلاهما على الخادم نفسه. ويوجّه مفتاح الاختبار كل منصة إلى موصل اختبار: مواقع وتقييمات نموذجية حتمية ومصاغة مثل الحقيقية (مقهى على Google، تطبيق على App Store، فندق على Booking.com)، وردود تُقبل ولا تُنشر في أي مكان أبدًا، وعلى المنصات للقراءة فقط حقل url على كل تقييم، لأن الوثائق تَعِد به. فأي شخص يستطيع تشغيل العقد كاملًا، بما فيه مسارات الكتابة، دون لمس حساب حقيقي.
الأمثلة أدناه هي الأمثلة الواردة في المواصفة، مع استبدال الروابط بـ example.com. وطلب قائمة:
GET /v1/reviews?platform=google&limit=1 Authorization: Bearer pk_test_… يعيد التقييم المعروض سابقًا داخل data، مع next_cursor. والردّ على منصة تدعم الردود يُقبل بالرمز 202، ويعود التقييم وردّه في قائمة الانتظار (مع إسقاط الحقول الأخرى):
POST /v1/reviews/rev_01KJ8Q2M4T7HX3VB9CWD6NRZ5E/reply Authorization: Bearer pk_test_… Content-Type: application/json { "text": "Thanks Marta! We have added a second barista at lunch." } { "id": "rev_01KJ8Q2M4T7HX3VB9CWD6NRZ5E", "platform": "google", "reply": { "text": "Thanks Marta! We have added a second barista at lunch.", "created_at": null, "status": "queued", "error": null } } أما الحالات المثيرة للاهتمام فهي حالات الفشل. فكل خطأ له الشكل نفسه (type، code، message، retryable، request_id، docs_url)، وبعض الأكواد تضيف حقولًا يستطيع العميل التصرف بناءً عليها. والردّ على تقييم Yelp يعيد الرمز 422:
{ "error": { "type": "invalid_request_error", "code": "reply_not_supported", "message": "Yelp has no reply API for third parties, so Prisma only reads its reviews. Answer this one on the platform: https://example.com/biz/example-cafe-madrid", "retryable": false, "request_id": "req_01KJ8T3C5D7E9F1G3H5J7K9M1N", "docs_url": "https://example.com/docs/errors#reply_not_supported", "platform": "yelp", "url": "https://example.com/biz/example-cafe-madrid" } } والردّ الذي يتجاوز حد المنصة يعيد أيضًا 422، مع code: "reply_too_long" وplatform: "google_play" وmax_length: 350. ويجب أن يتفرّع العملاء بناءً على code، لا على message أبدًا: فالرسالة موجهة للبشر وقد تتغير.
ونفس الشكل يسري على الحركة الحية. هذا استجابة حقيقية من الإنتاج لطلب بلا مفتاح (مع اختصار الترويسات واستبدال رابط الوثائق):
HTTP/1.1 401 Unauthorized Content-Type: application/json Request-Id: req_01K6VVGDM8CFFJEQ3MNWWR582S {"error":{"type":"authentication_error","code":"missing_api_key","message":"Send your API key as \"Authorization: Bearer pk_live_…\".","retryable":false,"request_id":"req_01K6VVGDM8CFFJEQ3MNWWR582S","docs_url":"https://example.com/docs/errors#missing_api_key"}} حقل request_id في الجسم يطابق ترويسة Request-Id. ولكل عملية نفحص رمز الحالة، وأن الجسم يتحقق من صحته مقابل مخططه (جميع حقول التقييم الـ 14 موجودة، مع الأنواع القابلة للقيمة الفارغة حيث وُضّحت)، وشكل الخطأ على كل استجابة غير 2xx، وترويساتي Request-Id وحدود المعدل عند النجاح.
شغّل الفحوصات نفسها باستخدام Apidog CLI
وتنطبق الفحوصات نفسها على أي API يأتي مع ملف OpenAPI. إذ يستورد Apidog CLI المواصفة، ووكيل برمجي مثل Claude Code يكتب حالات الاختبار ويشغّلها. أعدّه مرة واحدة:
npm install -g apidog-cli@latest apidog login --with-token <YOUR_TOKEN> apidog skill install ثم أعطِ الوكيل تعليمات واحدة:
Import ./openapi.json into Apidog project <projectId>. Create test cases for the list reviews and reply endpoints that assert the status code, that the body validates against its schema with all 14 review fields present, and that the Request-Id header is set. Add a case that replies to a Yelp review and expects 422 with code reply_not_supported. Run them against the test environment and summarize any failures. يستورد الوكيل المواصفة، ويقرأ مخطط حالة الاختبار، ويتحقق من صحة حمولته، وينشئ الحالة ويشغّلها:
apidog import --project <projectId> --format openapi --file ./openapi.json apidog cli-schema get test-case-create apidog cli-schema validate test-case-create --file case.json apidog test-case create --project <projectId> --file case.json apidog run --test-case <caseId> --project <projectId> -e <envId> -r cli,junit وكاتب التقارير junit يكتب ملفًا يستطيع نظام CI الخاص بك قراءته، فيمكن لعملية التشغيل نفسها أن تصرّ على كل طلب دمج (pull request). ويغطي دليل CI/CD لـ Apidog CLI إعداد خط الأنابيب.
الدروس المستفادة
صمّم "لديه واجهة API" و"يمكن الردّ" كخاصيتين منفصلتين. فAtlassian وMicrosoft تُظهران أن واجهة API قد تكون موجودة ومع ذلك لا تقبل الردود. وعلامة واحدة لكليهما ستَعِد بردود لا نستطيع تقديمها.
خطّط لحالة الردّ unknown قبل أن يُرسل أول ردّ. فالحالة التي تعترف بعدم اليقين تكلفك قيمة تعداد واحدة؛ أما الردّ العام المكرّر فيكلفك ثقة العميل.
لا تثق في أن معرّف المنصة موجود أو يبقى ثابتًا. سجّل، لكل موصل، من أين يأتي المعرّف وما الذي قد يغيّره.
اختبر المواصفة مقابل الشيفرة، لا الشيفرة مقابل المواصفة فقط. فاختبار التعداد نحو عشرة أسطر، وهو يحمي من الخلل الذي يؤذي العملاء المولَّدة أكثر من غيره.




