Wprowadzenie do API

Skontaktuj się z Działem Wsparcia, aby założyć Konto API i zostać naszym partnerem.

Autoryzacja

Na tym etapie zakładamy, że jesteś partnerem Bonder i nasz Dział Wsparcia dostarczył Ci nazwę użytkownika, Hasło i nazwę klienta API.
  • Komenda auth
  • Żądanie 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" \
Parametry autoryzacji
Parametr
Typ
Opis
username
string
nazwa użytkownika API
password
string
hasło API
client
string
nazwa klienta API
rpt
integer
liczba operacji przypadających na token (RPT - Requests Per Token) rpt<1000, 100000>
Powodzenie HTTP/1.1 200 OK
{
  "success" : true,
  "errors" : [],
  "result" : {
    "token" : "access_token",
    "expire" : "1610932369"
  }
}
Odpowiedź
Parametr
Typ
Opis
token
string
twój token
expire
integer
znacznik czasu zawierający datę wygaśnięcia tokena expire=time()+3600
Zmienne expire i rpt ścigają się. Pierwsza, która osiągnie wartość docelową, deaktywuje token.
Niepowodzenie HTTP/1.1 200 OK
{
  "success" : false,
  "errors" : [kod-błędu],
  "result" : {}
}
kod-błędu
Błąd
Opis
INVALID_CREDENTIALS_ERROR
Nieprawidłowe Hasło, nieprawidłowy e-mail lub Konto zostało usunięte lub nie istnieje
SERVER_OFFLINE_ERROR
Serwer offline z powodu prac konserwacyjnych w toku.
Możliwa aktualizacja oprogramowania
  • Sugestie: ponów próbę za 45-60 min
AUTH_SERVICE_OFFLINE_ERROR
Usługa autoryzacji chwilowo niedostępna dla wszystkich Użytkowników.
Możliwa aktualizacja oprogramowania
  • Sugestie: ponów próbę za 45-60 min
API_SERVICE_OFFLINE_ERROR
Usługa API chwilowo niedostępna.
Możliwa aktualizacja oprogramowania
  • Sugestie: ponów próbę za 45-60 min
ACCOUNT_INACTIVE_ERROR
Konto API zawieszone lub przeznaczone do usunięcia
  • Sugestie: kontakt z Działem Wsparcia
INTERNAL_SERVER_ERROR
Wewnętrzny błąd serwera
  • Sugestie: ponów próbę
DATABASE_ERROR
Błąd połączenia z bazą danych
  • Sugestie: ponów próbę

Struktura danych

Zanim przejdziemy do obsługi pozostałych komend, przybliżymy Ci strukturę danych używaną przez Bonder.

Typy danych

typy danych
Typ
Opis
wielojęzyczne
powinny być zapisane oddzielnie w każdym języku
stałe
są przechowywane w oddzielnej tabeli i są dodawane do Wizytówki w każdym języku
Na przykład: Jeżeli zmienisz wartość typu stałego jak email lub mobile, to wszystkie wersje językowe Wizytówki zostaną zaktualizowane.

Tryby wizytówek

Jako, że twój klient może nie być osobą, a przedsiębiorstwem, np.: "Zupełnie-niestraszne-usługi-dentystyczne", stworzyliśmy zmienną najwyższego poziomu displayName. Jeżeli !empty(displayName), to wizytówka zadziała w trybie biznes i zmienne name lastname position zostaną pominięte podczas generowania wizytówki (serwer przechowa wartości mimo to).
Tryby Wizytówek
Tryb
Warunek
biznes
if (!empty(displayName)) {
 businessMode = TRUE
}
osobisty
if (empty(displayName)) {
 businessMode = FALSE
}
W wersji angielskiej zmienna displayName ma przypisaną wartość, więc serwer zapisze przesłane dane, jednak name lastname position zostaną zignorowane podczas generowania Wizytówki. "en" : {
  "displayName" : "Non-scary-dental-services",
  "name" : "John",
  "lastname" : Kowalski",
  "position" : "CEO"
},
W wersji polskiej na urządzeniu mobilnym wyświetli się nazwa Jan Kowalski (na stanowisku Prezesa). "pl" : {
  "displayName" : "",
  "name" : "Jan",
  "lastname" : "Kowalski",
  "position" : "Prezes"
},
Wersja rosyjska będzie niedostępna do pobrania mimo przechowywania części danych na serwerze. "ru" : {
  "displayName" : "",
  "name" : "",
  "lastname" : "Ковалский",
  "position" : "Директор"
}

Zmienne

