التفويض

في هذه المرحلة نفترض أنك شريك Bonder وقسم الدعم الخاص بنا كان قد سلم اليك اسم المستخدم، كلمة السر واسم العميل API.
  • أمر auth
  • طلب POST
curl -k -X POST \
-H "Content-Type : application/json" \
-H "Accept : application/json" \
-d '{
  "username" : "USERNAME",
  "password" : "PASSWORD",
  "client" : "API_CLIENT_NAME",
  "rpt" : "10000"
}' \
"https:// {{API_URL}} /auth" \
معلمات التفويض
معامل
نوع
وصف
username
string
اسم المستخدم API
password
string
كلمة السر لـAPI
client
string
اسم العميل API
rpt
integer
عدد العمليات token الواحد (RPT - Requests Per Token) rpt<1000, 100000>
نجاح HTTP/1.1 200 OK
{
  "success" : true,
  "errors" : [],
  "result" : {
    "token" : "access_token",
    "expire" : "1601382431"
  }
}
الإجابة
معامل
نوع
وصف
token
string
token الخاص بك
expire
integer
علامة الوقت التي تحتوي على تاريخ انتهاء صلاحية token expire=time()+3600
يتنافس المتغيران expire وrpt. المتغير الأول الذي يصل الى القيمة المستهدفة يعطل token.
فشل HTTP/1.1 200 OK
{
  "success" : false,
  "errors" : [رمز-الخطأ],
  "result" : {}
}
رمز-الخطأ
خطأ
وصف
INVALID_CREDENTIALS_ERROR
كلمة السر غير صحيحة، عنوان البريد الإلكتروني غير صحيح أو تم حذف الحساب أو الحساب غير موجود
SERVER_OFFLINE_ERROR
الخادم ليس متصلا بسبب أعمال الصيانة الجارية.
من الممكن تحديث البرمجيات
  • النصيحة: يرجى اعادة المحاولة بعد 45-60 دقيقة
AUTH_SERVICE_OFFLINE_ERROR
خدمة التفويض ليست متاحة لجميع المستخدمين.
من الممكن تحديث البرمجيات
  • النصيحة: يرجى اعادة المحاولة بعد 45-60 دقيقة
API_SERVICE_OFFLINE_ERROR
خدمة API ليست متاحة مؤقتاً.
من الممكن تحديث البرمجيات
  • النصيحة: يرجى اعادة المحاولة بعد 45-60 دقيقة
ACCOUNT_INACTIVE_ERROR
تم تعليق حساب API أو تم توجيهه الى الحذف
  • نصيحة: الاتصال بقسم الدعم
INTERNAL_SERVER_ERROR
خطأ داخلي للخادم
  • النصيحة: يرجى اعادة المحاولة
DATABASE_ERROR
خطأ الاتصال بقاعدة البيانات
  • النصيحة: يرجى اعادة المحاولة

هيكل البيانات

فبل أن نتابع الى خدمة الأوامر الأخرى، نود أن نوضح لك هيكل البيانات المستخدمة من قبل Bonder.

أنواع البيانات

أنواع البيانات
نوع
وصف
متعدد اللغات
يجب أن تكون مسجلة بشكل منفصل لكل لغة
ثابتة
يتم تخزينها في الجدول المنفصل وإضافتها الى بطاقة العمل في كل لغة
على سبيل المثال: في حال قيامك بتغيير القيمة من النوع الثابت مثل email أو mobile فيتم تحديث جميع بطاقات العمل في كافة النسخ اللغوية.

أساليب بطاقات العمل

