# واجهة برمجة تطبيقات Apple Wallet PassKit

تتيح لك واجهة برمجة تطبيقات PassKit Designer إنشاء وتحديث وتنزيل وإدارة [بطاقات Apple Wallet](/ar/product/messaging-channels/apple-wallet-passes/) برمجيًا. وهي تدعم نفس العمليات التي يقوم بها منشئ البطاقات في لوحة التحكم. استخدمها لإصدار بطاقات الولاء، والكوبونات، وتذاكر الفعاليات، وبطاقات الصعود إلى الطائرة، وبطاقات المتاجر، ولإرسال تحديثات حية إلى البطاقات المثبتة بالفعل على أجهزة المستخدمين.

<Aside type="note" title="شرط مسبق: شهادة PassKit">
قبل أن تتمكن من إنشاء بطاقات لتطبيق ما، يجب تكوين شهادة توقيع iOS PassKit لهذا التطبيق. تتم إدارة الشهادة في لوحة تحكم Pushwoosh. بدونها، ستفشل طلبات `create` و `update`. انظر [تكوين بطاقة Apple Wallet لنظام iOS](/ar/developer/first-steps/connect-messaging-services/ios-configuration/ios-wallet-pass-configuration/).
</Aside>

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

```
https://apple-passkit.svc-nue.pushwoosh.com
```

يتم تقديم جميع نقاط النهاية عبر HTTPS. تستخدم الطلبات والاستجابات `application/json` ما لم يُذكر خلاف ذلك.

## المصادقة

يجب أن يتضمن كل طلب ترويسة `Authorization` مع [رمز الوصول لواجهة برمجة تطبيقات Pushwoosh](/ar/developer/api-reference/api-access-token/) الخاص بك:

```
Authorization: Token <api-token>
```

يجب أن يكون الحساب الذي يمتلك الرمز هو مالك التطبيق المشار إليه بواسطة `applicationCode`. أي طلب لتطبيق ينتمي إلى حساب آخر سيعيد `403 Forbidden`.

## الاصطلاحات

*   **تسمية الحقول:** تستخدم حقول JSON `lowerCamelCase` (على سبيل المثال، `passTypeIdentifier`، `serialNumber`، `backgroundColor`).
*   **الحقول غير المعبأة:** تتضمن الاستجابات جميع الحقول، حتى لو كانت فارغة أو قيمتها صفر.
*   **البيانات الثنائية:** حقول `bytes` مثل `pkpassData` وبيانات الصورة `data` هي سلاسل نصية مشفرة بـ Base64 في JSON.
*   **الأرقام التسلسلية:** يتم دائمًا تعيين `serialNumber` بواسطة الخادم عند إنشاء بطاقة. يتم تجاهل أي قيمة ترسلها عند الإنشاء؛ فهو يحدد البطاقة لجميع العمليات اللاحقة.

### استجابات الخطأ

تقوم واجهة برمجة التطبيقات بربط رموز الحالة الداخلية برموز حالة HTTP:

| حالة HTTP | المعنى |
| :---- | :---- |
| `400 Bad Request` | وسيطة غير صالحة—حقل مطلوب مفقود أو مشوه. |
| `401 Unauthorized` | ترويسة `Authorization` مفقودة أو غير صالحة. |
| `403 Forbidden` | التطبيق لا ينتمي إلى حساب المتصل. |
| `404 Not Found` | لم يتم العثور على البطاقة أو القالب أو التطبيق. |
| `503 Service Unavailable` | الخدمة بكامل طاقتها أو غير متاحة مؤقتًا. |

## نقاط النهاية

