مرجع الواجهة البرمجية

برافو باي خدمة مدفوعات تستهلكها المشاريع الأخرى عبر HTTP. كل ما يحتاجه مشروعك متاح من خلال هذه الواجهة البرمجية؛ أما لوحة التحكم فهي مخصّصة لمن يدير برافو باي نفسه فقط.

لم تُنشر بعد أي مسارات في v1. الأقسام التالية تشرح القواعد التي ستلتزم بها كل المسارات — العنوان الأساسي، وطريقة المصادقة، وسلوك الأخطاء وإعادة المحاولة. ويُوثَّق كل مسار هنا فور إطلاقه.

العنوان الأساسي

كل المسارات تقع تحت بادئة الإصدار:

https://your-bravopay-host/api/v1

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

نوع المحتوى. أرسل Content-Type: application/json وAccept: application/json. كل الاستجابات بصيغة JSON، بما فيها الأخطاء.

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

المبالغ ليست أرقامًا عشرية. تُرسل المبالغ أعدادًا صحيحة بالوحدة الصغرى للعملة (مثلًا 1050 مع "currency": "SAR" تعني ١٠٫٥٠ ريال)، ومعها رمز العملة دائمًا. اقرأ المبلغ ورمز العملة معًا، ولا تعتمد على أحدهما دون الآخر.

كل طلب يُصادَق عليه بوصفه مشروعًا عبر مفتاح واجهة برمجية يُصدر من لوحة تحكم برافو باي. لا يوجد مسار لتسجيل الدخول ولا تبادل للرموز — المفتاح نفسه هو بيانات الاعتماد، ولا تنتهي صلاحيته تلقائيًا.

أرسله في ترويسة X-API-Key:

X-API-Key: bp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

كما تُقبل ترويسة Authorization: Bearer <key> إن كانت أنسب لعميل HTTP لديك. تبدأ المفاتيح دائمًا بـ bp_.

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

احتفظ به على الخادم. المفتاح يحمل كامل صلاحيات مشروعك — لا تضعه في متصفّح ولا في تطبيق جوال ولا في أي مكان يستطيع المستخدم قراءته.

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

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

مفتاح واجهتك البرمجية يحدّد أي مشروع يُجري الاتصال، لا أيّ مستخدم من مستخدميك يخصّه هذا الاتصال — لذا تذكر ذلك بنفسك حيثما كان له معنى، عبر external_sso_id.

GET  api/v1/orders?external_sso_id=user-1043
POST api/v1/orders          { "external_sso_id": "user-1043", ... }

فهو معامل استعلام في عمليات القراءة، وحقل في جسم الطلب في عمليات الكتابة. وصفحة كل مسار تبيّن أيّهما، ومتى يكون مطلوبًا.

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

استخدم المعرّف الذي يصدره نظام الدخول الموحّد لديك، واستخدم المعرّف نفسه في كل موضع. يتعامل برافو باي معه كنصّ مبهم: يُخزَّن كما أُرسل تمامًا، ويُطابَق كما أُرسل تمامًا، وuser-1043 وUSER-1043 شخصان مختلفان. وإن غيّرت طريقة تعريفك للمستخدم فلن يتبعك برافو باي — تبقى عضوياته وطلباته وفواتيره القائمة معلّقة بالقيمة القديمة.

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

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

العزل. المشتركون غير مشتركين بين المشاريع. وذكر مشترك يخصّ مشروعًا آخر لا يجد شيئًا — فالسجل غير مرئي لمفتاحك، وقراءته بالمعرّف تُجاب بـ 404 دون أن تكشف أصلًا ما إذا كان موجودًا.

تُعاد الأخطاء بصيغة JSON، والمعنى تحمله حالة HTTP. اعتمد على رمز الحالة لا على نص الرسالة: الرسالة تلميح للبشر وقد تُعاد صياغتها، أما رمز الحالة فلا يتغيّر.

أخطاء التحقق تأتي مفصّلة حقلًا حقلًا، وأسماء الحقول مطابقة لما أرسلته، فيمكنك ربطها مباشرة بحقول النموذج لديك.

إعادة المحاولة آمنة مع مفتاح التكرار. كل طلب يغيّر البيانات يقبل ترويسة Idempotency-Key من اختيارك. وإرسال المفتاح نفسه مرتين يعيد نتيجة العملية الأولى بدل تنفيذها من جديد — فأي انقطاع أو مهلة أو خطأ 5xx يمكن إعادة محاولته دون أي خطر خصم مزدوج. استخدم قيمة فريدة لكل عملية منطقية (المعرّف UUID خيار مثالي)، ولا تُعد استخدامها إلا عند إعادة محاولة العملية نفسها.

نتيجة الدفع لا تصل في الاستجابة. الدفع عملية غير متزامنة: الاستجابة تخبرك بأن الطلب قُبل، أما النتيجة فتصلك لاحقًا على رابط الويب‑هوك المسجّل لمشروعك. لا تعتبر استجابة 2xx هنا دليلًا على أن الدفع تم.

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

POST api/v1/orders
X-API-Key: your-key
Idempotency-Key: 7f3c1e94-2b6a-4d51-9f0e-8c2d5a1b3e77