نظراً إلى أن عميلك قد لا يكون شخصًا طبيعيًا ولكن مؤسسة على سبيل المثال باسم خدمات-طبيب-الأسنان-غير-المخيفة، فقد قمنا بإنشاء متغير المستوى الأعلى displayName. في حالة !empty(displayName) فسوف تعمل بطاقة العمل في أسلوب الأعمال وسوف يتم إهمال متغيرات name lastname position أثناء إنشاء بطاقة العمل (و مع ذلك سيظل الخادم يحتفظ بالقيم).
أساليب بطاقات العمل
الأسلوب
الشرط
الأعمال
if (!empty(displayName)) {
businessMode = TRUE
}
الشخصي
if (empty(displayName)) {
businessMode = FALSE
}
في النسخة الإنكليزية للمتغير displayName قيمة معينة، لذا سيقوم الخادم بحفظ البيانات المرسلة ولكن ستهمل name lastname position خلال إنشاء بطاقة العمل. "en" : {
  "displayName" : "Non-scary-dental-services",
  "name" : "John",
  "lastname" : Kowalski",
  "position" : "CEO"
},
في النسخة البولندية سيتم عرض اسم Jan Kowalski (ومنصبه الرئيس التنفيذي) على شاشة الجهاز المحمول. "pl" : {
  "displayName" : "",
  "name" : "Jan",
  "lastname" : "Kowalski",
  "position" : "Prezes"
},
النسخة الروسية ستكون غير متوفرة للتنزيل على الرغم من تخزين جزء من البيانات في الخادم. "ru" : {
  "displayName" : "",
  "name" : "",
  "lastname" : "Ковалский",
  "position" : "Директор"
}

المتغيرات

يجب التحقق من صحة كل متغير قبل إرساله إلى الخادم إذا كانت قيمة المتغير المرسل لا تتماشى مع التعبير العادي المعين له، فسوف يقوم الخادم بتعيينه null (قيمة خالية)، وعلى الرغم من ذلك سيعطي الإجابة الإيجابية بالنسبة لحفظ البيانات success=true.
المتغيرات
اسم
نوع
متعدد اللغات
وصف
name
string
الاسم
  • مطلوبة لإنشاء بطاقة العمل في النمط الشخصي
  • تم حفظه وتجاهله في أسلوب الأعمال
  • /^[a-zA-Z0-9]{2,25}$/
lastname
string
اللقب
  • تم حفظه وتجاهله في أسلوب الأعمال
  • تم حفظه وتجاهله في أسلوب الأعمال
  • /^[a-zA-Z0-9]{32,128}$/
displayName
string
الاسم المعروض
  • مطلوب لإنشاء البطاقة في نمط الأعمال
  • /^[a-zA-Z0-9]{32,128}$/
company
string
اسم الشركة
  • /^[a-zA-Z0-9]{32,128}$/
position
string
المنصب
  • تم حفظه وتجاهله في أسلوب الأعمال
  • /^[a-zA-Z0-9]{32,128}$/
keywords
string
الكلمات الرئيسية التي تصف الشخص أو الشركة بأفضل طريقة
  • الفاصلة بين الكلمات الرئيسية
  • /^[a-zA-Z0-9]{1,150}$/
thumbnail
string
صورة المستخدم أو الشعار الذي يتم عرضه على الجهاز المحمول
  • تم حفظ الصورة في base64
  • الحجم الثابت 300px x 300px
  • الحد الأقصى لحجم الملف 50 كيلوبايت
phoneA
string
رقم الهاتف
  • يتم قطع الأصفار البادئة والعلامات غير الرقمية
  • يجب على العميل إدخال مفتاح الدولة
  • نحن نقوم بإضافة ((+)) في البداية
  • /^[a-zA-Z0-9]{32,128}$/
phoneB
string
كما هو مذكور أعلاه
mobileA
string
رقم الهاتف المحمول
  • يتم قطع الأصفار البادئة والعلامات غير الرقمية
  • يجب على العميل إدخال مفتاح الدولة
  • نحن نقوم بإضافة ((+)) في البداية
  • /^[a-zA-Z0-9]{32,128}$/
mobileB
string
كما هو مذكور أعلاه
skypeA
string
اسم مستخدم سكايب
  • /^[a-zA-Z0-9]{32,128}$/