Każda zmienna musi zostać wstępnie zwalidowana przed przesłaniem jej na serwer. Jeżeli wartość przesłanej zmiennej nie będzie zgodna z przypisanym jej wyrażeniem regularnym, to serwer przypisze jej null i mimo tego zwróci pozytywną odpowiedź success=true o zapisaniu danych.
Zmienne
Nazwa
Typ
Wielojęzyczna
Opis
name
string
imię
  • wymagana do wygenerowania Wizytówki w trybie osobistym
  • zapisana i ignorowana w trybie biznes
  • /^[a-zA-Z0-9]{2,25}$/
lastname
string
nazwisko
  • zapisana i ignorowana w trybie biznes
  • zapisana i ignorowana w trybie biznes
  • /^[a-zA-Z0-9]{32,128}$/
displayName
string
nazwa wyświetlana
  • wymagana do wygenerowania Wizytówki w trybie biznes
  • /^[a-zA-Z0-9]{32,128}$/
company
string
nazwa firmy
  • /^[a-zA-Z0-9]{32,128}$/
position
string
stanowisko
  • zapisana i ignorowana w trybie biznes
  • /^[a-zA-Z0-9]{32,128}$/
keywords
string
słowa kluczowe, które najlepiej opisują osobę lub firmę
  • przecinek jako separator
  • /^[a-zA-Z0-9]{1,150}$/
thumbnail
string
zdjęcie użytkownika lub logo wyświetlane na urządzeniu mobilnym
  • kodowanie obrazu w base64
  • stały rozmiar 300px x 300px
  • maksymalny rozmiar pliku 50kB
phoneA
string
numer telefonu
  • zera wiodące i znaki nienumeryczne zostaną obcięte
  • klient powinien podać numer kierunkowy kraju
  • sami dodamy "+" na początku
  • /^[a-zA-Z0-9]{32,128}$/
phoneB
string
jak wyżej
mobileA
string
numer komórki
  • zera wiodące i znaki nienumeryczne zostaną obcięte
  • klient powinien podać numer kierunkowy kraju
  • sami dodamy "+" na początku
  • /^[a-zA-Z0-9]{32,128}$/
mobileB
string
jak wyżej
skypeA
string
nazwa użytkownika skype
  • /^[a-zA-Z0-9]{32,128}$/
skypeB
string
jak wyżej
faxA
string
numer faksu
  • zera wiodące i znaki nienumeryczne zostaną obcięte
  • klient powinien podać numer kierunkowy kraju
  • sami dodamy "+" na początku
  • /^[a-zA-Z0-9]{32,128}$/
faxB
string
jak wyżej
emailA
string
e-mail
emailB
string
jak wyżej
webA
string
URL
  • /^[a-zA-Z0-9]{32,128}$/
webB
string
jak wyżej
webC
string
jak wyżej
addrStreet
string
adres - ulica
  • /^[a-zA-Z0-9]{32,128}$/
addrCity
string
adres - miasto
  • /^[a-zA-Z0-9]{32,128}$/
addrState
string
adres - województwo / prowincja
  • /^[a-zA-Z0-9]{32,128}$/
addrZip
string
adres - kod pocztowy
  • /^[a-zA-Z0-9]{32,128}$/
addrCountry
string
adres - kraj
  • /^[a-zA-Z0-9]{32,128}$/

parametry

Parametry
Zmienna
Typ
Opis
langStatus
integer
0 = off, 1 = on
Włącz / wyłącz wersję językową bez usuwania danych
  • default = 0
usePhoto
integer
0 = off, 1 = on
Włącz / wyłącz zdjęcie bez usuwania go
  • default = 1
cardStatus
integer
0 = off, 1 = on
Włącz / wyłącz Wizytówkę bez usuwania jej
  • default = 1

Wsparcie językowe

Bonder pozwala swoim użytkownikom na tworzenie Wizytówek w ponad 60 językach i ta kluczowa funkcjonalność jest dostępna także dla Użytkowników API. Dla twojej wygody przygotowaliśmy repozytoria zawierające przetłumaczone kody języków wspieranych przez Bonder, których możesz użyć podczas tworzenia własnej aplikacji. Do zarządzania wersjami językowymi używamy zmiennej lang. Będziesz jej używać do dodawania, edytowania i usuwania wersji językowych.
  • Komenda repositories
  • Żądanie 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 \
Powodzenie HTTP/1.1 200 OK
{
  "success": true,
  "errors" : [],
  "result" : {
    "langList" : [local, lang]
  }
}
langList
wartość
Typ
Opis
lang
string
kod języka zgodny z ISO 639-1:2002
local
string
lista lokalnych nazw języków, np.: en => English, ru => Русский
Przykładowa odpowiedź Serwer zwraca listę dostępnych zasobów : local, angielski, rosyjski, polski, chiński HTTP/1.1 200 OK
{
  "success": true,
  "errors" : [],
  "result" : {
    "langList" : ["local", "en", "ru", "pl", "zh"]
  }
}
Użyj wartości z langList, aby pobrać zasoby, których potrzebujesz. Odpowiedź zawsze przyjdzie w postaci par klucz : wartość.