اختر قيمة تخصّ هذه المحاولة وحدها — والمعتاد أن تكون UUID — وأرسل القيمة نفسها في كل إعادة لها. ويحمل الجواب المعاد ترويسة Idempotent-Replay: true لتميّزه إن أردت.

ما الذي يصلك:

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

والنداء الفاشل يحرّر مفتاحه. فإذا عاد الطلب بـ 4xx أو 5xx لم يُحفظ شيء: صحّح الطلب وأعده بالمفتاح نفسه. فلا يستحقّ الإعادةَ إلا النجاح.

والمفاتيح محصورة بمشروعك، فلا تصطدم قيمتك بقيمة مستهلك آخر أبدًا، ولا يستطيع مشروع آخر قراءة جوابك.

ويُطابَق المفتاح على الفعل والمسار والمحتوى، لا على ترويساتك. فللنداء المعاد أن يحمل معرّف تتبّعٍ جديدًا أو Accept-Language مختلفة دون أن يصير نداءً آخر. وثمّ نتيجةٌ تستحقّ المعرفة: التكرار الذي يطلب لغةً أخرى يظلّ يتلقّى الجواب المحفوظ مكتوبًا بلغة النداء الأول. وهذا هو معنى التكرار. فإن أردت قراءته بلغةٍ أخرى فاستعمل GET — وهي لا تأخذ مفتاحًا أصلًا — أو أنشئ نداءً جديدًا حقًّا بمفتاح جديد.

أما مسارات القراءة فلا تأخذ الترويسة ولا تحتاجها — فـ GET لا يغيّر شيئًا، وإعادةُ جواب محفوظ له تعطيك سجلًّا قديمًا.

وأيّ النداءات تحتاجها: كل POST في هذا المرجع. إنشاء الطلب ونداءات دورة حياته الخمسة؛ وبدء العضوية ونداءات دورة حياتها الستة؛ واستهلاك الاستحقاق. فما كان قادرًا على التغيير احتاج مفتاحًا.

وملاحظة في الاستهلاك خاصةً: النداء المعاد الذي يصرف استعمالًا ثانيًا يعني شخصًا حُوسب مرتين على فعل واحد، فأعد استخدام مفتاح المحاولة التي تعيدها. أما صرف استعمال ثانٍ عن قصد فمحاولة جديدة تأخذ مفتاحًا جديدًا.

يحفظ برافو باي النصّ الذي كتبه المشغّل — اسم الميزة ووصف الباقة — بالعربية والإنجليزية. وأنت تختار أيّهما تريد بترويسة Accept-Language المعتادة، فتصلك الاستجابة مكتوبةً بها.

GET api/v1/features
X-API-Key: your-key
Accept-Language: ar

ولكل حقل مفتاح واحد لا مفتاحان: يصلك name وحده، لا name وname_ar معًا، فلا تحتاج إلى تفريعٍ في شفرتك يسأل «أيّ حقلٍ أقرأ؟».

واللغتان المدعومتان en وar. والتفاوض على اللغة تفاوضٌ عاديّ: تُحترم الأوزان، ويُردّ الرمز الإقليمي إلى لغته الأمّ، فـ ar-SA,ar;q=0.9,en;q=0.8 تعطيك العربية، وen-US تعطيك الإنجليزية.

والإنجليزية هي الأصل. فإن لم ترسل الترويسة، أو أرسلتها فارغة، أو طلبت لغةً لا يملكها برافو باي، جاءتك الاستجابة بالإنجليزية في صمت. فطلبُ fr ليس خطأً ولا 422؛ ولغةٌ أرسلتها سهوًا لا تستطيع أن تكسر تكاملك.

وتخبرك كل استجابة باللغة التي كُتبت بها فعلًا في ترويسة Content-Language. فاقرأها ولا تفترض، خاصةً إن كنت تمرّر ترويسة متصفّحٍ لا تتحكّم فيه.

ما الذي يتغيّر وما الذي لا يتغيّر

لا يتغيّر إلا النصّ الذي كتبه إنسانٌ ليقرأه الناس: name و**description**.

أما كل ما تقرأه شفرتك فيبقى كما هو في اللغتين:

• الحالات والأنواع — status وtype وduration_type وbilling_cycle؛
• المعرّفات — رمز الميزة code وأي id وexternal_sso_id؛
• المبالغ كلها بما فيها نصّ decimal، وسائر الأرقام؛
• التواريخ والأوقات وأسعار الصرف؛
• رسائل الأخطاء. فالفشل يُصاغ بالصياغة نفسها مهما كانت لغة طلبك.

فالنداء الواحد باللغتين لا يختلف إلا في النصّ المقروء، ولا شيء غيره. وازِن بين الاستجابتين أدناه.

الحقل غير المترجَم قيمته null

إذا لم يكن للحقل نصٌّ مكتوبٌ باللغة التي طلبتها، وصلتك القيمة null — لا نصّ اللغة الأخرى.

وهذا مقصود. فإعطاؤك الإنجليزية وقد طلبت العربية يُقحم كلماتٍ تُقرأ من اليسار في شاشةٍ تُقرأ من اليمين، فتبدو معطوبةً لمن ينظر إليها. أما null فصادقة، وتترك لك الاختيار: أن تُخفي الحقل أو تضع فيه صياغتك أنت. فعامِل كل name وdescription على أنه قد يكون فارغًا.