| الطريقة | المسار | الوصف |
| :---- | :---- | :---- |
| `POST` | `/api/pass/validate` | التحقق من صحة تكوين بطاقة |
| `POST` | `/api/pass/create` | إنشاء `.pkpass` جديد |
| `POST` | `/api/pass/update/{serialNumber}` | تحديث بطاقة موجودة وإخطار الأجهزة |
| `GET` | `/api/passes` | سرد جميع البطاقات لتطبيق ما |
| `GET` | `/api/pass/{applicationCode}/{serialNumber}` | الحصول على بطاقة واحدة |
| `GET` | `/api/pass/{applicationCode}/{serialNumber}/download` | تنزيل `.pkpass` لبطاقة موجودة |
| `DELETE` | `/api/pass/{applicationCode}/{serialNumber}` | حذف بطاقة |
| `GET` | `/api/pass/{serialNumber}/registrations` | سرد الأجهزة المسجلة لبطاقة |
| `GET` | `/api/config` | الحصول على تكوين PassKit للتطبيق |
| `GET` | `/api/templates` | سرد قوالب البطاقات المتاحة |
| `GET` | `/api/templates/{filename}` | الحصول على قالب واحد |


## إنشاء بطاقة

يُنشئ ويُوقع ويُخزن بطاقة جديدة، ثم يُرجع رقمها التسلسلي المُعين من الخادم.

`POST` `/api/pass/create`