skypeB
string
كما هو مذكور أعلاه
faxA
string
رقم الفاكس
  • يتم قطع الأصفار البادئة والعلامات غير الرقمية
  • يجب على العميل إدخال مفتاح الدولة
  • نحن نقوم بإضافة ((+)) في البداية
  • /^[a-zA-Z0-9]{32,128}$/
faxB
string
كما هو مذكور أعلاه
emailA
string
عنوان البريد الإلكتروني
emailB
string
كما هو مذكور أعلاه
webA
string
URL
  • /^[a-zA-Z0-9]{32,128}$/
webB
string
كما هو مذكور أعلاه
webC
string
كما هو مذكور أعلاه
addrStreet
string
العنوان - الشارع
  • /^[a-zA-Z0-9]{32,128}$/
addrCity
string
العنوان - المدينة
  • /^[a-zA-Z0-9]{32,128}$/
addrState
string
العنوان - المحافظة
  • /^[a-zA-Z0-9]{32,128}$/
addrZip
string
العنوان - الرمز البريدي
  • /^[a-zA-Z0-9]{32,128}$/
addrCountry
string
العنوان - الدولة
  • /^[a-zA-Z0-9]{32,128}$/

المعلمات

المعلمات
متغير
نوع
وصف
langStatus
integer
0 = off, 1 = on
تشغيل / إيقاف النسخة اللغوية دون حذف البيانات
  • default = 0
usePhoto
integer
0 = off, 1 = on
تشغيل / إيقاف الصورة دون حذفها
  • default = 1
cardStatus
integer
0 = off, 1 = on
تشغيل / إيقاف بطاقة العمل دون حذفها
  • default = 1

الدعم اللغوي

يسمح Bonder لعملائه بإنشاء بطاقات العمل في أكثر من 60 لغة وهذه الوظيفة الرئيسية متوفرة أيضاً لمستخدمي API. من أجل راحتك قمنا بتحضير المستودعات التي تحتوي على رموز اللغات المترجمة والمدعومة من قبل Bonder الجاهزة للاستخدام خلال تشكيل التطبيق الخاص بك. لإدارة النسخة اللغوية نستخدم المتغير lang. سوف تستخدمه لإضافة، وتعديل وحذف النسخ اللغوية.
  • أمر repositories
  • طلب GET
curl -k -X GET \
-H "X-Auth-Key : {{access_token}}" \
-H "X-Auth-Email : {{username}}" \
-H "Content-Type : application/json" \
-H "Accept : application/json" \
"https:// {{API_URL}} /repositories \
نجاح HTTP/1.1 200 OK
{
  "success": true,
  "errors" : [],
  "result" : {
    "langList" : [local, lang]
  }
}
langList
قيمة
نوع
وصف
lang
string
رمز اللغة متوافق مع ISO 639-1:2002
local
string
قائمة اسماء اللغات المحلية مثلا: en => English, ru => Русский
الإجابة المثالية يعيد الخادم قائمة الموارد المتوفرة: local، الإنكليزية، الروسية، البولندية، الصينية HTTP/1.1 200 OK
{
  "success": true,
  "errors" : [],
  "result" : {
    "langList" : ["local", "en", "ru", "pl", "zh"]
  }
}
استخدم القيمة من langList بهدف تنزيل الموارد المطلوبة. سوف تحصل على الإجابة بشكل المفتاح : القيمة دائماً.

تنزيل قائمة اسماء اللغات المحلية

  • أمر repositories
  • طلب GET
curl -k -X GET \
-H "X-Auth-Key : {{access_token}}" \
-H "X-Auth-Email : {{username}}" \
-H "Content-Type : application/json" \
-H "Accept : application/json" \
"https:// {{API_URL}} /repositories/local" \
نجاح HTTP/1.1 200 OK
{
  "success": true,
  "errors" : [],
  "result" : {
    "pl" : "Polski",
    "en" : "English",
    "ru" : "Русский",
    ...,
    "مفتاح" : "قيمة"
 }
}

