وثائق نبوكس ناو API
مقدمة
تم تصميم انبوكس ناو API للتكامل السلس مع موقع التجارة الإلكترونية الخاص بك مع نظام انبوكس ناو، مما يمكّن من حسابات أسعار الشحن التلقائية وإدارة الطلبات. عند التكامل، سيتمكن المستخدمون من:
- استرداد أسعار الشحن في الوقت الفعلي من انبوكس ناو بناءً على أبعاد المنتج ووجهات الشحن.
- دفع معلومات المتجر والطلبات إلى انبوكس ناو للتنفيذ المبسط وخدمات الشحن.
من خلال الاستفادة من هذا API، يمكن للتجار تحسين سير عمل الشحن وتقليل المعالجة اليدوية وضمان المعالجة الفعالة للطلبات.
عناوين URL الأساسية
استخدم عنوان URL الأساسي المناسب حسب بيئتك:
- مباشر (الإنتاج):
https://nbox.now/api - التجريبي (الاختبار):
https://staging.nbox.now/api
فيما يلي قائمة بـ APIs التي ستستخدمها للتكامل مع انبوكس ناو. تسمح هذه النقاط النهائية بالمصادقة وإدارة المواقع واسترداد أسعار الشحن والتعامل مع الطلبات داخل النظام.
API تسجيل الدخول
سجل الدخول إلى النظام عن طريق استدعاء نقطة نهاية المصادقة:
يتم إرجاع رمز مميز عند نجاح المصادقة ويجب استخدامه في طلبات API الأخرى.
الطريقة: POST
نقطة النهاية: POST https://{base_url}/login
الطلب
يجب تضمين المعاملات التالية في نص الطلب:
| الاسم | النوع | مطلوب | الوصف |
|---|---|---|---|
| String | Required | عنوان البريد الإلكتروني للمستخدم (مثال: juan.delacruz@email.com) | |
| password | String | Required | كلمة مرور المستخدم (مثال: *******) |
| shopId | String | Required | المعرف الفريد للمتجر (النطاق) (مثال: nbox.now) |
| shopName | String | Required | اسم المتجر (مثال: Nbox Store) |
| platform | String | Required | منصة التجارة الإلكترونية (مثال: WooCommerce، Shopify، Magento، مخصص) (مثال: woocommerce) |
| url | String | Required | رابط المتجر (مثال: https://store.nbox.now) |
| locations | Array of Objects | Optional | حقل اختياري ويمكن أن يتضمن مواقع تنفيذ المتجر. مواقع المتجر (مثال: address: 143 Missing Street, Unknown area, city: Al Rayyan, state: Qatar, countryCode: QA, zip: 0000, country: Qatar) |
الاستجابة
| الحالة | الوصف |
|---|---|
| 200 OK | نجح أو فشل التفعيل بناءً على المعاملات المقدمة |
| 400 Bad Request | معاملات مفقودة أو غير صالحة |
| 401 Unauthorized | رمز مميز و/أو نطاق متجر غير صالح |
| 500 Internal Server Error | خطأ في الخادم أثناء عملية التفعيل |
API المواقع
لإدارة المواقع في نظام انبوكس ناو، يمكنك استخدام نقاط النهاية التالية. كلاهما يقبل نفس نص الطلب الذي يحتوي على مصفوفة من معلومات الموقع.
تأكد من تضمين الرمز المميز ونطاق المتجر في رؤوس الطلب. سيقوم API بالتحقق من صحة هذه لضمان أن الطلب قادم من متجر مخول. يمكن توفير المواقع في معلومة واحدة أو مصفوفة من معلومات الموقع، اعتماداً على المنصة. lat و lng الحقول اختيارية ولكن يمكن تضمينها إذا كانت الإحداثيات الجغرافية للموقع معروفة.
الطريقة: POST
نقطة النهاية:
POST https://{base_url}/locations/add- إضافة مواقع جديدة.POST https://{base_url}/locations/update- تحديث المواقع الموجودة.
الرؤوس
| الاسم | الوصف |
|---|---|
x-nbox-shop-token | الرمز المميز المسترد من API تسجيل الدخول. هذا الرمز يصادق على المستخدم. |
x-nbox-shop-domain | نطاق موقع التجارة الإلكترونية (مثال: nbox.nowمرتبط بالمتجر. |
الطلب
| الاسم | النوع | مطلوب | الوصف (مع مثال) |
|---|---|---|---|
| refId | String | Required | معرف مرجعي فريد للموقع (مثال: "loc123") |
| refName | String | Required | اسم مرجعي فريد لعرض الموقع (مثال: "المستودع الرئيسي") |
| address | String | Required | عنوان الشارع للموقع (مثال: "123 Main St") |
| city | String | Required | مدينة الموقع (مثال: "نيويورك") |
| state | String | Required | الولاية أو المحافظة للموقع (مثال: "نيويورك") |
| countryCode | String | Required | رمز البلد المكون من حرفين (مثال: "US") |
| country | String | Optional | اسم البلد (مثال: "الولايات المتحدة") |
| zip | String | Required | الرمز البريدي للموقع (مثال: "10001") |
| longitude | Number | Optional | خط الطول للموقع (مثال: "-73.935242") |
| latitude | Number | Optional | خط العرض للموقع (مثال: "40.730610") |
الاستجابة
| الحالة | الوصف |
|---|---|
| 200 OK | نجح أو فشل التفعيل بناءً على المعاملات المقدمة |
| 400 Bad Request | معاملات مفقودة أو غير صالحة |
| 401 Unauthorized | رمز مميز و/أو نطاق متجر غير صالح |
| 500 Internal Server Error | خطأ في الخادم أثناء عملية التفعيل |
API التفعيل
الطريقة: POST
نقطة النهاية: POST https://{base_url}/activation
الرؤوس
| الاسم | الوصف |
|---|---|
x-nbox-shop-token | الرمز المميز المسترد من API تسجيل الدخول. هذا الرمز يصادق على المستخدم. |
x-nbox-shop-domain | نطاق موقع التجارة الإلكترونية (مثال: nbox.nowمرتبط بالمتجر. |
الطلب
| الاسم | النوع | مطلوب | الوصف (مع مثال) |
|---|---|---|---|
| activate | Boolean | Required | ما إذا كان سيتم تفعيل المتجر (صحيح أو خطأ) (مثال: true |
| locations | Array | Optional | مصفوفة من معلومات الموقع المراد تفعيلها (مثال: [{"refId": "loc123", "refName": "Main Warehouse", "address": "123 Main St", "city": "New York", "state": "NY", "zip": "10001", "countryCode": "US", "country": "United States"}]) |
الاستجابة
| الحالة | الوصف |
|---|---|
| 200 OK | نجح أو فشل التفعيل بناءً على المعاملات المقدمة |
| 400 Bad Request | معاملات مفقودة أو غير صالحة |
| 401 Unauthorized | رمز مميز و/أو نطاق متجر غير صالح |
| 500 Internal Server Error | خطأ في الخادم أثناء عملية التفعيل |
أسعار API
الطريقة: POST
نقطة النهاية: POST https://{base_url}/rates
الرؤوس
| الاسم | الوصف |
|---|---|
x-nbox-shop-token | الرمز المميز المسترد من API تسجيل الدخول. هذا الرمز يصادق على المستخدم. |
x-nbox-shop-domain | نطاق موقع التجارة الإلكترونية (مثال: nbox.nowمرتبط بالمتجر. |
الوصف
يحسب هذا API أسعار الشحن بناءً على تفاصيل المنتج والمنشأ والوجهة. يحسب النظام بذكاء الأبعاد والوزن من المنتجات الفردية لحساب دقيق للأسعار. معاملات الوزن/الحجم القديمة مدعومة للتوافق مع الإصدارات السابقة.
الطلب
موصى به: استخدم products مصفوفة لحسابات الوزن الأبعاد الدقيقة. سيحسب النظام الوزن والحجم الإجمالي من مواصفات المنتجات الفردية.
هيكل الطلب الرئيسي
| الاسم | النوع | مطلوب | الوصف |
|---|---|---|---|
| products | Array | Recommended | قائمة المنتجات مع الأبعاد والوزن للحساب الدقيق |
| volume | Number | Legacy | (Legacy) حجم الطرد بالوحدات المكعبة (مثال:Legacy) 1.5 |
| weight | Number | Legacy | (Legacy) وزن الطرد بالكيلوغرام (مثال:Legacy) 2.5 |
| origin | Object | Required | معلومات موقع المنشأ (انظر معلومات المنشأ والوجهة أدناه) |
| destination | Object | Required | معلومات موقع الوجهة (انظر معلومات المنشأ والوجهة أدناه) |
| type | String | Optional | نوع الشحن (مثال: "non_document", "document", إلخ. الافتراضي هو "non_document"غير وثائقي |
Product Object (Recommended)
| الاسم | النوع | مطلوب | الوصف |
|---|---|---|---|
| name | String | Required | اسم المنتج |
| quantity | Number | Required | كمية المنتج |
| price | Number | Required | سعر الوحدة الواحدة من المنتج |
| grams | Number | Required | وزن المنتج بالغرام |
| length | Number | Required | طول المنتج بالسنتيمتر |
| width | Number | Required | عرض المنتج بالسنتيمتر |
| height | Number | Required | ارتفاع المنتج بالسنتيمتر |
| volume | Number | Required | حجم المنتج بالسنتيمتر المكعب (سم³) |
| currency | String | Required | عملة سعر المنتج |
معلومات المنشأ والوجهة
| الاسم | النوع | مطلوب | الوصف |
|---|---|---|---|
| address | String | Required | العنوان الكامل، بما في ذلك سطور العنوان وأي معلومات عنوان إضافية |
| city | String | Required | المدينة |
| state | String | Optional | الولاية أو المحافظة (يقبل null للمناطق بدون ولايات) |
| countryCode | String | Required | رمز البلد (مثال: "US"، "QA") |
| country | String | Optional | اسم البلد (مثال: "الولايات المتحدة"، "قطر") |
| zip | String | Required | الرمز البريدي |
| longitude | Number | Optional | خط الطول للعنوان (يدعم تنسيقي longitude و lng) |
| latitude | Number | Optional | خط العرض للعنوان (يدعم تنسيقي latitude و lat) |
الاستجابة
| الحالة | الوصف |
|---|---|
| 200 OK | نجح أو فشل التفعيل بناءً على المعاملات المقدمة |
| 400 Bad Request | معاملات مفقودة أو غير صالحة |
| 401 Unauthorized | رمز مميز و/أو نطاق متجر غير صالح |
| 500 Internal Server Error | خطأ في الخادم أثناء عملية التفعيل |
نص الاستجابة
سيحتوي نص الاستجابة على مصفوفة من معلومات الأسعار، بالهيكل التالي:
| الاسم | النوع | الوصف |
|---|---|---|
| id | String | معرف فريد للسعر (مثال: "f9d17f56-7eeb-44ad-bc7e-b95f61d5d2ed" |
| logo | String | رابط شعار مقدم الخدمة (مثال: "/images/nbox-logistics.png" |
| pickup_dropoff_method | String | طريقة الاستلام والتسليم (مثال: "Door to Door" |
| service_name | String | اسم خدمة الشحن (مثال: "NBOX Express Local Delivery" |
| service_code | String | رمز خدمة الشحن (مثال: "NBOX" |
| total_price | Number | السعر الإجمالي للخدمة بالعملة المحددة (مثال: 20.00 |
| description | String | وصف للخدمة، مثل وقت التسليم (مثال: "Estimate Time of Delivery: 3 hours" |
| currency | String | عملة السعر الإجمالي (مثال: "QAR" |
طلب API
الطريقة: POST
نقطة النهاية: POST https://{base_url}/order
الوصف
يتم استدعاء هذا API أثناء عملية الدفع في موقع التجارة الإلكترونية. يدفع تفاصيل الطلب من متجر التجارة الإلكترونية إلى نظام انبوكس ناو للمعالجة. سيتعامل النظام مع مهام مثل حساب تكلفة الشحن وتحديث حالة الطلب وإنشاء إشعارات البريد الإلكتروني لفريق العمليات والمستخدم.
الرؤوس
| الاسم | الوصف |
|---|---|
x-nbox-shop-token | الرمز المميز المسترد من API تسجيل الدخول. هذا الرمز يصادق على المستخدم. |
x-nbox-shop-domain | نطاق موقع التجارة الإلكترونية (مثال: nbox.nowمرتبط بالمتجر. |
الطلب
يجب أن يحتوي نص الطلب على تفاصيل الطلب، بما في ذلك الناقل وتفاصيل العميل والوجهة ومعلومات المنتج. فيما يلي هيكل بيانات الطلب:
هيكل المعلومات الرئيسي
| الاسم | النوع | مطلوب | الوصف |
|---|---|---|---|
| order | Object | Required | تفاصيل الطلب بما في ذلك الناقل ورقم الطلب والمجموع الفرعي ورسوم الشحن. |
| customer | Object | Required | معلومات العميل، بما في ذ لك الاسم والبريد الإلكتروني والهاتف. |
| origin | Object | Required | عنوان منشأ متجر التجارة الإلكترونية (المتجر). يتضمن العنوان والمدينة والولاية والرمز البريدي. |
| destination | Object | Required | تفاصيل وجهة الشحن، بما في ذلك عنوان المستلم والمدينة والولاية والرمز البريدي. |
| products | Array | Required | قائمة المنتجات في الطلب مع خصائص مثل الاسم والسعر والكمية والوزن والأبعاد والحجم. |
معلومات الطلب
| الاسم | النوع | مطلوب | الوصف |
|---|---|---|---|
| shopDomain | String | Required | نطاق متجر التجارة الإلكترونية |
| carrier | String | Required | ناقل الشحن للطلب |
| subTotal | Number | Required | مبلغ المجموع الفرعي للطلب |
| orderNumber | Number | Required | رقم الطلب الفريد |
| orderReference | String | Required | رقم مرجعي للطلب |
| total | Number | Required | المبلغ الإجمالي للطلب |
| currency | String | Required | عملة الطلب |
| shippingFee | Number | Required | رسوم الشحن للطلب |
معلومات العميل
| الاسم | النوع | مطلوب | الوصف |
|---|---|---|---|
| firstName | String | Required | الاس م الأول للعميل |
| lastName | String | Required | اسم العائلة للعميل |
| String | Required | عنوان البريد الإلكتروني للعميل | |
| phone | String | Optional | رقم هاتف العميل |
معلومات المنشأ والوجهة
| الاسم | النوع | مطلوب | الوصف |
|---|---|---|---|
| address | String | Required | العنوان الكامل، بما في ذلك سطور العنوان وأي معلومات عنوان إضافية |
| city | String | Required | المدينة |
| state | String | Optional | الولاية أو المحافظة (يقبل null للمناطق بدون ولايات) |
| countryCode | String | Required | رمز البلد (مثال: "US"، "QA") |
| country | String | Optional | اسم البلد (مثال: "الولايات المتحدة"، "قطر") |
| zip | String | Required | الرمز البريدي |
| longitude | Number | Optional | خط الطول للعنوان (يدعم تنسيقي longitude و lng) |
| latitude | Number | Optional | خط العرض للعنوان (يدعم تنسيقي latitude و lat) |
Product Object
| الاسم | النوع | مطلوب | الوصف |
|---|---|---|---|
| name | String | Required | اسم المنتج |
| quantity | Number | Required | كمية المنتج |
| price | Number | Required | سعر الوحدة الواحدة من المنتج |
| grams | Number | Required | وزن المنتج بالغرام |
| length | Number | Required | طول المنتج بالسنتيمتر |
| width | Number | Required | عرض المنتج بالسنتيمتر |
| height | Number | Required | ارتفاع المنتج بالسنتيمتر |
| volume | Number | Required | حجم المنتج بالسنتيمتر المكعب (سم³) |
| currency | String | Required | عملة سعر المنتج |
الاستجابة
| الحالة | الوصف |
|---|---|
| 200 OK | نجح أو فشل التفعيل بناءً على المعاملات المقدمة |
| 400 Bad Request | معاملات مفقودة أو غير صالحة |
| 401 Unauthorized | رمز مميز و/أو نطاق متجر غير صالح |
| 500 Internal Server Error | خطأ في الخادم أثناء عملية التفعيل |
نص الاستجابة
سيحتوي نص الاستجابة على الحقول التالية:
| الاسم | النوع | الوصف |
|---|---|---|
| message | String | رسالة الحالة التي تشير إلى النجاح أو الفشل |
| orderId | String | معرف الطلب الفريد |
| errorDetails | String | أي تفاصيل خطأ إذا لم تتم معالجة الطلب بنجاح |
API الإنجاز
الطريقة: POST
نقطة النهاية: POST https://{base_url}/fulfilled
الوصف
يتم استدعاء هذا API عندما يتم إنجاز الطلب (شحنه). يدفع حالة إنجاز الطلب من متجر التجارة الإلكترونية إلى نظام انبوكس ناو لمزيد من المعالجة، مثل تحديث حالة الطلب أو إخطار العميل.
الرؤوس
| الاسم | الوصف |
|---|---|
x-nbox-shop-token | الرمز المميز المسترد من API تسجيل الدخول. هذا الرمز يصادق على المستخدم. |
x-nbox-shop-domain | نطاق موقع التجارة الإلكترونية (مثال: nbox.nowمرتبط بالمتجر. |
الطلب
يجب تضمين المعاملات التالية في نص الطلب:
| الاسم | النوع | مطلوب | الوصف |
|---|---|---|---|
| orderNumber | Number | Required | رقم الطلب الفريد |
الاستجابة
| الحالة | الوصف |
|---|---|
| 200 OK | نجح أو فشل التفعيل بناءً على المعاملات المقدمة |
| 400 Bad Request | معاملات مفقودة أو غير صالحة |
| 401 Unauthorized | رمز مميز و/أو نطاق متجر غير صالح |
| 500 Internal Server Error | خطأ في الخادم أثناء عملية التفعيل |
نص الاستجابة
| الاسم | النوع | الوصف |
|---|---|---|
| message | String | رسالة الحالة التي تشير إلى النجاح أو الفشل |
| orderId | String | معرف الطلب الفريد |
| errorDetails | String | أي تفاصيل عن الأخطاء في حال عدم معالجة التنفيذ بنجاح |
إلغاء API
الطريقة: POST
نقطة النهاية: POST https://{base_url}/order/cancelled
الوصف
يتم استدعاء هذا API عندما يتم إلغاء الطلب. يرسل حالة الإلغاء من متجر التجارة الإلكترونية إلى نظام نبوكس ناو لمزيد من المعالجة، مثل تحديث حالة الطلب وإخطار العميل بالإلغاء.
الرؤوس
| الاسم | الوصف |
|---|---|
x-nbox-shop-token | الرمز المميز المسترد من API تسجيل الدخول. هذا الرمز يصادق على المستخدم. |
x-nbox-shop-domain | نطاق موقع التجارة الإلكترونية (مثال: nbox.nowمرتبط بالمتجر. |
الطلب
| الاسم | النوع | مطلوب | الوصف |
|---|---|---|---|
| orderNumber | Number | Required | رقم الطلب الفريد |
الاستجابة
| الحالة | الوصف |
|---|---|
| 200 OK | نجح أو فشل التفعيل بناءً على المعاملات المقدمة |
| 400 Bad Request | معاملات مفقودة أو غير صالحة |
| 401 Unauthorized | رمز مميز و/أو نطاق متجر غير صالح |
| 500 Internal Server Error | خطأ في الخادم أثناء عملية التفعيل |