Authorisation
At this stage, we assume that you are a partner of Bonder and our Support Team has provided you with the Username, Password and API client name.
-
Command auth
-
Request POST
curl -k -X POST \
-H \
-H \
-d '{
"username" : "USERNAME",
"password" : "PASSWORD",
"client" : "API_CLIENT_NAME",
"rpt" : "10000"
}' \
"https:// {{API_URL}} /auth" \
Parameter
Type
Description
username
string
API username
password
string
API password
client
string
API client name
rpt
integer
number of requests per token (RPT - Requests Per Token) rpt<1000, 100000>
Success
HTTP/1.1 200 OK
{
"success" : true,
"errors" : [],
"result" : {
"token" : "access_token",
"expire" : "1614722304"
}
}
Parameter
Type
Description
expire
integer
timestamp of token expiry date expire=time()+3600
The expire and rpt variables are racing. The one which reaches the target value first will deactivate the token.
Failure
HTTP/1.1 200 OK
{
"success" : false,
"errors" : [error-code],
"result" : {}
}
INVALID_CREDENTIALS_ERROR
Invalid Password, invalid e-mail or Account was deleted or does not exist
SERVER_OFFLINE_ERROR
Server is offline due to ongoing maintenance works.
Possible software update
-
Suggestions: try again in 45-60 min
AUTH_SERVICE_OFFLINE_ERROR
The authentication service is temporarily unavailable for all Users.
Possible software update
-
Suggestions: try again in 45-60 min
API_SERVICE_OFFLINE_ERROR
The API service is temporarily unavailable.
Possible software update
-
Suggestions: try again in 45-60 min
ACCOUNT_INACTIVE_ERROR
The API Account is suspended or intended for deletion
-
Suggestions: contact the Support Team
DATABASE_ERROR
Database connection error
Data structure
Before we move to other commands, we will explain to you the data structure used by Bonder.
Data types
translatable
should be saved separately in each language
non-translatable
are stored in a separate table and are added to the Business Card in each language
For example:
If you change a non-translatable value such as email or mobile, all language versions of the Business Card will be updated.
Business Card modes
Due to the fact that your client may not be a natural person but an enterprise, e.g. Totally-not-scary-dental-services, we created the top level variable - displayName.
If !empty(displayName), the Business Card will operate in the business mode and the name lastname position variables will be omitted when generating the Business Card (however, the server will still keep the values).
business
if (!empty(displayName)) {
businessMode = TRUE
}
personal
if (empty(displayName)) {
businessMode = FALSE
}
"en" : {
"displayName" : "Non-scary-dental-services",
"name" : "John",
"lastname" : Kowalski",
"position" : "CEO"
},
"pl" : {
"displayName" : "",
"name" : "Jan",
"lastname" : "Kowalski",
"position" : "Prezes"
},
"ru" : {
"displayName" : "",
"name" : "",
"lastname" : "Ковалский",
"position" : "Директор"
}
Variables
Each variable need to be preliminary validated before sending it to the server. If the value of the sent variable is not in line with the regular expression assigned to it, the server will assign it with null and, despite that, will send the success=true positive response about saving data.
Name
Type
Translatable
Description
name
string
name
-
required to generate the Business Card in the personal mode
-
saved and ignored in the business mode
-
/^[a-zA-Z0-9]{2,25}$/
lastname
string
surname
-
saved and ignored in the business mode
-
saved and ignored in the business mode
-
/^[a-zA-Z0-9]{32,128}$/
displayName
string
display name
-
required to generate the Business Card in the business mode
-
/^[a-zA-Z0-9]{32,128}$/
position
string
position
-
saved and ignored in the business mode
-
/^[a-zA-Z0-9]{32,128}$/
keywords
string
keywords which best describe a given person or company
-
comma as a separator
-
/^[a-zA-Z0-9]{1,150}$/
thumbnail
string
user's photo or logo displayed on a mobile device
-
image encoded in base64
-
fixed size 300px x 300px
-
maximum file size 50KB
phoneA
string
phone number
-
leading zeros and non-numeric characters will be cut
-
a client should provide their country code
-
we will add "+" at the beginning
-
/^[a-zA-Z0-9]{32,128}$/
mobileA
string
mobile phone number
-
leading zeros and non-numeric characters will be cut
-
a client should provide their country code
-
we will add "+" at the beginning
-
/^[a-zA-Z0-9]{32,128}$/
faxA
string
fax number
-
leading zeros and non-numeric characters will be cut
-
a client should provide their country code
-
we will add "+" at the beginning
-
/^[a-zA-Z0-9]{32,128}$/
addrState
string
address – state / province
parameters
Variable
Type
Description
langStatus
integer
0 = off, 1 = on
Enable / disable language version without deleting data
usePhoto
integer
0 = off, 1 = on
Enable / disable photo without deleting it
cardStatus
integer
0 = off, 1 = on
Enable / disable Business Card without deleting it
Language support
Bonder allows its Users to create Business Cards in more than 60 languages and this key functionality is also available for API Users.
For your convenience, we prepared repositories with translated language codes supported by Bonder, which you can use when creating your own application.
We use the lang variable to manage language versions. You will use it to add, edit and delete language versions.
-
Command repositories
-
Request GET
curl -k -X GET \
-H \
-H \
-H \
-H \
"https:// {{API_URL}} /repositories \
Success
HTTP/1.1 200 OK
{
"success": true,
"errors" : [],
"result" : {
"langList" : [local, lang]
}
}
lang
string
language code compliant with ISO 639-1:2002
local
string
list of local language names, e.g.: en => English, ru => Русский
HTTP/1.1 200 OK
{
"success": true,
"errors" : [],
"result" : {
"langList" : ["local", "en", "ru", "pl", "zh"]
}
}
Use the values from langList to download resources which you need. The response will always be in the form of the key : value pairs.
Download the list of local language names
-
Command repositories
-
Request GET
curl -k -X GET \
-H \
-H \
-H \
-H \
"https:// {{API_URL}} /repositories/local" \
Success
HTTP/1.1 200 OK
{
"success": true,
"errors" : [],
"result" : {
"pl" : "Polski",
"en" : "English",
"ru" : "Русский",
...,
"key" : "value"
}
}
Download translated language names
-
Command repositories
-
Request GET
"https:// {{API_URL}} /repositories/ru" \
"https:// {{API_URL}} /repositories/en" \
If we do not have a resource which you look for in our repositories, inform the Support Team about that. We will fill the gaps as soon as possible.
If you cannot wait for our response, we suggest downloading available language codes and preparing your own translations.
Failure
HTTP/1.1 200OK
{
"success" : false,
"errors" : [error-code],
"result" : {}
}
INVALID_CREDENTIALS_ERROR
Invalid Password or e-mail or invalid token
-
Suggestions: repeat authentication
RESOURCE_NOT_FOUND_ERROR
The resource you are looking for does not exist
-
Suggestions: check the query
other
see ERROR-CODE in the Authorisation section
Creating a new Profile
-
Command users
-
Request post
curl -k -X POST \
-H \
-H \
-H \
"https:// {{API_URL}} /users" \
Success
HTTP/1.1 200 OK
{
"success": true,
"errors" : [],
"result" : {
"cardId" : string,
"cardQrc" : string,
"cardAddr" : string (url)
}
}
Variable
Type
Description
cardId
string
Business Card identifier of a created Profile
-
case-sensitive
-
/^[a-zA-Z0-9]{32,128}$/
cardAddr
string
address of a created Business Card
cardQrc
string
the QR code of the Business Card's address encoded in base64
The cardId cardQrc cardAddr variables should be stored locally on your server and assigned to a given Profile.
The cardId variable is necessary for correct communication with API.
Failure
HTTP/1.1 200 OK
{
"success" : false,
"errors" : [error-code],
"result" : {}
}
INVALID_CREDENTIALS_ERROR
Invalid Password or e-mail or invalid token
-
Suggestions: repeat authentication
PROFILE_LIMIT_REACHED_ERROR
Profile limit reached
-
Suggestions: contact the Support Team to change Account Settings
other
see ERROR-CODE in the Authorisation section
Saving data
-
We do not use fixed inquiries. Send only this data which needs to be updated.
-
Use the PUT command to create a new Profile.
-
Add a language using the lang keys in the translatable section.
-
If a client does not want to specify a language version, set lang=un which means universal.
-
Modify up to five languages within one query (updating, adding). Language versions above 5 will be ignored.
-
Command users
-
Request put
curl -k -X
PUT \
-H \
-H \
-H \
-H \
-d '
{
"settings" : {
"cardStatus" : "0",
"usePhoto" : "1"
},
"translatable" : {
"pl" : {
"name" : "John",
"lastname" : "Connor",
"position" : "Dyrektor Zarządzający"
},
"en" : {
"name" : "John",
"lastname" : "Connor",
"position" : "Managing Director",
"displayName" : "The Great John Connor",
"keywords" : "steel, steel pipe, tubular products"
},
"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}} \
Success
HTTP/1.1 200 OK
{
"success": true,
"errors" : [error-code],
"result" : {}
}
Despite returning success=true, the server may report an error if you add a profile photo to your query.
THUMBNAIL_REJECTED_ERROR
Data has been saved, however, the sent image has been rejected by the server
-
Suggestions: validate your image generator
Failure
HTTP/1.1 200 OK
{
"success" : false,
"errors" : [error-code],
"result" : {}
}
INVALID_CREDENTIALS_ERROR
Invalid Password or e-mail or invalid token
-
Suggestions: repeat authentication
CARD_ID_NOT_FOUND_ERROR
The Business Card
cardId does not exist or you do not have authorisations to modify this resource.
-
Suggestions: check the query
other
see ERROR-CODE in the Authorisation section
Modifying settings
Parameter
Type
Description
status
string
<enable, disable>
Changing Business Card status
-
Command users
-
Request put
curl -k -X PUT \
-H \
-H \
-H \
-H \
https:// {{API_URL}} /users/{{card_id}}/cardStatus/{{status}}
Changing photo status
-
Command users
-
Request put
curl -k -X PUT \
-H \
-H \
-H \
-H \
https:// {{API_URL}} /users/{{card_id}}/usePhoto/{{status}}
Changing language status
-
Command users
-
Request put
curl -k -X PUT \
-H \
-H \
-H \
-H \
https:// {{API_URL}} /users/{{card_id}}/langStatus/{{lang}}/{{status}}
Success
HTTP/1.1 200 OK
{
"success" : true,
"errors" : [],
"result" : {}
}
Failure
HTTP/1.1 200 OK
{
"success" : false,
"errors" : [error-code],
"result" : {}
}
all
see ERROR-CODE in the Saving data section
Downloading data
-
Command users
-
Request get
curl -k -X GET \
-H \
-H \
-H \
-H \
"https:// {{API_URL}} /users/{{card_id}}" \
Success
HTTP/1.1 200 OK
{
"success": true,
"errors" : [],
"result" : {
"translatable" : {
"lang" : {
"langStatus" : "1",
"key" : "value"
},
"lang" : {
"langStatus" : "0",
"key" : "value"
}
},
"non-translatable" : {
"thumbnail" : "base64_encoded_image",
"key" : "value"
},
"settings" : {
"cardStatus" : "1",
"usePhoto" : "1",
"cardQrc" : "base64_encoded_image",
"cardAddr" : "URL",
"usePhoto" : "1"
}
}
Failure
HTTP/1.1 200 OK
{
"success" : false,
"errors" : [error-code],
"result" : {}
}
INVALID_CREDENTIALS_ERROR
Invalid Password or e-mail or invalid token
-
Suggestions: repeat authentication
CARD_ID_NOT_FOUND_ERROR
The Business Card
cardId does not exist or you do not have authorisations to modify this resource.
-
Suggestions: check the query
other
see ERROR-CODE in the Authorisation section
Deleting data
Deleting language
-
Command users
-
Request delete
curl -k -X DELETE \
-H \
-H \
-H \
-H \
"https:// {{API_URL}} /users/{{card_id}}/{{lang}}" \
Deleting Profile
-
Command users
-
Request delete
curl -k -X DELETE \
-H \
-H \
-H \
-H \
"https:// {{API_URL}} /users/{{card_id}}" \
Success
HTTP/1.1 200 OK
{
"success" : true,
"errors" : [],
"result" : {}
}
Failure
HTTP/1.1 200 OK
{
"success" : false,
"errors" : [error-code],
"result" : {}
}
INVALID_CREDENTIALS_ERROR
Invalid Password or e-mail or invalid token
-
Suggestions: repeat authentication
CARD_ID_NOT_FOUND_ERROR
The Business Card
cardId does not exist or you do not have authorisations to modify this resource.
-
Suggestions: check the query
other
see ERROR-CODE in the Authorisation section