מבוא ל-API

צור קשר עם צוות התמיכה כדי ליצור ממשק API ולהפוך לשותף שלנו.

הרשאה

בשלב זה אנו מניחים שאתה שותף של 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" : "1614716311"
  }
}
תגובה
פרמטר
סוג
תיאור
token
string
token שלך
expire
integer
חותמת זמן של תאריך תפוגה של token expire=time()+3600
המשתנים expire ו-rpt נמצאים במרוץ (race). הראשון שמגיע לערך היעד מבטל את ה-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
  • גודל קובץ מקסימלי 50kB
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 אינו קיים או שאין לך הרשאות לשנות משאב זה.
  • הצעות: בדקו את השאילתה
אחר
ראה קוד-שגיאה בסעיף הרשאה
העמוד הקודם