تنزيل قائمة اسماء اللغات المترجمة

  • أمر repositories
  • طلب GET
قم بتغيير الاستفسار المذكور أعلاه على النحو التالي: "https:// {{API_URL}} /repositories/ru" \
"https:// {{API_URL}} /repositories/en" \
في حال لم تكن الموارد التي تبحث عنها متوفرة لدينا، قم بإبلاغ قسم الدعم. سنقوم بإستكمال النقص في أقرب وقت ممكن. إذا كنت لا تستطيع أن تنتظر ردنا فنوصي بتنزيل رموز اللغات المتوفرة والقيام بالترجمة بنفسك.
فشل HTTP/1.1 200OK
{
  "success" : false,
  "errors" : [رمز-الخطأ],
  "result" : {}
}
رمز-الخطأ
خطأ
وصف
INVALID_CREDENTIALS_ERROR
كلمة السر غير الصحيحة أو عنوان البريد الإلكتروني غير صحيح أو token غير صالح
  • النصائح: كرّر التفويض
RESOURCE_NOT_FOUND_ERROR
الموارد التي تبحث عنها ليست موجودة
  • النصيحة: تحقق من الاستفسار الذي أرسلته
أخرى
أنظر رمز-الخطأ في قسم التفويض

إنشاء ملف شخصي جديد

  • أمر users
  • طلب post
curl -k -X POST \
-H "X-Auth-Key : {{access_token}}" \
-H "X-Auth-Email : {{username}}" \
-H "Accept : application/json" \
"https:// {{API_URL}} /users" \
نجاح HTTP/1.1 200 OK
{
  "success": true,
  "errors" : [],
  "result" : {
    "cardId" : string,
    "cardQrc" : string,
    "cardAddr" : string (url)
  }
}
نتيجة الإستفسار
متغير
نوع
وصف
cardId
string
رقم بطاقة العمل الخاصة بالملف الشخصي الذي تم إنشاؤه
  • مع مراعاة الحروف الكبيرة والصغيرة
  • /^[a-zA-Z0-9]{32,128}$/
cardAddr
string
عنوان بطاقة العمل المنشأة
cardQrc
string
تم حفظ رمز الاستجابة السريعة QR في base64
يجب تخزين مغيرات cardId cardQrc cardAddr محلياً على الخادم الخاص بك وتعيينها الى للملف الشخصي. المتغير cardId ضروري للاتصال الصحيح بـAPI.
فشل HTTP/1.1 200 OK
{
  "success" : false,
  "errors" : [رمز-الخطأ],
  "result" : {}
}
رمز-الخطأ
خطأ
وصف
INVALID_CREDENTIALS_ERROR
كلمة السر غير الصحيحة أو عنوان البريد الإلكتروني غير صحيح أو token غير صالح
  • النصائح: كرّر التفويض
PROFILE_LIMIT_REACHED_ERROR
تم استنفاذ الملفات الشخصية
  • النصيحة: الاتصال بقسم الدعم بهدف تغيير اعدادات الحساب
أخرى
أنظر رمز-الخطأ في قسم التفويض

حفظ البيانات

  • لا نستخدم نماذج الاستفسار الثابتة. أرسل فقط البيانات التي تتطلب التحديث.
  • استخدم أمر PUT لإنشاء ملف شخصي جديد.
  • أضف اللغة باستخدام مفاتيح lang في قسم translatable.
  • إذا كان العميل لا يريد أن يحدد النسخة اللغوية فقم باختيار lang=un ما يعني اللغة العالمية.
  • تعديل خمس لغات كحد أقصى في الاستفسار الواحد (التحديث والإضافة). سيتم تجاهل أي لغة إضافية فوق الـ 5 لغات.
  • أمر users
  • طلب put
