PassHive API

أصدر بطاقات ولاء على Apple Wallet و Google Wallet من نظام الكاشير أو تطبيقك أو موقعك. العنوان الأساسي https://passhive.app/v1، والطلبات والردود بصيغة JSON.

التوثيق

أنشئ مفتاح من لوحة التحكم (مفاتيح API) وابعثه كـBearer token. المفتاح يظهر مرة وحدة، فخليه على السيرفر تبعك، وما تحطه بمتصفح أو تطبيق.

Authorization: Bearer ph_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

GET/v1/me

يرجع بيانات نشاطك وتصميم البطاقة والباقة.

العملاء والبطاقات

كل عميل إله بطاقة ولاء وحدة. أنشئ العميل، وبعدين ابعتله addToAppleWallet أو addToGoogleWallet (أو cardUrl، وهي صفحة فيها الزرين). البطاقة المحفوظة بتتحدث لحالها لما تتغير الأختام أو النقاط.

POST/v1/customers

الحقل	النوع	ملاحظات
`name`	نص	بيظهر على البطاقة، لحد 60 حرف.
`phone`	نص	اختياري، بالصيغة الدولية، وما بيتكرر بنفس النشاط.
`externalId`	نص	اختياري، رقمك الخاص (رقم العميل بنظام الكاشير). إذا بعثت رقم موجود بيرجعلك نفس العميل.
`branchId`	نص	اختياري. إذا الفرع موقف، بطاقاته بتوقف.

بيرجع 201 لعميل جديد، و200 مع "created": false إذا الرقم أو externalId موجود.

{
  "data": {
    "id": "cu_8f2c1e0b5a7d4c3b9e6f1a2d",
    "name": "Lina",
    "phone": "+962790000000",
    "externalId": "pos-4471",
    "branchId": "br_...",
    "stamps": 3,
    "stampTarget": 10,
    "points": 0,
    "pointsPerReward": null,
    "rewardsAvailable": 0,
    "rewardsClaimed": 1,
    "visits": 13,
    "status": "active",
    "cardUrl": "https://passhive.app/c/cu_....sig",
    "addToAppleWallet": "https://passhive.app/c/cu_....sig/apple.pkpass",
    "addToGoogleWallet": "https://passhive.app/c/cu_....sig/google",
    "createdAt": "2026-11-02T09:12:00.000Z",
    "updatedAt": "2026-11-02T10:40:00.000Z"
  }
}

GET/v1/customers?phone=+962790000000

GET/v1/customers?externalId=pos-4471

GET/v1/customers?limit=50&before=<next>

القائمة من الأحدث، واستعمل قيمة next للصفحة اللي بعدها.

GET/v1/customers/{id}

الأختام والنقاط والمكافآت

بطاقة الأختام بتستعمل /stamps، وبطاقة النقاط /points. لما تكمل البطاقة بتنضاف مكافأة والعداد بيبدأ من جديد، والعميل بيوصله إشعار على الجوال.

POST/v1/customers/{id}/stamps

{ "count": 1, "branchId": "br_..." }

POST/v1/customers/{id}/points

{ "points": 25 }

POST/v1/customers/{id}/redeem

بيستعمل مكافأة وحدة جاهزة، وبيرجع no_reward_available إذا ما في.

الرسائل

بيحط عرض على البطاقات المحفوظة. على iPhone بيظهر كإشعار من البطاقة، وعلى Android بتعرضه Google على البطاقة مع تنبيه. بدون customerId بيروح للكل. الحد 3 إرسالات باليوم لكل جمهور.

POST/v1/messages

{ "title": "Weekend offer", "body": "2 stamps for every coffee this Friday.", "customerId": null }

الفروع

مواقع الفروع بتنضاف للبطاقات (Apple لحد 10 مواقع، وبتظهر على شاشة القفل قريب من الفرع). الباقة بتحدد كم فرع ممكن يكون شغال.

GET/v1/branches

POST/v1/branches

{ "name": "Abdoun", "address": "Abdoun Circle, Amman", "lat": 31.9539, "lng": 35.8836 }

PATCH/v1/branches/{id}

{ "active": false }

الأخطاء والحدود

الأخطاء بترجع رقم حالة و{"error": "code"}.

الحالة	الرمز	المعنى
400	`invalid_json`، `invalid_phone`، `invalid_amount`، `card_uses_points`	صحح الطلب.
401	`missing_api_key`، `invalid_api_key`	تأكد من ترويسة Authorization.
402	`branch_limit_reached`	كبّر الباقة أو وقف فرع.
404	`customer_not_found`	رقم غلط أو تابع لنشاط ثاني.
429	`rate_limited`	600 طلب بالدقيقة لكل مفتاح، و 3 رسائل باليوم.