النداء المعاد يحتفظ بلغة أول جواب

حين تعيد نداءً بالمفتاح Idempotency-Key نفسه، يصلك الجواب المحفوظ — محتوى النداء الأول بلغة النداء الأول — ولو أرسلت Accept-Language مختلفة في المرة الثانية.

وهذا هو معنى الإعادة: الجواب نفسه للنداء نفسه لا جوابٌ جديد. فالمفتاح يقول هذا هو النداء الذي أجريته من قبل. فإن أردت القراءة بلغةٍ أخرى فأنشئ نداءً جديدًا بمفتاح جديد، أو اكتفِ بإعادة قراءة السجل بـ GET، فهي لا تأخذ مفتاحًا أصلًا.

ويُوسم الجواب المعاد بـ Idempotent-Replay: true. وفي هذا الجواب وحده ثِق بترويسة Idempotent-Replay قبل Content-Language: فالمحتوى محفوظ، ونصّه بلغة النداء الأول مهما قالت Content-Language عن الطلب الذي أرسلته للتوّ.

كل قائمة في هذه الواجهة تُجيب بصفحة واحدة، ولا تتجاوز الصفحة مئة سطر. وهذا يسري على كل مسار يعيد قائمة فيما يلي، فكُتب هنا مرةً واحدة بدل تكراره في كل واحد منها.

GET api/v1/orders?status=pending&limit=50&page=2
X-API-Key: your-key

ويُختار الجزء المطلوب بمعاملَين اختياريَّين في الرابط. فإن لم ترسل أيًّا منهما وصلتك أول ٢٥ سطرًا.

و**limit سقفٌ صارم لا مجرّد اقتراح.** فطلب limit=1000 يُرفض بـ 422 يذكر الحدّ، ولا يعود إليك مئةً في صمت — لأن صفحةً لم تطلبها هي صفحةٌ ستعدّها وتطابق عليها وتصدّقها. أما page بعد نهاية القائمة فأمرٌ آخر: سؤالٌ وجيه جوابه "لا شيء"، فيعود 200 بـ data فارغة، ولك أن تمشي بين الصفحات حتى تفرغ إحداها.

ما الذي يعود إليك

إلى جانب data التي تقرأها أصلًا، تحمل كل قائمة meta و**links**:

{
  "data": [ … ],
  "meta": {
    "current_page": 1,
    "per_page": 25,
    "from": 1,
    "to": 25,
    "total": 412,
    "last_page": 17
  },
  "links": {
    "first": "https://…/api/v1/orders?status=pending&page=1&limit=25",
    "last":  "https://…/api/v1/orders?status=pending&page=17&limit=25",
    "prev":  null,
    "next":  "https://…/api/v1/orders?status=pending&page=2&limit=25"
  }
}

• total يعدّ ما طابقته مرشِّحاتك لا ما في المشروع كلّه. وهو أرخص طريقة لسؤال كم فاتورة غير مسدّدة على هذا الشخص؟ — نداءٌ واحد بـ limit=1 يجيبك دون أن تقرأ سجلًّا واحدًا.
• from وto هما موضعا أول سطر وآخره في هذه الصفحة، وكلاهما null إذا كانت الصفحة فارغة. وlast_page يساوي 1 حتى حين لا يوجد شيء أصلًا.
• اتبع links.next بدل أن تبني الرابط التالي بنفسك. فالروابط تحمل مرشِّحاتك معها، فتسأل الصفحةُ الثانية ما سألته الأولى. وnext يكون null في الصفحة الأخيرة، وprev في الأولى، وهذا هو مَخرج حلقتك.

ولا يتغيّر meta ولا links بتغيّر Accept-Language. فهما أرقام وروابط، وهي واحدة في كل لغة، شأن كل حالة ونوع ورمز في هذه الواجهة.

أيّ النداءات تأخذهما

كل قائمة: الميزات والخطط والعضويات وسجلّ العضوية والطلبات والفواتير. أما ما يجيب بسجلٍّ واحد — خطة واحدة أو طلب واحد أو فحص استحقاق — فليس قائمة ولا يأخذ المعاملَين.

والمجموعات التي داخل السجلّ أمرٌ ثالث تعود كاملة: فـ items في الطلب وfeatures في العضوية جزءٌ من السجلّ نفسه، محدودةٌ بالخطة التي جاءت منها، ولا تُجزّأ إلى صفحات أبدًا.

أمران تعرفهما قبل أن تدور على الصفحات

الترتيب ثابت. فكل قائمة مرتّبة على ما لا يتكرّر، فلا يظهر سطرٌ في صفحتين بينما يسقط غيره.

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

الميزة استحقاق يعرّفه مشروعك — رمز code يتحقق منه تطبيقك قبل أن يسمح للمشترك بفعل شيء. الرموز رموزك أنت: تسمّيها ويخزّنها برافو باي كما كتبتها تمامًا، فـ readPaidArticle وreadpaidarticle ميزتان مختلفتان. لا توجد قائمة مشتركة؛ لكل مشروع رموزه الخاصة.

كِلا المسارين أدناه قراءة فقط. تُنشأ الميزات وتُعدّل من لوحة تحكم برافو باي لا عبر الواجهة البرمجية.

لعرض كل ميزات مشروعك:

GET api/v1/features