<Aside type="tip">
للحصول على ملف `.pkpass` نفسه، استدعِ [تنزيل بطاقة](#download-a-pass) (أو أنشئ [رابط تثبيت / رمز QR](#share-a-pass-as-a-qr-code)) باستخدام الرقم التسلسلي المُرجع.
</Aside>


### نص الطلب

| المعلمة | النوع | مطلوب | الوصف |
| :---- | :---- | :---- | :---- |
| `pass` | object | نعم | [كائن البطاقة](#pass-object) الذي يصف البطاقة. |
| `images` | array of objects | لا | [صور البطاقة](#pass-image-object) (أيقونة، شعار، إلخ). `icon` و `logo` مطلوبان لبطاقة صالحة. |
| `userId` | string | نعم | معرف مستخدم Pushwoosh الذي صدرت له البطاقة. |
| `applicationCode` | string | نعم | [رمز تطبيق Pushwoosh](/ar/developer/api-reference/api-identifiers/#application-code). |

<Aside type="note">
عند الإنشاء، إذا تم حذف `teamIdentifier` أو `passTypeIdentifier` أو `organizationName`، فسيتم تعيينها افتراضيًا إلى القيم من شهادة التطبيق المكونة. يتم تعيين `formatVersion` افتراضيًا إلى `1`. يتم تعيين `serialNumber` من جانب الخادم.
</Aside>

##### مثال على الطلب

```json
{
  "applicationCode": "XXXXX-XXXXX",
  "userId": "user-123",
  "pass": {
    "description": "بطاقة ولاء Acme",
    "logoText": "Acme",
    "backgroundColor": "rgb(60, 65, 76)",
    "foregroundColor": "rgb(255, 255, 255)",
    "labelColor": "rgb(255, 255, 255)",
    "storeCard": {
      "primaryFields": [
        { "key": "balance", "label": "الرصيد", "value": "1200 نقطة" }
      ],
      "secondaryFields": [
        { "key": "member", "label": "عضو", "value": "جين دو" }
      ]
    },
    "barcodes": [
      {
        "format": "PKBarcodeFormatQR",
        "message": "1234567890",
        "messageEncoding": "iso-8859-1"
      }
    ]
  },
  "images": [
    { "imageType": "icon", "data": "<base64>", "contentType": "image/png" },
    { "imageType": "logo", "data": "<base64>", "contentType": "image/png" }
  ]
}
```

### الاستجابة

| الحقل | النوع | الوصف |
| :---- | :---- | :---- |
| `serialNumber` | string | الهوية الفريدة المعينة من الخادم للبطاقة التي تم إنشاؤها. استخدمها لجلب البطاقة ([الحصول على بطاقة](#get-a-pass)) أو تنزيل `.pkpass` ([تنزيل بطاقة](#download-a-pass)). |
| `message` | string | رسالة النتيجة. |

##### مثال على الاستجابة

```json
{
  "serialNumber": "a1b2c3d4-1234-5678-9abc-def012345678",
  "message": "تم إنشاء البطاقة بنجاح"
}
```

## التحقق من صحة بطاقة

يتحقق من تكوين بطاقة مقابل مواصفات Apple دون إنشاء ملف. مفيد قبل استدعاء الإنشاء.

`POST` `/api/pass/validate`

### نص الطلب

| المعلمة | النوع | مطلوب | الوصف |
| :---- | :---- | :---- | :---- |
| `pass` | object | نعم | [كائن البطاقة](#pass-object) للتحقق من صحته. |

### الاستجابة

| الحقل | النوع | الوصف |
| :---- | :---- | :---- |
| `valid` | boolean | ما إذا كانت البطاقة تجتاز التحقق من الصحة. |
| `errors` | array of strings | المشاكل التي تمنع الاستمرار ويجب إصلاحها. |
| `warnings` | array of strings | إرشادات غير مانعة. |



## تحديث بطاقة

يعيد إنشاء البطاقة بمحتوى جديد، ويعيد توقيعها، ويزيد من علامة التحديث الخاصة بها، ويرسل **إشعار دفع صامت** إلى كل جهاز قام بتسجيل البطاقة. يقوم iOS بعد ذلك بجلب وتثبيت الإصدار المحدث في الخلفية.

`POST` `/api/pass/update/{serialNumber}`

### معلمات المسار

| المعلمة | النوع | الوصف |
| :---- | :---- | :---- |
| `serialNumber` | string | الرقم التسلسلي الذي تم إرجاعه عند إنشاء البطاقة. |

### نص الطلب

| المعلمة | النوع | مطلوب | الوصف |
| :---- | :---- | :---- | :---- |
| `updates` | object | نعم | [كائن البطاقة](#pass-object) الكامل مع المحتوى الجديد. |
| `applicationCode` | string | نعم | رمز تطبيق Pushwoosh. |

يتم الحفاظ على `serialNumber` (من المسار) ورمز المصادقة للبطاقة بواسطة الخادم بغض النظر عما ترسله.

### الاستجابة

| الحقل | النوع | الوصف |
| :---- | :---- | :---- |
| `success` | boolean | ما إذا كان التحديث قد نجح. |
| `updateTag` | integer | علامة التحديث الجديدة (طابع زمني Unix). |
| `message` | string | رسالة النتيجة. |



## سرد البطاقات

يُرجع قائمة مقسمة إلى صفحات ومرتبة للبطاقات المخزنة لتطبيق ما.

`GET` `/api/passes?applicationCode=XXXXX-XXXXX&page=0&perPage=20`

### معلمات الاستعلام

| المعلمة | النوع | مطلوب | الوصف |
| :---- | :---- | :---- | :---- |
| `applicationCode` | string | نعم | رمز تطبيق Pushwoosh. |
| `orderBy` | string | لا | حقل الفرز: `UPDATED` (الافتراضي) أو `CREATED`. |
| `orderDirection` | string | لا | اتجاه الفرز: `DESC` (الافتراضي، الأحدث أولاً) أو `ASC`. |
| `page` | integer | لا | فهرس الصفحة يبدأ من الصفر. الافتراضي هو `0`. |
| `perPage` | integer | لا | حجم الصفحة. `0` أو محذوف يستخدم الافتراضي للخادم. |

### الاستجابة

| الحقل | النوع | الوصف |
| :---- | :---- | :---- |
| `passes` | array of objects | الصفحة الحالية من [سجلات البطاقات](#pass-record-object). |
| `page` | integer | فهرس الصفحة المُرجعة. |
| `perPage` | integer | حجم الصفحة المستخدم لهذه الاستجابة. |
| `total` | integer | العدد الإجمالي للبطاقات للتطبيق عبر جميع الصفحات. |

##### مثال على الاستجابة

```json
{
  "passes": [ /* سجلات البطاقات */ ],
  "page": 0,
  "perPage": 20,
  "total": 137
}
```


## الحصول على بطاقة

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

`GET` `/api/pass/{applicationCode}/{serialNumber}`

### معلمات المسار

| المعلمة | النوع | الوصف |
| :---- | :---- | :---- |
| `applicationCode` | string | رمز تطبيق Pushwoosh. |
| `serialNumber` | string | الرقم التسلسلي للبطاقة. |

### الاستجابة

يُرجع `{ "pass": { ... } }`، وهو [سجل بطاقة](#pass-record-object) واحد.


## تنزيل بطاقة

يُرجع ملف `.pkpass` المخزن لبطاقة موجودة.

`GET` `/api/pass/{applicationCode}/{serialNumber}/download`

### الاستجابة

| الحقل | النوع | الوصف |
| :---- | :---- | :---- |
| `pkpassData` | string (Base64) | ملف `.pkpass`. |
| `filename` | string | اسم الملف المقترح. |


## حذف بطاقة

يزيل سجل بطاقة وملف `.pkpass` المخزن الخاص به.

`DELETE` `/api/pass/{applicationCode}/{serialNumber}`

### الاستجابة

| الحقل | النوع | الوصف |
| :---- | :---- | :---- |
| `success` | boolean | ما إذا تم حذف البطاقة. |
| `message` | string | رسالة النتيجة. |



## الحصول على تسجيلات البطاقة

يسرد الأجهزة التي أضافت البطاقة ومسجلة للتحديثات.

`GET` `/api/pass/{serialNumber}/registrations?applicationCode=XXXXX-XXXXX`

### الاستجابة

يُرجع `{ "registrations": [ ... ] }`، حيث يحتوي كل عنصر على:

| الحقل | النوع | الوصف |
| :---- | :---- | :---- |
| `deviceLibraryIdentifier` | string | معرف مكتبة جهاز Apple. |
| `pushToken` | string | رمز الدفع للبطاقة للجهاز. |



## الحصول على التكوين

يُرجع تكوين PassKit الذي تم حله لتطبيق من شهادته.

`GET` `/api/config?applicationCode=XXXXX-XXXXX`

### الاستجابة

| الحقل | النوع | الوصف |
| :---- | :---- | :---- |
| `teamIdentifier` | string | معرف فريق Apple من الشهادة. |
| `passTypeIdentifier` | string | معرف نوع البطاقة من الشهادة. |
| `organizationName` | string | اسم المنظمة من الشهادة. |
| `hasCertificate` | boolean | ما إذا كانت الشهادة مكونة. |
| `webServiceUrl` | string | عنوان URL الأساسي لخدمة الويب للبطاقة. يقوم العملاء بإنشاء رابط تثبيت بإضافة `/v1/passes/{passType}/{serial}?token={authToken}`. |



## القوالب

سرد قوالب البطاقات المتاحة، أو جلب قالب واحد كـ [كائن بطاقة](#pass-object) يمكنك استخدامه كنقطة بداية.

`GET` `/api/templates` — يُرجع `{ "templates": [ { "filename", "name", "description", "style" } ] }`.

`GET` `/api/templates/{filename}` — يُرجع `{ "template": { ...كائن البطاقة... } }`.



## مشاركة بطاقة كرمز QR

للسماح للمستخدمين بإضافة بطاقة عن طريق مسح رمز QR (أو النقر على رابط)، قم بترميز **عنوان URL لتثبيت** البطاقة في رمز QR. يتم بناء عنوان URL من القيم التي تحصل عليها بالفعل من واجهة برمجة التطبيقات:

```
{webServiceUrl}/v1/passes/{passTypeIdentifier}/{serialNumber}?token={authenticationToken}
```

| جزء URL | من أين تحصل عليه |
| :---- | :---- |
| `webServiceUrl` | [`GET /api/config`](#get-configuration) → `webServiceUrl` |
| `passTypeIdentifier` | [سجل البطاقة](#pass-record-object) → `pass.passTypeIdentifier` (من القائمة/الحصول) |
| `serialNumber` | [سجل البطاقة](#pass-record-object) → `serialNumber` |
| `authenticationToken` | [سجل البطاقة](#pass-record-object) → `pass.authenticationToken` |

مثال:

```
https://apple-passkit.svc-nue.pushwoosh.com/v1/passes/pass.com.acme.loyalty/a1b2c3d4-1234-5678-9abc-def012345678?token=AbC123XyZ
```

قم بعرض عنوان URL هذا كرمز QR باستخدام أي مكتبة QR. عندما يقوم المستخدم بمسحه، يفتح جهازه الرابط، ويقوم بتنزيل أحدث `.pkpass`، ويطالبه Wallet بإضافته—مما يسجل الجهاز أيضًا للتحديثات.



## مرجع الكائنات

### كائن البطاقة

| الحقل | النوع | الوصف |
| :---- | :---- | :---- |
| `formatVersion` | integer | إصدار تنسيق البطاقة. الافتراضي هو `1`. |
| `passTypeIdentifier` | string | معرف نوع بطاقة Apple (`pass.com.yourcompany.passtype`). يتم تعيينه افتراضيًا من الشهادة. |
| `serialNumber` | string | يتم تعيينه بواسطة الخادم عند الإنشاء؛ يحدد البطاقة. |
| `teamIdentifier` | string | معرف فريق Apple. يتم تعيينه افتراضيًا من الشهادة. |
| `organizationName` | string | المنظمة المعروضة على البطاقة. يتم تعيينها افتراضيًا من الشهادة. |
| `description` | string | وصف يمكن قراءته من قبل الإنسان (مطلوب من قبل Apple). |
| `boardingPass` / `coupon` / `eventTicket` / `storeCard` / `generic` | object | نمط البطاقة. يجب تعيين **واحد فقط** بالضبط. انظر [مجموعات الحقول](#field-group-object). |
| `backgroundColor` | string | لون الخلفية، `rgb(r, g, b)`. |
| `foregroundColor` | string | لون المقدمة (النص)، `rgb(r, g, b)`. |
| `labelColor` | string | لون تسمية الحقل، `rgb(r, g, b)`. |
| `logoText` | string | النص المعروض بجانب الشعار. |
| `suppressStripShine` | boolean | تعطيل تأثير اللمعان على صورة الشريط. |
| `barcodes` | array | [الباركود](#barcode-object) المعروض على البطاقة. |
| `locations` | array | [المواقع](#location-object) التي تجعل البطاقة ذات صلة. |
| `beacons` | array | [المنارات (Beacons)](#beacon-object) التي تجعل البطاقة ذات صلة. |
| `relevantDate` | string | تاريخ ISO 8601 عندما تصبح البطاقة ذات صلة. |
| `maxDistance` | integer | أقصى مسافة (بالأمتار) لصلة الموقع. |
| `expirationDate` | string | تاريخ انتهاء الصلاحية ISO 8601. |
| `voided` | boolean | يحدد البطاقة على أنها باطلة. |
| `groupingIdentifier` | string | يجمع البطاقات ذات الصلة (تذاكر الفعاليات/بطاقات الصعود). |
| `userInfo` | object (map) | بيانات تطبيق عشوائية من نوع مفتاح/قيمة. |

<Aside type="note">
تتم إدارة `authenticationToken` و `webServiceUrl` بواسطة الخدمة ولا يحتاج عملاء واجهة برمجة التطبيقات إلى تعيينهما.
</Aside>

### كائن مجموعة الحقول

كل نمط بطاقة (`boardingPass`، `coupon`، `eventTicket`، `storeCard`، `generic`) يجمع [الحقول](#field-object) في مناطق:

| الحقل | النوع | الوصف |
| :---- | :---- | :---- |
| `headerFields` | array | تظهر في رأس البطاقة (مرئية عند تكديسها في Wallet). |
| `primaryFields` | array | الحقول الأبرز. |
| `secondaryFields` | array | أسفل الحقول الأساسية. |
| `auxiliaryFields` | array | حقول إضافية أسفل الحقول الثانوية. |
| `backFields` | array | تظهر على ظهر البطاقة. |

`boardingPass` لديه بالإضافة إلى ذلك `transitType` (`PKTransitTypeAir`، `PKTransitTypeTrain`، `PKTransitTypeBus`، `PKTransitTypeBoat`، أو `PKTransitTypeGeneric`).

### كائن الحقل

| الحقل | النوع | الوصف |
| :---- | :---- | :---- |
| `key` | string | مفتاح حقل فريد داخل البطاقة. |
| `label` | string | تسمية الحقل. |
| `value` | string | قيمة الحقل (نص أو رقم كسلسلة نصية). |
| `changeMessage` | string | رسالة تظهر عند تغيير القيمة (استخدم `%@` كعنصر نائب). |
| `textAlignment` | string | قيمة `PKTextAlignment`. |
| `dateStyle` / `timeStyle` | string | `PKDateStyle` لتنسيق التاريخ/الوقت. |
| `isRelative` | boolean | عرض التاريخ بالنسبة للوقت الحالي. |
| `numberStyle` | string | `PKNumberStyle` لتنسيق الأرقام. |
| `currencyCode` | string | رمز عملة ISO 4217. |
| `dataDetectorTypes` | array of strings | كاشفات البيانات لتطبيقها على القيمة. |

### كائن الباركود

| الحقل | النوع | الوصف |
| :---- | :---- | :---- |
| `format` | string | `PKBarcodeFormatQR`، `PKBarcodeFormatPDF417`، `PKBarcodeFormatAztec`، أو `PKBarcodeFormatCode128`. |
| `message` | string | البيانات المشفرة في الباركود. |
| `messageEncoding` | string | ترميز النص، عادة `iso-8859-1`. |
| `altText` | string | النص المعروض أسفل الباركود. |

### كائن الموقع

| الحقل | النوع | الوصف |
| :---- | :---- | :---- |
| `latitude` | number | خط العرض. |
| `longitude` | number | خط الطول. |
| `altitude` | number | الارتفاع بالأمتار. |
| `relevantText` | string | النص المعروض على شاشة القفل بالقرب من هذا الموقع. |

### كائن المنارة (Beacon)

| الحقل | النوع | الوصف |
| :---- | :---- | :---- |
| `proximityUuid` | string | iBeacon proximity UUID. |
| `major` | integer | القيمة الرئيسية. |
| `minor` | integer | القيمة الثانوية. |
| `relevantText` | string | النص المعروض على شاشة القفل بالقرب من هذه المنارة. |

### كائن صورة البطاقة

| الحقل | النوع | الوصف |
| :---- | :---- | :---- |
| `imageType` | string | واحد من `icon`، `logo`، `strip`، `background`، `footer`، `thumbnail`. `icon` و `logo` مطلوبان. |
| `data` | string (Base64) | بايتات الصورة. |
| `contentType` | string | نوع MIME، على سبيل المثال `image/png`. |

### كائن سجل البطاقة

يتم إرجاعه بواسطة نقاط نهاية السرد/الحصول.

| الحقل | النوع | الوصف |
| :---- | :---- | :---- |
| `serialNumber` | string | الرقم التسلسلي للبطاقة. |
| `passTypeIdentifier` | string | معرف نوع البطاقة. |
| `organizationName` | string | اسم المنظمة. |
| `description` | string | وصف البطاقة. |
| `createdAt` | string | الطابع الزمني للإنشاء (RFC 3339). |
| `updatedAt` | string | الطابع الزمني لآخر تحديث (RFC 3339). |
| `updateTag` | integer | علامة التحديث الحالية. |
| `pass` | object | [كائن البطاقة](#pass-object) الكامل، للتحرير. |
| `userId` | string | معرف مستخدم Pushwoosh الذي صدرت له البطاقة. |