نبني
للبنّائين · دليل تقني

باسات Apple Wallet بلا حساب مطوّر

كل ما قرأته عن باسات المحفظة يبدأ بجملة واحدة: تحتاج اشتراك Apple Developer المدفوع لتوقيع الملف. هذا صحيح، لكنه ليس الطريق الوحيد. هذا الدليل يشرح كيف تُصدر بطاقات بنّاء باسات Apple وGoogle Wallet اليوم بلا شهادة ولا اشتراك، وما الذي تشتريه حين تدفع.

١ · لماذا التوقيع هو العقبة

ملف .pkpass أرشيف ZIP فيه pass.json والصور وملف manifest.json بتجزئات الملفات، وملف signature يوقّع هذا المانيفست بشهادة Pass Type ID الصادرة من Apple. المحفظة ترفض أي ملف بلا توقيع صحيح، والشهادة لا تُمنح إلا لحساب مطوّر مدفوع. كل شيء آخر في الملف نصّ وصور يستطيع أي أحد كتابتها.

الخلاصة: العقبة ليست بناء الملف، بل من يوقّعه.

٢ · ثلاثة طرق، وما يناسب مجتمعاً

الطريقالكلفةما تكسبهما تخسره
شهادتك أنتاشتراك Apple Developer سنوياً + خادم يوقّعالباس باسمك بالكامل، وتحديث الباسات عن بُعد، وإشعاراتتجديد الشهادة كل سنة، ومسؤولية المفتاح الخاص، ووقت بناء
خدمة توقيع خارجيةطبقة مجانية بعدد شهري، وشعارك وألوانك الدقيقة في الباقات المدفوعةباس موقّع في دقائق، ويغطي Apple وGoogle معاًهوية الجهة المُصدِرة في ملف الباس هي الخدمة لا أنت، والباس ثابت لا يتحدّث
بلا محفظةصفرصفحة ورمز وجهة اتصال تعمل على كل جوالأيقونة المحفظة نفسها فقط

لمجتمع مثل نبني، حيث البطاقة مجانية والعدد بالعشرات لا بالآلاف، الطريق الثاني هو الأنسب، والثالث يبقى قائماً لمن لا يحمل آيفون.

٣ · كيف تعمل بطاقة بنّاء فعلاً

  1. الصفحة تعرض زر «Apple Wallet» على آيفون و«Google Wallet» على أندرويد، والزر يطلب مساراً على خادمنا لا الخدمة مباشرة.
  2. عند أول طلب، الخادم يبني وصف الباس من بيانات البطاقة: الاسم، والدور، والجوال في الرأس، والبريد والموقع في الوجه، والـvCard كاملة في الرمز.
  3. الخادم يرسل الوصف إلى خدمة التوقيع بمفتاح سرّي لا يظهر في المتصفح، ويستلم الملف موقّعاً، ويخزّنه عندنا.
  4. الطلبات التالية تُخدم من المخزن، فلا تُستهلك حصة الخدمة إلا عند تغيّر البيانات.
  5. الملف يُقدَّم بنوع application/vnd.apple.pkpass، فيفتحه سفاري في ورقة المحفظة مباشرة.
النتيجة: الرمز داخل الباس هو جهة الاتصال نفسها، فمن يمسحه من شاشة قفل جوالك يحفظك بلا إنترنت وبلا فتح أي رابط.

٤ · الطلب الذي يُرسل، حرفياً

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

POST https://api.walletwallet.dev/api/passes
Authorization: Bearer ww_live_…

{
  "barcodeValue": "BEGIN:VCARD\r\nVERSION:3.0\r\nFN:فهد غازي\r\n…END:VCARD",
  "barcodeFormat": "QR",
  "logoText": "نبني",
  "organizationName": "نبني",
  "headerFields":    [{ "label": "الجوال", "value": "+9665xxxxxxxx" }],
  "primaryFields":   [{ "label": "المؤسس", "value": "فهد غازي" }],
  "secondaryFields": [{ "label": "البريد", "value": "fahad@nabni.app" },
                      { "label": "الموقع", "value": "nabni.app" }],
  "backFields":      [{ "label": "البطاقة", "value": "https://…/c/fahad/" }],
  "color": "#2C39E5",
  "logoURL": "https://…/brand/wallet-logo.png",
  "thumbnailURL": "https://…/c/fahad/photo.png",
  "expirationDays": 3650
}

الرد يحمل الملف مشفّراً بـ base64 ورابط حفظ لـ Google Wallet ورابط مشاركة يختار المنصة تلقائياً.

٥ · خمسة أفخاخ وقعنا فيها

الصور المضمّنة تُقبل PNG فقطأرسلنا الصورة الشخصية data URI بصيغة JPEG فرُفض الطلب برسالة عن البروتوكول لا عن الصيغة. PNG مضمّنة أو رابط HTTPS يحلّها.
الشعار الأزرق على باس أزرق يختفيأيقونة التطبيق ليست شعار باس. الباس يحتاج الكلمة البيضاء على خلفية شفافة بمقاس ١٦٠×١٦٠، وإلا رأى المستخدم مربعاً بلون الخلفية.
البريد ذهب إلى ظهر البطاقةالحقول الخلفية لا تُرى إلا بقلب الباس. ما يجب أن يُقرأ فوراً يوضع في الحقول الثانوية، والظهر للنسخ.
التخزين المؤقت أبقى النسخة القديمةحين غيّرنا ترتيب الحقول لم يتغيّر الباس لأن مفتاح التخزين كان يعتمد على البيانات وحدها. المفتاح يجب أن يضم رقم نسخة التخطيط أيضاً.
Cloudflare يحجب الطلبات بلا User-Agentالطلب من سكربت بلا ترويسة متصفح رُدّ بخطأ ١٠١٠ قبل أن يصل إلى الخدمة. ضع User-Agent واضحاً باسم أداتك.

٦ · ما لا تستطيعه بلا شهادتك

٧ · قائمة تحقق قبل الإطلاق

المحفظة طبقة فوق البطاقة لا البطاقة نفسها. الصفحة والرمز وجهة الاتصال تعمل لكل جوال، والباس إضافة لمن يحمل آيفون. ابنِ ما يعمل للجميع أولاً، ثم أضف المحفظة. · بطاقة بنّاء · مشغَّل بواسطة نبني