تُعاد الميزات مرتّبةً حسب code، وتحمل كل واحدة اسمها ووصفها بلغةٍ واحدة: هي التي طلبتها بترويسة Accept-Language، أو الإنجليزية إن لم تطلب شيئًا. وأي حقل لا ترجمة له بتلك اللغة قيمته null، ولا يُملأ أبدًا من اللغة الأخرى. راجع اختيار اللغة.

لجلب ميزة واحدة عبر رمزها:

GET api/v1/features/readPaidArticle
Accept-Language: ar

تكون الاستجابة ميزة واحدة بالبنية نفسها:

{
  "data": {
    "code": "readPaidArticle",
    "name": "قراءة المقالات المدفوعة",
    "description": "الوصول إلى المقالات المدفوعة."
  }
}

والرمز code رمزك أنت، لا يتغيّر بتغيّر اللغة؛ ولا يتغيّر إلا النصّ المقروء.

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

الخطة اشتراك يقدّمه مشروعك. تحمل كل خطة سعرًا، ومدة الفترة الواحدة، ووتيرة تحصيلها، ومجموعة الميزات التي تمنحها. وكِلا المسارين أدناه قراءة فقط — تُنشأ الخطط وتُعدّل من لوحة تحكم برافو باي لا عبر الواجهة البرمجية.

وخلافًا للميزة، ليس للخطة رمز من اختيارك؛ تُعرّف برقمها id — وهو المعرّف نفسه الذي ستستخدمه عند إنشاء طلب لها.

لعرض كل خطط مشروعك، الأقدم أولًا:

GET api/v1/plans

لجلب خطة واحدة عبر رقمها:

GET api/v1/plans/42

قراءة الحقول:

• price كائن، أو null للتجربة المجانية بلا سعر. ولا يستخدم رقمًا عشريًا أبدًا. فـ amount عدد صحيح من أصغر وحدة للعملة — 5000 مع minor_unit: 2 تعني 50.00. أما decimal فهو القيمة نفسها مكتوبةً بدقّة للعرض؛ أجرِ حساباتك على amount لا عليه.
• duration وduration_type تحدّدان طول الفترة التي تمنح الوصول — duration بقيمة 3 مع duration_type: "month" هو ربع سنة. أما billing_cycle فهو وتيرة التحصيل، وهي مستقلة: قد تمنح الخطة سنةً كاملة وتحصّل monthly.
• duration_type واحد من day أو week أو month أو year. وbilling_cycle واحد من monthly أو quarterly أو yearly أو one_time.
• status إمّا active (متاحة لاشتراكات جديدة) أو inactive (مسحوبة — تبقى الاشتراكات القائمة، ولا يمكن اشتراك جديد).
• is_trial وis_featured كلٌّ منهما صحيح لخطة واحدة على الأكثر في مشروعك.
• features تسرد كل ميزة ممنوحة برمزها code، مع usage_limit الذي تحدّده الخطة (-1 يعني بلا حد)، وحالة المنح active أو disabled.

أما رقم خطة لا يخصّ مشروعك فيُجاب عليه بـ 404 — تمامًا كرقم غير موجود. فأنت لا ترى إلا خطط مشروعك.

المنتج شراءٌ لمرة واحدة يبيعه مشروعك — شيء يُشترى مرةً لا يُشترك فيه. وكِلا المسارين أدناه قراءة فقط: تُنشأ المنتجات وتُعدّل من لوحة تحكم برافو باي لا عبر الواجهة البرمجية.

وكالخطة، ليس للمنتج رمز من اختيارك؛ يُعرّف برقمه id — وهو المعرّف نفسه الذي تضعه في سطر الطلب باسم product_id.

وشراء المنتج لا يمنح شيئًا داخل برافو باي. هذا هو الفرق كله بينه وبين الخطة، وعنه يتفرّع كل ما عداه. فدفع ثمن الخطة يُنشئ اشتراكًا ويفتح الميزات التي تمنحها، أما دفع ثمن المنتج فلا يُنشئ شيئًا: يسجّل برافو باي وقوع البيع، ويحاسب عليه، ويحصّل المال. وتسليم الشيء من شأن تطبيقك أنت. فراقِب حالة الطلب status — وfulfilled تعني أن البيع تمّ — ثم تصرّف بنفسك.

ولهذا السبب نفسه لا وجود في هذه الواجهة لمخزون ولا عنوان شحن ولا تنزيل ولا مفتاح ترخيص. فبرافو باي لا يعلم أعندك الصنف أم لا، ولا كيف يصل إلى المشتري.

لعرض كل منتجات مشروعك، الأقدم أولًا:

GET api/v1/products

ولعرض المعروض للبيع منها فقط:

GET api/v1/products?status=active

ولجلب منتج واحد عبر رقمه:

GET api/v1/products/12

قراءة الحقول:

