واجهة API لبطاقات Wallet

تُصدر بطاقات Wallet (Apple Wallet وGoogle Wallet) وتُدار من لوحة تحكم Joryio والرحلات. تغطي هذه الواجهة الخطوة الوحيدة التي تحدث خارج Joryio: تسجيل وقت مسح/استرداد بطاقة عند نقطة البيع.

هذا المسح هو ما يشغّل مرحلة المسح في مسار تبني Wallet ومعدل المسح في التحليلات ← تحليلات Wallet. لا تخطر Apple ولا Google Joryio عند استخدام البطاقة داخل المتجر، لذلك يجب أن يرسل POS لديكم (أو تكامل وسيط) المسح إلى هنا.

المصادقة

تستخدم كل الطلبات مفتاح API كرمز bearer وتتطلب صلاحية wallet:write:

Authorization: Bearer jry_live_xxxxxxxxxxxxxxxxxxxx

سجل مسح/استرداد بطاقة

POST /wallet-passes/scan

الحقل	النوع	ملاحظات
serialNumber	string	مطلوب. المعرّف الفريد للبطاقة، يُقرأ من الرمز الشريطي/QR المطبوع على البطاقة.
properties	object	اختياري. بيانات تعريف استرداد حرة (المتجر والمبلغ وأمين الصندوق وغيرها). تُخزن كما هي في حدث pass.scanned الناتج وتتاح في التحليلات.

مثال

TOKEN=jry_live_xxxxxxxxxxxxxxxxxxxx
BASE=https://api-eu1.joryio.com

curl -sX POST "$BASE/wallet-passes/scan" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "serialNumber": "a1b2c3d4-e5f6-4789-abcd-1234567890ab",
    "properties": { "storeId": "store_42", "amount": 19.90, "currency": "EUR" }
  }'

الاستجابة

{ "recorded": true }

تكون recorded بقيمة false عندما لا توجد بطاقة بهذا serialNumber في مؤسستكم - لا يُسجل شيء في هذه الحالة.

ملاحظات

• متكرر بأمان لكل بطاقة في التحليلات. يعد المسار البطاقات المميزة، لذلك يظل مسح serialNumber نفسه مرة أخرى محسوبًا كبطاقة ممسوحة واحدة. ومع ذلك يصدر كل استدعاء حدث pass.scanned خاصًا به، فتُحتفظ properties لكل مسح.
• ما هو الرقم التسلسلي. serialNumber هو معرّف البطاقة المشفر في رمزها الشريطي/QR. اقرأوه عند نقطة البيع وأرسلوه كما هو.
• أين يظهر. تغذي عمليات المسح تدفق أحداث pass.scanned ومرحلة المسح/معدل المسح في تحليلات Wallet. يُحسب معدل المسح كـ scanned / downloaded (أساس نظيف بين المنصات).
• مفاتيح مساحات العمل المتعددة. إذا امتد مفتاح API عبر مساحات عمل متعددة، أضيفوا رأس X-Workspace-Id: <workspace-id>. وهو اختياري لمفتاح مساحة عمل واحدة.