curl -k -X PUT \
-H "X-Auth-Key : {{access_token}}" \
-H "X-Auth-Email : {{username}}" \
-H "Content-Type : application/json" \
-H "Accept : application/json" \
-d ' {
في حالة cardStatus=0 سيتم إيقاف بطاقة العمل ولن يكون تنزيلها ممكناً.   "settings" : {
    "cardStatus" : "0",
    "usePhoto" : "1"
  },
  "translatable" : {
استخدم langStatus لتشغيل وإيقاف تشغيل اللغات.     "pl" : {
      "name" : "John",
      "lastname" : "Connor",
      "position" : "Dyrektor Zarządzający"
    },
عند إضافة لغة جديدة، سنقوم بتعيين langStatus=0 بشكل افتراضي. يمكنك تجاوز هذا الإعداد عن طريق تعيين langStatus=1 عند إضافة اللغة.     "en" : {
      "name" : "John",
      "lastname" : "Connor",
      "position" : "Managing Director",
      "displayName" : "The Great John Connor",
      "keywords" : "steel, steel pipe, tubular products"
    },
على الرغم من اختيار langStatus=1 فإن اللغة المحددة لن تكون جاهزة للتحميل حتى يتم تلبية الشرط(name!=null && lastname!=null) || displayName!=null     "es" : {
      "langStatus" : "1",
      "name" : "John",
      "position" : "Director Ejecutivo"
    },
    "pt" : {
      "langStatus" : "1",
      "name" : "John",
      "lastname" : "Connor",
    },
    "ru" : {
      "langStatus" : "1",
      "name" : "",
      "lastname" : "Коннор",
    },
    "zh" : {
      "position" : "首席执行官"
    }
  },
  "non-translatable" : {
    "thumbnail" : "base64_encoded_image",
    "mobileA" : "123456789",
    "emailB" : "[email protected]"
  }
}
' \
"https:// {{API_URL}} /users/{{card_id}} \
نجاح HTTP/1.1 200 OK
{
  "success": true,
  "errors" : [رمز-الخطأ],
  "result" : {}
}
على الرغم من إعادة success=true يمكن للخادم أن يعلن خطأ عندما تضيف صورة الملف الشخصي الى الاستفسار.
رمز-الخطأ
خطأ
وصف
THUMBNAIL_REJECTED_ERROR
تم حفظ البيانات ولكن تم رفض الصورة المرسلة من قبل الخادم
  • النصيحة: تحقق من مولد الصور
فشل HTTP/1.1 200 OK
{
  "success" : false,
  "errors" : [رمز-الخطأ],
  "result" : {}
}
رمز-الخطأ
خطأ
وصف
INVALID_CREDENTIALS_ERROR
كلمة السر غير الصحيحة أو عنوان البريد الإلكتروني غير صحيح أو token غير صالح
  • النصائح: كرّر التفويض
CARD_ID_NOT_FOUND_ERROR
بطاقة العمل cardId ليست موجودة أو ليس لديك إذن بتعديل هذه الموارد
  • النصيحة: تحقق من الاستفسار الذي أرسلته
أخرى
أنظر رمز-الخطأ في قسم التفويض

تعديل الاعدادات

المعلمات
معامل
نوع
وصف
status
string
<enable, disable>

تغيير حالة بطاقة العمل

  • أمر users
  • طلب put
curl -k -X PUT \
-H "X-Auth-Key : {{access_token}}" \
-H "X-Auth-Email : {{username}}" \
-H "Content-Type : application/json" \
-H "Accept : application/json" \
https:// {{API_URL}} /users/{{card_id}}/cardStatus/{{status}}

تغيير حالة الصورة

  • أمر users
  • طلب put
curl -k -X PUT \
-H "X-Auth-Key : {{access_token}}" \
-H "X-Auth-Email : {{username}}" \
-H "Content-Type : application/json" \
-H "Accept : application/json" \
https:// {{API_URL}} /users/{{card_id}}/usePhoto/{{status}}