• price كائن، ولا يستخدم رقمًا عشريًا أبدًا، وخلافًا لسعر الخطة لا يكون null قطّ — فللمنتج عملة دائمًا. وamount عدد صحيح من أصغر وحدة للعملة، فـ 7000 مع minor_unit: 2 تعني 70.00. أما decimal فهو القيمة نفسها مكتوبةً بدقّة للعرض؛ أجرِ حساباتك على amount لا عليه.
• compare_at_price هو السعر المشطوب «قبل الخصم»، أو null إن لم يكن المنتج على تخفيض. وهو للعرض لا غير. فلا يُحاسَب به أبدًا، ولا يُضاف إلى مجموع، ولا يُحوَّل إلى عملة أخرى، ولا يُكتب في سطر طلب. إنما وُجد لتشطبه في صفحتك، ولا شيء سواه.
• is_discounted وdiscount_percentage يُحسبان من السعرين لا يُخزَّنان، فلا يمكن أن يخالفاهما. وإن لم يكن ثمّة تخفيض كانا false وnull.
• status إمّا active (قابل للشراء) أو inactive (مسحوب). والطلب الجديد الذي يذكر منتجًا مسحوبًا يُرفض بـ 422، أما الطلبات القائمة فتبقى سطورها وفواتيرها مستحقة، ويظلّ الاسترداد ممكنًا.
• image_url هو صورة المنتج الرئيسية، أو null. وmedia كل ما عداها — صور إضافية وفيديو، بالترتيب الذي رتّبه المشغّل. وكلاهما روابط مطلقة على مضيف عام، لأنك تعرضها في موقعك أنت.
• media[].url هو العنوان النهائي سواء رُفع الملف إلى برافو باي أو استُضيف في مكان آخر، فلا تحتاج أبدًا إلى التفريق بينهما. وmedia تكون [] عند خلوّها، ولا تكون null قطّ — فيمكنك المرور عليها بلا احتراز.
• media[].sort_order ترتيب العرض، الأصغر أولًا. وهي تصلك مرتّبةً أصلًا.

وما يتحرّك مع اللغة: name وdescription وalt كل عنصر في media تُكتب باللغة التي طلبتها بترويسة Accept-Language. أما ما عداها — id وstatus وis_discounted وdiscount_percentage وكل رقم داخل كائنَي السعر وكل رابط — فهو واحد بأي لغة سألت. والحقل الذي لا ترجمة له يعود null، لا بنصّ اللغة الأخرى. راجع «اختيار اللغة».

وصفحة واحدة في كل مرة. تحصل على ٢٥ منتجًا ما لم تطلب limit مختلفًا، ولا تتجاوز ١٠٠ بحال. والمنتج يحمل معرضه كاملًا، فالصفحة هنا أثقل قراءةً مما يوحي به عدد سطورها. راجع «تصفّح القوائم».

أما رقم منتج لا يخصّ مشروعك فيُجاب عليه بـ 404 — تمامًا كرقم غير موجود، وكذلك منتج حذفه المشغّل. فأنت لا ترى إلا منتجات مشروعك.

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

لعرض العضويات، الأحدث أولًا:

GET api/v1/memberships

ومرّر external_sso_id لحصر القائمة بشخص واحد — وهو سؤال «بماذا يستحقّ هذا الشخص؟»:

GET api/v1/memberships?external_sso_id=user-1043

لجلب عضوية واحدة عبر رقمها:

GET api/v1/memberships/8091

ولقراءة سجلّها — كل ما مرّت به من عمليات دورة الحياة، والأحدث أولًا:

GET api/v1/memberships/8091/history

قراءة الحقول:

• status واحد من active أو trialing أو paused أو past_due أو cancelled أو expired. ولا يمنح الوصولَ إلا active وtrialing، وما عداهما يحجبه — فـ paused تعليق قابل للرجوع، وpast_due مشكلة دفع قد تُحلّ، وcancelled وexpired منتهيتان.
• plan_id هو الخطة التي جاءت منها العضوية، أو null لعضوية يدوية منحها المشغّل مباشرة. وname وdescription لقطتان أُخذتا عند الإنشاء، فلا تتغيّران إن أُعيدت تسمية الخطة لاحقًا.
• start_date وend_date وtrial_ends_at وcancelled_at طوابع زمنية (أو null). وauto_renew يبيّن هل ضُبطت على التجديد.
• features تسرد الاستحقاقات التي تمنحها العضوية حاليًا — ولا يُدرج منح مسحوب أو منح سُحبت ميزته. تحمل كل واحدة رمز الميزة code، وusage_count الخاص بهذا الشخص، وusage_limit المنسوخ من الخطة (-1 يعني بلا حد)، وremaining (ما تبقّى، أو null عند اللامحدود)، وreset_at (تاريخ إعادة ضبط العدّاد، أو null).

أما رقم عضوية لا يخصّ مشروعك فيُجاب عليه بـ 404. فأنت لا ترى إلا عضويات مشروعك.

سبع عمليات كتابة، واحدة لكل ما قد يحدث للاشتراك. ويجيب كلٌّ منها بالعضوية كما صارت — بالبنية نفسها التي تعيدها مسارات القراءة — فيكفيك نداءٌ واحد لتحديث ما تعرضه لمستخدمك.

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

POST api/v1/memberships
{ "external_sso_id": "user-1043", "plan_id": 42 }

ومرّر start_date لتقديم بداية المدة أو تأجيلها، وauto_renew لتسجيل رغبة الشخص في الاستمرار. أما خطة تجريبية فتبدأ العضوية trialing لا active، ويُضبط trial_ends_at على نهاية المدة. والجواب 201.

للتجديد — مدة أخرى من مدد الخطة، ورصيد جديد:

POST api/v1/memberships/8091/renew

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

