Введення в API

Зверніться до Служби Підтримки, щоб створити Aкаунт 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" : "1611047424"
  }
}
Відповідь
Параметр
Тип
Опис
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:/SPAN присвоєно значення, тому сервер збереже надіслані дані, але 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
e-mail
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 не існує, або у вас немає прав на зміну цього ресурсу
  • Пропозиції: перевірте ваш запит
інше
див. КОД-ПОМИЛКИ в розділі Авторизація
Попередня сторінка