تغيير حالة اللغة

  • أمر users
  • طلب put
curl -k -X PUT \
-H "X-Auth-Key : {{access_token}}" \
-H "X-Auth-Email : {{username}}" \
-H "Content-Type : application/json" \
-H "Accept : application/json" \
https:// {{API_URL}} /users/{{card_id}}/langStatus/{{lang}}/{{status}}
نجاح HTTP/1.1 200 OK
{
  "success" : true,
  "errors" : [],
  "result" : {}
}
فشل HTTP/1.1 200 OK
{
  "success" : false,
  "errors" : [رمز-الخطأ],
  "result" : {}
}
رمز-الخطأ
خطأ
وصف
الكل
أنظر رمز-الخطأ في قسم حفظ البيانات

تنزيل البيانات

  • أمر users
  • طلب get
curl -k -X GET \
-H "X-Auth-Key : {{access_token}}" \
-H "X-Auth-Email : {{username}}" \
-H "Content-Type : application/json" \
-H "Accept : application/json" \
"https:// {{API_URL}} /users/{{card_id}}" \
نجاح HTTP/1.1 200 OK
{
"success": true,
"errors" : [],
"result" : {
  "translatable" : {
    "lang" : {
      "langStatus" : "1",
      "مفتاح" : "قيمة"
    },
    "lang" : {
      "langStatus" : "0",
      "مفتاح" : "قيمة"
    }
  },
  "non-translatable" : {
    "thumbnail" : "base64_encoded_image",
    "مفتاح" : "قيمة"
  },
  "settings" : {
    "cardStatus" : "1",
    "usePhoto" : "1",
    "cardQrc" : "base64_encoded_image",
    "cardAddr" : "URL",
    "usePhoto" : "1"
  }

}
فشل HTTP/1.1 200 OK
{
  "success" : false,
  "errors" : [رمز-الخطأ],
  "result" : {}
}
رمز-الخطأ
خطأ
وصف
INVALID_CREDENTIALS_ERROR
كلمة السر غير الصحيحة أو عنوان البريد الإلكتروني غير صحيح أو token غير صالح
  • النصائح: كرّر التفويض
CARD_ID_NOT_FOUND_ERROR
بطاقة العمل cardId ليست موجودة أو ليس لديك إذن بتعديل هذه الموارد
  • النصيحة: تحقق من الاستفسار الذي أرسلته
أخرى
أنظر رمز-الخطأ في قسم التفويض

حذف البيانات

حذف اللغة

  • أمر users
  • طلب delete
curl -k -X DELETE \
-H "X-Auth-Key : {{access_token}}" \
-H "X-Auth-Email : {{username}}" \
-H "Content-Type : application/json" \
-H "Accept : application/json" \
"https:// {{API_URL}} /users/{{card_id}}/{{lang}}" \

حذف الملف الشخصي

  • أمر users
  • طلب delete
curl -k -X DELETE \
-H "X-Auth-Key : {{access_token}}" \
-H "X-Auth-Email : {{username}}" \
-H "Content-Type : application/json" \
-H "Accept : application/json" \
"https:// {{API_URL}} /users/{{card_id}}" \
نجاح HTTP/1.1 200 OK
{
  "success" : true,
  "errors" : [],
  "result" : {}
}
فشل HTTP/1.1 200 OK
{
 "success" : false,
 "errors" : [رمز-الخطأ],
 "result" : {}
}
رمز-الخطأ
خطأ
وصف
INVALID_CREDENTIALS_ERROR
كلمة السر غير الصحيحة أو عنوان البريد الإلكتروني غير صحيح أو token غير صالح
  • النصائح: كرّر التفويض
CARD_ID_NOT_FOUND_ERROR
بطاقة العمل cardId ليست موجودة أو ليس لديك إذن بتعديل هذه الموارد
  • النصيحة: تحقق من الاستفسار الذي أرسلته
أخرى
أنظر رمز-الخطأ في قسم التفويض