لتغيير الخطة — والاتجاه أنت من يصرّح به، لأنك وحدك تعرف أيّ خططك هي الأعلى:

POST api/v1/memberships/8091/upgrade    { "plan_id": 43 }
POST api/v1/memberships/8091/downgrade  { "plan_id": 41 }

ويؤدّي المساران العمل نفسه ولا يختلفان إلا فيما يُسجَّل: تُنسخ صياغة الخطة الجديدة وحدودها، وتُسحب الميزات التي لا تحملها الخطة الجديدة، وتُستأنف المدة بمقدار مدة واحدة من الخطة الجديدة. ويُحتفظ بما أُنفق من الاستخدام — فمن استخدم ثلاثة من خمسة تصديرات فقد استخدم ثلاثة مهما صار الحد الجديد. ولا تُحتسب أيّ تسوية تناسبية ولا ينتقل أيّ مال.

للإلغاء والتعليق ورفع التعليق:

POST api/v1/memberships/8091/cancel      { "reason": "Switching providers" }
POST api/v1/memberships/8091/pause
POST api/v1/memberships/8091/reactivate

ويسري الإلغاء فورًا ويُلغي auto_renew؛ وreason اختياري ويُخزَّن كما هو بكلماتك أنت. أما التعليق فحجزٌ قابل للرجوع يوقف الوصول ولا يغيّر شيئًا سواه، فرفعه يعيد ما عُلّق تمامًا — إلى trialing إن كانت نافذة التجربة ما تزال مفتوحة، وإلى active فيما عدا ذلك.

لقراءة السجل. كل عملية مما سبق تترك قيدًا، والأحدث أولًا:

GET api/v1/memberships/8091/history

ويحمل كل قيد action (وهو created أو renewed أو upgraded أو downgraded أو paused أو reactivated أو cancelled)، وcreated_at، و— عند تغيير الخطة وحده — old_plan_id وnew_plan_id.

حين يُرفض النداء. بخلاف التحقق من استحقاق، فالنداء في دورة الحياة إن تعذّر تنفيذه فهو خطأ: لو أُجبت بـ 200 لصحّ لك أن تظنّ العضوية قد تحرّكت. فأيّ عملية لا تسمح بها حالة العضوية الراهنة — تعليق عضوية ملغاة، أو رفع تعليق عن عضوية لم تُعلَّق قط، أو تجديد عضوية يدوية لا خطة لها تُؤخذ منها مدة — يُجاب عنها بـ 422 مع message يبيّن الحالات المسموح بالعملية منها. ولا يُطبَّق شيء جزئيًّا ولا يُكتب أيّ سجل.

أما رقم عضوية أو خطة يخصّ مشروعًا آخر فيُجاب عنه بـ 404. فأنت لا تتصرّف إلا في سجلات مشروعك.

وتطلب السبعة كلها ترويسة Idempotency-Key — انظر «إعادة المحاولة بأمان». فأعد المحاولة بالمفتاح نفسه يصلك الجواب الأول، لا تجديدٌ ثانٍ ولا مدةٌ ثانية.

الاستحقاق يجيب عن سؤال واحد بشأن شخص واحد: هل يجوز لهذا الشخص استخدام هذه الميزة الآن، وكم تبقّى منها إن كانت محدودة بعدّاد. وتُسمّى الميزة بالرمز code الذي عرّفتها به، ويُسمّى الشخص بـ external_sso_id الذي تعرفه به.

للتحقق من الوصول دون إنفاق استخدام — قراءة آمنة يمكن استدعاؤها عند كل تحميل صفحة:

GET api/v1/entitlements/reports.export?external_sso_id=user-1043

لإنفاق استخدام واحد — كتابة تسجّل أنّ استخدامًا قد وقع. أرسِل الشخص في جسم الطلب:

POST api/v1/entitlements/reports.export/consume

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

قراءة الحكم. يجيب المساران بـ 200 وبالبنية نفسها — فالنتيجة السالبة ليست خطأً بل جوابًا. وتفرّع على هذه الحقول:

• granted — القيمة المنطقية التي تحتاجها البوّابة. تكون true فقط عند السماح بالوصول (وعند الإنفاق: عند تسجيل استخدام فعلًا).
• status — السبب، لتخبر مستخدمك بشيء محدّد. وهو واحد من: granted، وlimit_reached (يملك الميزة لكن العدّاد نفد)، وmissing_feature (عضوية فاعلة لكنها لا تمنح هذه الميزة)، وno_active_membership (لا عضوية في حالة تمنح الوصول).
• usage_limit وusage_count وremaining — الأرقام خلف عرضٍ مثل «٣ من ٥ مستخدمة». وusage_limit يساوي -1 حين يكون المنح بلا حد، وremaining يكون null عندئذٍ (وكلما لم يُبلغ أيّ منح أصلًا). وعند إنفاقٍ مُجاب بالمنح يكون usage_count هو العدّ بعد الاستخدام.

كما أنّ شخصًا أو رمزًا code لا وجود له في مشروعك ليس خطأً أيضًا — بل يُحَلّ ببساطة إلى no_active_membership أو missing_feature. فأنت لا تتصرّف إلا في عضويات مشروعك وميزاته.

