unidays php
v1.2.2 Bug fix
هذه هي مكتبة PHP للتكامل مع UNiDAYS. سيتم استخدام هذا في عمليات التكامل المشفرة وغير المشفرة. توفر الوثائق التالية وصفًا للتطبيقات والأمثلة.
كيفية استخدام هذا الرمز؟
التتبع المباشر
التحقق بدون كود
المساهمة
فيما يلي وصف لجميع المعلمات المتاحة. أي مما تقدمه لنا يعتمد على العقد المتفق عليه.
| المعلمة | وصف | نوع البيانات | مثال |
|---|---|---|---|
| معرف الشريك | معرف الشريك الخاص بك كما هو مقدم من UNiDAYS. إذا كنت تعمل في مناطق جغرافية متعددة، فقد يكون لديك معرف شريك مختلف لكل منطقة | دليل Base64 المشفر | XaxptFh0sK8Co6pI== |
| معرف المعاملة | معرف فريد للمعاملة في نظامك | خيط | الطلب123 |
| عملة | رمز العملة ISO 4217 | خيط | GBP |
يعد وجود الرمز أو معرف العضو كمعلمة أمرًا إلزاميًا أيضًا:
| المعلمة | وصف | نوع البيانات | مثال |
|---|---|---|---|
| شفرة | كود خصم UNiDAYS المستخدم | خيط | ABC123 |
| معرف العضو | سيتم توفيرها فقط إذا كنت تستخدم تكاملًا بدون تعليمات برمجية | دليل Base64 المشفر | 0LTio6iVNaKj861RM9azJQ== |
لاحظ أنه يجب حذف أي من الخصائص التالية التي تكون قيمتها غير معروفة من الاستدعاءات. أي من القيم التالية التي تقدمها لنا ستعتمد على العقد المتفق عليه.
| المعلمة | وصف | نوع البيانات | مثال |
|---|---|---|---|
| إجمالي الطلب | إجمالي المبلغ النقدي المدفوع، منسقًا إلى منزلتين عشريتين | عشري | 209.00 |
| العناصرUNiDAYSDiscount | إجمالي المبلغ النقدي لخصم UNiDAYS المطبق على إجمالي قيمة العنصر ItemsGross ، منسقًا إلى منزلتين عشريتين | عشري | 13.00 |
| ضريبة العناصر | إجمالي المبلغ النقدي للضريبة المطبقة على العناصر، منسقًا بمنزلتين عشريتين | عشري | 34.50 |
| إجمالي الشحن | إجمالي المبلغ النقدي لتكلفة الشحن، قبل تطبيق أي خصم أو ضريبة على الشحن، مُنسق إلى منزلتين عشريتين | عشري | 5.00 |
| خصم الشحن | إجمالي المبلغ النقدي لخصم الشحن (UNiDAYS أو غير ذلك) المطبق على الطلب، منسقًا إلى منزلتين عشريتين | عشري | 3.00 |
| العناصرالإجمالي | إجمالي المبلغ النقدي للعناصر، بما في ذلك الضريبة، قبل تطبيق أي خصومات، منسق إلى منزلتين عشريتين | عشري | 230.00 |
| عناصر أخرىخصم | إجمالي المبلغ النقدي لجميع الخصومات بخلاف UNiDAYS المطبقة على ItemsGross ، منسقًا إلى منزلتين عشريتين | عشري | 10.00 |
| UNiDAYSDiscountPercentage | تم تطبيق خصم UNiDAYS، كنسبة مئوية، منسقًا إلى منزلتين عشريتين | عشري | 10.00 |
| عميل جديد | هل المستخدم هو عميل جديد (مقابل مكرر) بالنسبة لك؟ | منطقية | صحيح أو خطأ |
فيما يلي مثال لسلة تحتوي على الحقول المتعلقة بمعلمات التتبع UNiDAYS،
| غرض | إجمالي | خصم يوندايز | خصم آخر | ضريبة | صافي المجموع | إجمالي الخط |
|---|---|---|---|---|---|---|
| أحذية | 100.00 | 0.00 | 0.00 | 16.67 | 83.33 | 100.00 |
| قميص | 50.00 | 5.00 | 0.00 | 7.50 | 37.50 | 45.00 |
| جينز | 80.00 | 8.00 | 10.00 | 10.33 | 51.67 | 62.00 |
| المجاميع | 230.00 | 13.00 | 10.00 | 34.50 | 172.50 | 207.00 |
| شحن | 5.00 | |||||
| خصم الشحن | 3.00 | |||||
| إجمالي الطلب | 209.00 |
فيما يلي الخيارات الثلاثة لتنفيذ التكامل الخاص بك. تغطي هذه الأمثلة كلاً من عمليات التكامل المشفرة وغير المشفرة (راجع ملف PDF للتحليلات المباشرة للحصول على التفاصيل) وتتضمن جميع المعلمات الاختيارية. والغرض منها هو أن تكون بمثابة مبدأ توجيهي للتنفيذ.
تقوم هذه الطريقة بإرجاع عنوان URL الذي يمكنك استخدامه للاتصال بواجهة برمجة التطبيقات.
من المتطلبات الإلزامية أن يتم توقيع جميع عناوين URL للخادم. هذا يعني أنه يتعين عليك تمرير مفتاح التوقيع الذي توفره لك UNiDAYS كإحدى الوسائط. مفتاح التوقيع هو GUID مشفر بواسطة Base64. تقبل نقطة النهاية هذه طلبات GET و POST .
طريقة الحصول على عنوان URL لإجراء طلب من خادم إلى خادم هي create_server_url($key) . لتنفيذ هذه الطريقة، تحتاج أولاً إلى استخدام DirectTrackingDetailsBuilder لإنشاء كائن تتبع مباشر بالخصائص التي تريد إرسالها إلينا. يمكن العثور على مزيد من التفاصيل حول هذا المنشئ هنا.
بمجرد إنشاء الكائن الذي يحتوي على التفاصيل التي تحتاج إلى إرسالها إلينا، قم بإنشاء مساعد التتبع، مع توفير هذه التفاصيل كوسيطة new TrackingHelper($directTrackingDetails) واتصل ->create_server_url($key) حيث يكون $key هو المفتاح المقدم لك بواسطة يوم واحد.
سيتم إرجاع عنوان URL إليك، والذي يمكن استخدامه بعد ذلك للاتصال بواجهة برمجة التطبيقات (API) الخاصة بنا. إذا نجحت الاستجابة برمز الحالة 204، فلن يتم إرجاع أي محتوى. سيعمل هذا مع طلبات POST و GET .
<?php
use Unidays ;
// UNiDAYS will provide your partnerId and key
$ partnerId = " somePartnerId " ;
$ key = " someSigningKey " ;
$ details = new DirectTrackingDetailsBuilder ( $ partnerId , ' order123 ' , ' GBP ' );
$ details -> withOrderTotal ( 209.00 );
$ details -> withItemsUnidaysDiscount ( 13.00 );
$ details -> withCode ( ' UNI123 ' );
$ details -> withItemsTax ( 34.50 );
$ details -> withShippingGross ( 5.00 );
$ details -> withShippingDiscount ( 3.00 );
$ details -> withItemsGross ( 230.00 );
$ details -> withItemsOtherDiscount ( 10.00 );
$ details -> withUnidaysDiscountPercentage ( 10.00 );
$ details -> withNewCustomer ( true );
$ directTrackingDetails = $ details -> build ();
$ helper = new TrackingHelper ( $ directTrackingDetails );
$ url = $ helper -> create_server_url ( $ key );يُعرف هذا أيضًا باسم التكامل من العميل إلى الخادم. تقوم هذه الطريقة بإرجاع عنوان URL الذي يمكن وضعه داخل عنصر البرنامج النصي في صفحة الدفع المؤجل/نجاح الطلب لاستدعاء واجهة برمجة التطبيقات.
إنه خيار لإنشاء عنوان url موقع لطلب البرنامج النصي الخاص بك. للقيام بذلك، ستحتاج إلى أن ترسل لنا مفتاح التوقيع الذي توفره لك UNiDAYS كأحد الوسائط للطريقة الموقعة.
$url = $helper->create_signed_script_url($key);
بدلاً من
$url = $helper->create_script_url();
طريقة الحصول على عنوان URL لإجراء طلب من عميل إلى خادم هي create_script_url() أو create_signed_script_url($key) إذا اخترت إرجاع عنوان URL مُوقع. لتنفيذ هذه الطريقة، تحتاج أولاً إلى استخدام DirectTrackingDetailsBuilder لإنشاء كائن تتبع مباشر بالخصائص التي تريد إرسالها إلينا. يمكن العثور على مزيد من التفاصيل حول هذا المنشئ هنا.
بمجرد إنشاء الكائن الذي يحتوي على التفاصيل التي تحتاج إلى إرسالها إلينا، قم بإنشاء مساعد التتبع، مع توفير هذه التفاصيل كوسيطة new TrackingHelper($directTrackingDetails) واتصل ->create_script_url() للحصول على عنوان URL غير موقع، أو ->create_signed_script_url($key) ، حيث $key هو المفتاح المقدم لك بواسطة UNiDAYS.
سيتم إرجاع عنوان URL إليك والذي يمكن وضعه ضمن عنصر البرنامج النصي في صفحة الدفع المؤجل/نجاح الطلب لاستدعاء واجهة برمجة التطبيقات. في حالة النجاح، سيتم إرجاع استجابة برمز الحالة 200 OK. سيعمل هذا فقط مع طلبات GET .
المثال أدناه هو طلب لعنوان URL للبرنامج النصي غير الموقع.
<?php
use Unidays ;
// UNiDAYS will provide your partnerId and key
$ partnerId = " somePartnerId " ;
$ details = new DirectTrackingDetailsBuilder ( $ partnerId , ' order123 ' , ' GBP ' );
$ details -> withOrderTotal ( 209.00 );
$ details -> withItemsUnidaysDiscount ( 13.00 );
$ details -> withCode ( ' UNI123 ' );
$ details -> withItemsTax ( 34.50 );
$ details -> withShippingGross ( 5.00 );
$ details -> withShippingDiscount ( 3.00 );
$ details -> withItemsGross ( 230.00 );
$ details -> withItemsOtherDiscount ( 10.00 );
$ details -> withUnidaysDiscountPercentage ( 10.00 );
$ details -> withNewCustomer ( true );
$ directTrackingDetails = $ details -> build ();
$ helper = new TrackingHelper ( $ directTrackingDetails );
$ url = $ helper -> create_script_url ();تشبه المكالمات إلى عميل التتبع إنشاء عنوان url للخادم، ولكن بدلاً من إرجاع عنوان URL، يرسل UNiDAYS الطلب ويعيد الاستجابة.
من المتطلبات الإلزامية أن يتم تزويد جميع مكالمات عميل التتبع بمفتاح، حيث يتم توقيع الطلبات التي ترسلها UNiDAYS.
لتنفيذ هذه الطريقة، تحتاج أولاً إلى استخدام DirectTrackingDetailsBuilder لإنشاء كائن تتبع مباشر بالخصائص التي تريد إرسالها إلينا. يمكن العثور على مزيد من التفاصيل حول هذا المنشئ هنا.
بمجرد إنشاء الكائن الذي يحتوي على التفاصيل التي تحتاج إلى إرسالها إلينا، قم بإنشاء مثيل لعميل التتبع، مع توفير هذه التفاصيل كمعلمة، إلى جانب مفتاح التوقيع الذي قدمته لك UNiDAYS new TrackingClient($directTrackingDetails, $key) واتصل ->sendRequest() .
يتم إرجاع HttpResponseMessage. إذا نجحت الاستجابة، فيجب أن تحتوي على رمز الحالة 204 لا يوجد محتوى.
يقوم المثال أدناه بإعداد بعض تفاصيل التتبع المباشر، واستدعاء sendRequest على العميل وتكرار رمز الاستجابة إلى وحدة التحكم.
<?php
use Unidays ;
// UNiDAYS will provide your partnerId and key
$ partnerId = " somePartnerId " ;
$ key = " someSigningKey " ;
$ details = new DirectTrackingDetailsBuilder ( $ partnerId , ' order123 ' , ' GBP ' );
$ details -> withOrderTotal ( 209.00 );
$ details -> withItemsUnidaysDiscount ( 13.00 );
$ details -> withCode ( ' UNI123 ' );
$ details -> withItemsTax ( 34.50 );
$ details -> withShippingGross ( 5.00 );
$ details -> withShippingDiscount ( 3.00 );
$ details -> withItemsGross ( 230.00 );
$ details -> withItemsOtherDiscount ( 10.00 );
$ details -> withUnidaysDiscountPercentage ( 10.00 );
$ details -> withNewCustomer ( true );
$ directTrackingDetails = $ details -> build ();
$ client = new TrackingClient ( $ directTrackingDetails , $ key );
$ response = $ client -> sendRequest ();
echo $ response -> code ; توفر UNiDAYS تكوينًا لنقطة نهاية الاختبار لكائن TrackingHelper .
سيقوم كائن TrackingHelper، الذي تم تكوينه في وضع الاختبار، بإضافة معلمة إضافية ( &Test=True ) إلى عنوان URL الذي تم إرجاعه إليك أو إرساله إليك.
<?php
use Unidays ;
// UNiDAYS will provide your partnerId and key
$ partnerId = " somePartnerId " ;
$ key = " someSigningKey " ;
$ details = new DirectTrackingDetailsBuilder ( $ partnerId , ' order123 ' , ' GBP ' );
$ details -> withOrderTotal ( 209.00 );
$ details -> withItemsUnidaysDiscount ( 13.00 );
$ details -> withCode ( ' UNI123 ' );
$ details -> withItemsTax ( 34.50 );
$ details -> withShippingGross ( 5.00 );
$ details -> withShippingDiscount ( 3.00 );
$ details -> withItemsGross ( 230.00 );
$ details -> withItemsOtherDiscount ( 10.00 );
$ details -> withUnidaysDiscountPercentage ( 10.00 );
$ details -> withNewCustomer ( true );
$ directTrackingDetails = $ details -> build ();
// Pass in an aditional argument of true to instantiate the TrackingHelper object in test mode
$ helper = new TrackingHelper ( $ directTrackingDetails , true );
// The url generated will now contain the appended $Test=True parameter, this url will call our test endpoint
$ url = $ helper -> create_server_url ( $ key );الغرض من المنشئ هو جعل الأمر بسيطًا وبديهيًا عند إنشاء أي طلب تتبع إلى UNiDAYS.
الوسائط الموجودة على المنشئ هي المعلمات الإلزامية:
$directTrackingDetails = new DirectTrackingDetailsBuilder($partnerId, $currency, $transactionId)
هناك بعد ذلك مجموعة متنوعة من الأساليب المتاحة لبناء المعلومات التي تريد إرسالها إلينا والتي يمكن ربطها بالتسلسل حسب المثال. تتطابق هذه مع المعلمات الموجودة في الجزء العلوي من هذا المستند.
base64 encoded guid )string )decimal )decimal )decimal )decimal )decimal )decimal )decimal )decimal )bool )قم فقط بربط القيم التي وافقت على تقديمها تعاقديًا. ليس من الضروري استخدام كل الأساليب.
الاستدعاء الأخير الذي سيتم ربطه بالتسلسل هو ->build() الذي يقوم بإنشاء الكائن.
<?php
use Unidays ;
$ details = new DirectTrackingDetailsBuilder ( ' somePartnerId ' , ' order123 ' , ' GBP ' );
$ details -> withOrderTotal ( 209.00 );
$ details -> withItemsUnidaysDiscount ( 13.00 );
$ details -> withCode ( ' UNI123 ' );
$ details -> withItemsTax ( 34.50 );
$ details -> withShippingGross ( 5.00 );
$ details -> withShippingDiscount ( 3.00 );
$ details -> withItemsGross ( 230.00 );
$ details -> withItemsOtherDiscount ( 10.00 );
$ details -> withUnidaysDiscountPercentage ( 10.00 );
$ details -> withNewCustomer ( true );
$ directTrackingDetails = $ details -> build ();إذا وافقت على تزويد أعضاء UNiDAYS بتجربة بدون رموز، إلى جانب التتبع المباشر، فسوف تحتاج أيضًا إلى تنفيذ "Codeless API" التي ستساعدك في تحليل والتحقق من صحة حركة المرور الموقعة التي نوجهها نحو موقعك.
اتصل أولاً بـ CodelessUrlVerifier باستخدام المفتاح المقدم لك بواسطة UNiDAYS new CodelessUrlVerifier($key) . ثم قم باستدعاء الطريقة verify_url_params($ud_s, $ud_t, $ud_h) مع قيم ud_s، وud_t، وud_h كوسيطات.
| المعلمة | وصف | نوع البيانات | أقصى طول | مثال |
|---|---|---|---|---|
| ud_s | UNiDAYS هوية الطالب التي تم التحقق منها | خيط | 256 حرفًا | فعل/faqh330SGgCnn4t3X4g== |
| ud_t | الطابع الزمني للطلب | خيط | 64 بت | 1395741712 |
| ud_h | توقيع التجزئة للمعلمتين الأخريين | سلسلة Base64 | 256 حرفًا | o9Cg3q2eVElZxYlJsEAQ== |
إذا نجحت الطريقة في التحقق من صحة تجزئة الطلب الوارد، فسيتم إرجاع التاريخ والوقت للطلب؛ وإلا سيتم إرجاع فارغة.
<?php
use Unidays ;
// Your key as provided by UNiDAYS
$ key = " someSigningKey " ;
// Obtain parameters from the query string. Be sure to URL Decode them
$ ud_s = " Do/faqh330SGgCnn4t3X4g== " ;
$ ud_t = " 1395741712 " ;
$ ud_h = " i38dJdX+XLKuE4F5tv+Knpl5NPtu5zrdsjnqBQliJEJE4NkMmfurVnUaT46WluRYoD1/f5spAqU36YgeTMCNeg== " ;
$ verifier = new CodelessUrlVerifier ( $ key );
$ verifiedAt = $ verifier -> verify_url_params ( $ ud_s , $ ud_t , $ ud_h );تم إعداد هذا المشروع كمشروع مفتوح المصدر. على هذا النحو، إذا كانت لديك أي اقتراحات بشأن الميزات، أو لتحسين الكود نفسه، أو واجهت أي مشاكل؛ يمكنك رفعها و/أو اقتراح تغييرات في التنفيذ.
إذا كنت مهتمًا بالمساهمة في قاعدة التعليمات البرمجية هذه، فيرجى اتباع إرشادات المساهمة. يحتوي هذا على أدلة حول المساهمة المباشرة ورفع طلبات الميزات أو تقارير الأخطاء. يرجى الالتزام بقواعد السلوك لدينا عند القيام بأي مما سبق.