Pobierz listę lokalnych nazw języków

  • Komenda repositories
  • Żądanie 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" \
Powodzenie HTTP/1.1 200 OK
{
  "success": true,
  "errors" : [],
  "result" : {
    "pl" : "Polski",
    "en" : "English",
    "ru" : "Русский",
    ...,
    "klucz" : "wartość"
 }
}

Pobierz przetłumaczone nazwy języków

  • Komenda repositories
  • Żądanie GET
Zmień powyższe zapytanie zgodnie z poniższym przykładem: "https:// {{API_URL}} /repositories/ru" \
"https:// {{API_URL}} /repositories/en" \
Jeżeli w repozytoriach nie posiadamy zasobu, którego szukasz, poinformuj o tym Dział Wsparcia. Uzupełnimy braki tak szybko, jak to możliwe. Jeżeli nie możesz czekać na naszą odpowiedź, to sugerujemy pobranie dostępnych kodów języków i wykonanie własnych tłumaczeń.
Niepowodzenie HTTP/1.1 200OK
{
  "success" : false,
  "errors" : [kod-błędu],
  "result" : {}
}
kod-błędu
Błąd
Opis
INVALID_CREDENTIALS_ERROR
Nieprawidłowe Hasło lub e-mail lub nieważny token
  • Sugestie: powtórz autoryzację
RESOURCE_NOT_FOUND_ERROR
Zasób, którego szukasz, nie istnieje
  • Sugestie: sprawdź przesłane zapytanie
pozostałe
patrz KOD-BŁĘDU w sekcji Autoryzacja

Tworzenie nowego Profilu

  • Komenda users
  • Żądanie post
curl -k -X POST \
-H "X-Auth-Key : {{access_token}}" \
-H "X-Auth-Email : {{username}}" \
-H "Accept : application/json" \
"https:// {{API_URL}} /users" \
Powodzenie HTTP/1.1 200 OK
{
  "success": true,
  "errors" : [],
  "result" : {
    "cardId" : string,
    "cardQrc" : string,
    "cardAddr" : string (url)
  }
}
WYNIK ZAPYTANIA
Zmienna
Typ
Opis
cardId
string
numer Wizytówki utworzonego Profilu
  • uwzględnia wielkość liter
  • /^[a-zA-Z0-9]{32,128}$/
cardAddr
string
adres utworzonej Wizytówki
cardQrc
string
kod QR adresu Wizytówki zakodowany w base64
Wartości cardId cardQrc cardAddr powinny być przechowywane lokalnie na twoim serwerze i przypisane do Profilu. Zmienna cardId jest niezbędna do poprawnej komunikacji z API.
Niepowodzenie HTTP/1.1 200 OK
{
  "success" : false,
  "errors" : [kod-błędu],
  "result" : {}
}
kod-błędu
Błąd
Opis
INVALID_CREDENTIALS_ERROR
Nieprawidłowe Hasło lub e-mail lub nieważny token
  • Sugestie: powtórz autoryzację
PROFILE_LIMIT_REACHED_ERROR
Wyczerpano limit Profili
  • Sugestie: kontakt z Działem Wsparcia w celu zmiany Ustawień Konta
pozostałe
patrz KOD-BŁĘDU w sekcji Autoryzacja

Zapisywanie danych

  • Nie używamy sztywnych szablonów zapytań. Wyślij tylko dane, które wymagają aktualizacji.
  • Do utworzenia nowego Profilu użyj komendy PUT.
  • Dodaj język używając kluczy lang w sekcji translatable.
  • Jeżeli klient nie chce określać wersji językowej, to ustaw lang=un, co oznacza uniwersalny.
  • Modyfikuj do pięciu języków w jednym zapytaniu (aktualizacja, dodanie). Wersje językowe ponad 5 zostaną zignorowane.
  • Komenda users
  • Żądanie 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 ' {