ويطلب الإنفاق ترويسة Idempotency-Key — انظر «إعادة المحاولة بأمان». فأعد المحاولة بالمفتاح نفسه يصلك الجواب الأول، ولا يُصرف استخدامٌ ثانٍ. أما صرف استخدام ثانٍ عن قصد فمحاولة جديدة تأخذ مفتاحًا جديدًا. والتحقّق لا يأخذ الترويسة ولا يحتاجها، فهو لا يغيّر شيئًا.

الطلب عملية شراء قام بها أحد الأشخاص في مشروعك. وبرافو باي لا يحتفظ بسلّة شراء — فالسلّة تخصّ تطبيقك، وأنت ترسل الطلب مكتملًا هنا في نداء واحد. فيُسعَّر ويُكتب وتُصدر فاتورته معًا، ثم يعود بحالة pending.

POST api/v1/orders
Idempotency-Key: 7f3c1e94-2b6a-4d51-9f0e-8c2d5a1b3e77

{
  "external_sso_id": "user-1043",
  "items": [{ "plan_id": 42, "quantity": 2 }]
}

وترويسة Idempotency-Key مطلوبة — انظر «إعادة المحاولة بأمان». ويجيب النداء بـ 201 ومعه الطلب وسطوره والفاتورة التي صدرت له.

والمال دائمًا عدد صحيح بالوحدة الصغرى. فـ 5000 في عملة ذات منزلتين هي ٥٠٫٠٠. لا ترسل رقمًا عشريًا ولا تقرأه: فكل مبلغ يعود كائنًا يحمل amount وcurrency وminor_unit ونصًّا عشريًّا في decimal.

العملة. إن تركت currency استُخدمت عملة مشروعك الافتراضية. ومرّرها لتسعّر الطلب بغيرها — على أن تكون عملة يُسمح لمشروعك باستعمالها، وإلا كان الجواب 422.

الخطط والمنتجات. يذكر السطر واحدًا فقط من plan_id أو product_id، وللطلب الواحد أن يجمع بينهما كيف شاء. فالسطر الجامع بينهما مرفوض، وكذلك الخالي منهما. وكلاهما يُسعَّر ويُحوَّل ويُجمَّع ويُفوتَر ويُدفَع ويُستردّ على السواء — ولا يختلفان إلا في موضع واحد، وبعد الدفع وحده: فسطر الخطة يُنشئ اشتراكًا ويفتح ميزاته، وسطر المنتج لا يُنشئ شيئًا البتّة. فراقِب حالة الطلب status وسلّم المنتج بنفسك.

كيف يُسعَّر السطر. يُسعَّر كل سطر بعملة الخطة أو المنتج ثم يُحوَّل إلى عملة الطلب، ويحمل السطر الاثنتين معًا:

• unit_price وtotal — بعملة العنصر نفسه، وهما ما تعرضه بجانبه؛
• converted_unit_price وconverted_total — المال نفسه بعملة الطلب، وهو ما تجمعه إجماليات الطلب وما سيُحصَّل فعلًا؛
• exchange_rate — السعر المستعمل، نصًّا عشريًا.

وهذا السعر لقطة محفوظة. أعد قراءة الطلب بعد سنة تجد الأرقام التي حُصّلت منك، وإن صُحّح السعر بعدها. ويُضرب سعر الوحدة المحوَّل في الكمية، فثلاثةٌ بسعر وحدةٍ معلن تساوي دائمًا إجمالي السطر المعلن.

أما الخطة بلا سعر — التجربة المجانية — فتأتي سطرًا بصفر بعملة الطلب. وأما خطة مسعّرة بعملة لا يوجد سعر صرف منها إلى عملة الطلب فلا يمكن تحويلها، ويُرفض النداء كله بـ 422 بدل التخمين، ولا يُكتب شيء.

وdiscount_amount يُخصم من المجموع الفرعي، بالوحدة الصغرى لعملة الطلب. وما زاد على المجموع الفرعي جوابه 422.

لقراءة الطلبات:

GET api/v1/orders
GET api/v1/orders?external_sso_id=user-1043
GET api/v1/orders?status=pending
GET api/v1/orders/5501

القائمة بالأحدث أولًا، والمرشِّحان يجتمعان. وstatus واحد من pending أو confirmed أو processing أو fulfilled أو cancelled أو refunded — وما عداها جوابه 422 لا قائمةٌ فارغة في صمت.

ويحمل كل طلب allowed_transitions — وهي الخطوات التي يجوز لك أن تخطوها، أي cancelled أو refunded أو لا شيء — و**is_terminal**. اقرأهما بدل تثبيت دورة حياتنا في شيفرتك، يبقَ تكاملك عاملًا حين تضيف نسخةٌ لاحقة حالةً جديدة. أما الحالات المتقدّمة فليست في تلك القائمة عن قصد: فالدفع هو ما يقدّم الطلب، لا نداءٌ منك.

أما رقم خطة أو طلب لا يخصّ مشروعك فجوابه 404، دون أن يكشف أموجود هو أم لا.

عمليتا كتابة، للنهايتين اللتين لا يعرفهما إلا أنت: انصرف عميلك، أو طلب عميلك ماله. ويجيب كلٌّ منهما بالطلب كما صار — بالبنية نفسها التي تعيدها القراءات — فيكفيك نداءٌ واحد لتحديث ما تعرضه لمستخدمك. وكلتاهما تطلب ترويسة Idempotency-Key؛ انظر «إعادة المحاولة بأمان».