Kiedy cardStatus=0 Wizytówka zostanie wyłączona i nie będzie można jej pobrać.   "settings" : {
    "cardStatus" : "0",
    "usePhoto" : "1"
  },
  "translatable" : {
Używaj langStatus do włączania i wyłączania języków.     "pl" : {
      "name" : "John",
      "lastname" : "Connor",
      "position" : "Dyrektor Zarządzający"
    },
Podczas dodawania nowego języka domyślanie ustawiamy langStatus=0. Możesz obejść to ustawienie przez przypisanie langStatus=1 podczas dodawania języka.     "en" : {
      "name" : "John",
      "lastname" : "Connor",
      "position" : "Managing Director",
      "displayName" : "The Great John Connor",
      "keywords" : "steel, steel pipe, tubular products"
    },
Mimo ustawienia langStatus=1, dany język nie będzie gotowy do pobrania dopóki nie zostanie spełniony warunek (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}} \
Powodzenie HTTP/1.1 200 OK
{
  "success": true,
  "errors" : [kod-błędu],
  "result" : {}
}
Mimo zwrócenia success=true serwer może zgłosić błąd, kiedy do zapytania dołączysz zdjęcie profilowe.
kod-błędu
Błąd
Opis
THUMBNAIL_REJECTED_ERROR
Dane zostały zapisane, jednak przesłany obraz został odrzucony przez serwer
  • Sugestie: sprawdź swój generator obrazów
Niepowodzenie HTTP/1.1 200 OK
{
  "success" : false,
  "errors" : [kod-błędu],
  "result" : {}
}
kod-błędu
Błąd
Opis
INVALID_CREDENTIALS_ERROR
Nieprawidłowe Hasło lub e-mail lub nieważny token
  • Sugestie: powtórz autoryzację
CARD_ID_NOT_FOUND_ERROR
Wizytówka cardId nie istnieje lub nie masz uprawnień do modyfikacji tego zasobu
  • Sugestie: sprawdź przesłane zapytanie
pozostałe
patrz KOD-BŁĘDU w sekcji Autoryzacja

Modyfikowanie ustawień

Parametry
Parametr
Typ
Opis
status
string
<enable, disable>

Zmiana statusu Wizytówki

  • Komenda users
  • Żądanie 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}}

Zmiana statusu zdjęcia

  • Komenda users
  • Żądanie 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}}

Zmiana statusu języka

  • Komenda users
  • Żądanie 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}}
Powodzenie HTTP/1.1 200 OK
{
  "success" : true,
  "errors" : [],
  "result" : {}
}
Niepowodzenie HTTP/1.1 200 OK
{
  "success" : false,
  "errors" : [kod-błędu],
  "result" : {}
}
kod-błędu
Błąd
Opis
wszystkie
patrz KOD-BŁĘDU w sekcji Zapisywanie danych

Pobieranie danych

  • Komenda users
  • Żądanie 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}}" \
Powodzenie HTTP/1.1 200 OK
{
"success": true,
"errors" : [],
"result" : {
  "translatable" : {
    "lang" : {
      "langStatus" : "1",
      "klucz" : "wartość"
    },
    "lang" : {
      "langStatus" : "0",
      "klucz" : "wartość"
    }
  },
  "non-translatable" : {
    "thumbnail" : "base64_encoded_image",
    "klucz" : "wartość"
  },
  "settings" : {
    "cardStatus" : "1",
    "usePhoto" : "1",
    "cardQrc" : "base64_encoded_image",
    "cardAddr" : "URL",
    "usePhoto" : "1"
  }
}
Niepowodzenie HTTP/1.1 200 OK
{
  "success" : false,
  "errors" : [kod-błędu],
  "result" : {}
}
kod-błędu
Błąd
Opis
INVALID_CREDENTIALS_ERROR
Nieprawidłowe Hasło lub e-mail lub nieważny token
  • Sugestie: powtórz autoryzację
CARD_ID_NOT_FOUND_ERROR
Wizytówka cardId nie istnieje lub nie masz uprawnień do modyfikacji tego zasobu
  • Sugestie: sprawdź przesłane zapytanie
pozostałe
patrz KOD-BŁĘDU w sekcji Autoryzacja

Usuwanie danych

Usuwanie języka

  • Komenda users
  • Żądanie 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}}" \

Usuwanie Profilu

  • Komenda users
  • Żądanie 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}}" \
Powodzenie HTTP/1.1 200 OK
{
  "success" : true,
  "errors" : [],
  "result" : {}
}
Niepowodzenie HTTP/1.1 200 OK
{
 "success" : false,
 "errors" : [kod-błędu],
 "result" : {}
}
kod-błędu
Błąd
Opis
INVALID_CREDENTIALS_ERROR
Nieprawidłowe Hasło lub e-mail lub nieważny token
  • Sugestie: powtórz autoryzację
CARD_ID_NOT_FOUND_ERROR
Wizytówka cardId nie istnieje lub nie masz uprawnień do modyfikacji tego zasobu
  • Sugestie: sprawdź przesłane zapytanie
pozostałe
patrz KOD-BŁĘDU w sekcji Autoryzacja
Poprzednia strona