ويتقدّم الطلب هكذا:

pending → confirmed → processing → fulfilled

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

فليس ثَمّ ما تؤكّده أو تنفّذه بيدك. واستعلم عن الطلب (أو اقرأ invoice.status) لترى ذلك يحدث.

وللإلغاء — صرف النظر عنه، مع سبب اختياري بكلماتك أنت:

POST api/v1/orders/5501/cancel   { "reason": "Customer changed their mind" }

وتتبعه الفاتورة تلقائيًا: تُلغى إن لم تُدفع، وتُردّ إن كانت قد دُفعت. أما طلبٌ أُلغيت فاتورته أو رُدّت من قبل فيُلغى دون المساس بها ثانيةً.

وللاسترداد — إعادة المال:

POST api/v1/orders/5501/refund   { "reason": "Duplicate charge" }

فيَرُدّ كل دفعةٍ ما زالت محفوظة على الطلب، ويُعلّم الفاتورة refunded، وينهي الطلب عند refunded. فالطلب يقول refunded لأنّ المال عاد، لا بدلًا من عودته.

ولا تسترد إلا مالًا موجودًا حقًّا. فطلبٌ لم يُدفع قطّ، أو رُدّت دفعاته كلها من قبل، جوابه 422 ولا يغيّر شيئًا — واستعمل الإلغاء في حالة عدم الدفع. فالاثنان يبلغان الموضع نفسه في الطلب غير المدفوع (إذ تُلغى الفاتورة في الحالين)، والفرق أنّ الطلب يقول حينئذٍ cancelled وهو صدق، لا refunded وهو ادّعاءٌ بعودة مالٍ لم يدخل أصلًا.

والاسترداد لا يُلغي العضوية. فبرافو باي يفكّ المال ويترك الاستحقاق قائمًا، لأنّ كون مستخدمك أحقَّ بالوصول أو غير أحقّ قرارُك أنت لا قرارنا — فلعلّه في وسط أمرٍ ما. فألغِ العضوية بنفسك إن أردتَ زوالها؛ انظر «دورة حياة العضوية».

وحين يُرفض النداء. فخطوةٌ لا تسمح بها حال الطلب — إلغاء ما استُرد — جوابها 422 مع message يسمّي الحالات التي يجوز له الانتقال إليها. ولا يُطبَّق شيء جزئيًا. واقرأ allowed_transitions في الطلب لتعرف ذلك سلفًا؛ فهو لا يذكر إلا ما تستطيع نداءه فعلًا.

أما رقم طلب يخصّ مشروعًا آخر فجوابه 404.

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

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

GET api/v1/invoices
GET api/v1/invoices/3301

والقائمة بالأحدث أولًا. والمرشّحات تجتمع:

GET api/v1/invoices?external_sso_id=user-1043
GET api/v1/invoices?status=paid
GET api/v1/invoices?type=subscription_renewal
GET api/v1/invoices?unpaid=1

و**unpaid=1** هو ما تلجأ إليه عند تحصيل المستحقّات. فـ«ما زال مستحقًّا» يشمل ثلاث حالات، وهذا المرشّح يعفيك من معرفتها — ومن متابعة تغيّرها.

قراءة الحقول:

• status واحد من draft (مهيّأة ولم تُصدر)، وpending (صدرت وتنتظر السداد)، وpaid، وoverdue (تجاوزت تاريخ استحقاقها وما زالت مستحقّة — متأخّرة لا ضائعة، فما زال سدادها ممكنًا)، وrefunded، وvoid. وrefunded وvoid نهائيتان.
• وis_paid وis_unpaid كلاهما مذكور، وليسا نقيضين: فالفاتورة refunded ليست واحدًا منهما — إذ دُفعت ثم رُدّت. وكذلك void، إذ لم يكن عليها شيء أصلًا.
• وtype يبيّن ما يُحاسَب عليه ومن ثمّ أيّ رقم مضبوط: فـ order يحمل order_id، وsubscription وsubscription_renewal وupgrade_proration تحمل membership_id، وrefund لا يحمل واحدًا منهما.
• وtotal كائن فيه amount (عدد صحيح بالوحدة الصغرى) وcurrency وminor_unit ونصّ عشري في decimal. وamount هو ما تُجري عليه حسابك.
• وexchange_rate وbase_currency لقطةٌ أُخذت عند إصدار الفاتورة. ولا تتحرّكان إن صُحّح السعر لاحقًا، وهذا هو سبب حفظهما أصلًا.
• وdue_date تاريخ أو null، وpaid_at طابع زمني أو null.

وdue_date قيمته null دائمًا حاليًّا: إذ لا يحدّد برافو باي شروط السداد بعد، لأن انتماءها إلى المشروع أو إلى الخطة ما زال قيد التقرير. فلا تبنِ عليه إجراءات مطالبة قبل أن يحمل قيمة. وحين يحملها، فإن الفاتورة التي تتجاوزه دون سداد تنتقل إلى overdue وحدها — وoverdue تنبيهٌ لا نهاية، وتبقى الفاتورة قابلة للسداد.

أما رقم فاتورة لا يخصّ مشروعك فجوابه 404.