Introduzione all'API

Contatta la Sezione di Supporto per creare l'Account API e diventare il nostro partner.

Autorizzazione

In questa fase si assume che sei partner di Bonder e la nostra Sezione di Supporto ti ha fornito il nome dell'Utente, la Password e il nome del cliente API.
  • Comando auth
  • Richiesta 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" \
Parametri di autorizzazione
Parametro
Tipo
Descrizione
username
string
nome dell'utente API
password
string
password API
client
string
nome del cliente API
rpt
integer
numero delle operazioni per token (RPT - Requests Per Token) rpt<1000, 100000>
Successo HTTP/1.1 200 OK
{
  "success" : true,
  "errors" : [],
  "result" : {
    "token" : "access_token",
    "expire" : "1614717967"
  }
}
Risposta
Parametro
Tipo
Descrizione
token
string
il tuo token
expire
integer
marcatura temporale con la data di scadenza del token expire=time()+3600
Le variabili expire e rpt si rincorrono. La prima che raggiunge il valore target diattiva il token.
Fallimento HTTP/1.1 200 OK
{
  "success" : false,
  "errors" : [codice-di-errore],
  "result" : {}
}
codice-di-errore
Errore
Descrizione
INVALID_CREDENTIALS_ERROR
Password sbagliata, e-mail sbagliata oppure l'Account è stato rimosso o non esiste
SERVER_OFFLINE_ERROR
Il server offline a causa dei lavori di manutenzione in corso.
L'aggiornamento del software possibile
  • Suggerimenti: riprovaci in 45-60 minuti
AUTH_SERVICE_OFFLINE_ERROR
Il servizio di autorizzazione temporaneamente indisponibile per tutti gli Utenti.
L'aggiornamento del software possibile
  • Suggerimenti: riprovaci in 45-60 minuti
API_SERVICE_OFFLINE_ERROR
Il servizio API temporaneamente indisponibile.
L'aggiornamento del software possibile
  • Suggerimenti: riprovaci in 45-60 minuti
ACCOUNT_INACTIVE_ERROR
L'Account API sospeso o destinato ad essere rimosso
  • Suggerimenti: contatta la Sezione di Supporto
INTERNAL_SERVER_ERROR
Errore interno del server
  • Suggerimenti: riprovaci
DATABASE_ERROR
Errore di collegamento con la banca dati
  • Suggerimenti: riprovaci

Struttura dei dati

Prima di passare alla gestione di altri comandi, ti presentiamo la struttura dei dati utilizzata da Bonder.

Tipi di dati

tipi di dati
Tipo
Descrizione
multilingue
devono essere salvati separatamente in ogni lingua
costanti
sono conservati in una tabella separata e aggiunti al Biglietto da Visita in ogni lingua
Per esempio: Se cambi un valore di tipo costante come email o mobile, tutte le versioni linguistiche del Biglietto da Visita saranno aggiornate.

Modi dei Biglietti da Visita

Siccome il tuo cliente può essere non una persona ma una ditta, per esempio: Cure-dentistiche-assolutamente-non-spaventose, abbiamo creato una variabile del più alto livello - displayName. Se !empty(displayName), il Biglietto da Visita funziona nel modo business e le variabili name lastname position saranno omesse durante la generazione del Biglietto da Visita (il server conserverà i valori ciò nonostante).
Modi dei Biglietti da Visita
Modo
Condizione
business
if (!empty(displayName)) {
 businessMode = TRUE
}
personale
if (empty(displayName)) {
 businessMode = FALSE
}
Nella versione inglese la variabile displayName ha il valore assegnato quindi il server salverà i dati inviati ma name lastname position saranno ignorati durante la generazione del Biglietto da Visita. "en" : {
  "displayName" : "Non-scary-dental-services",
  "name" : "John",
  "lastname" : Kowalski",
  "position" : "CEO"
},
Nella versione polacca sul dispositivo mobile sarà visualizzato il nome Jan Kowalski (al posto del Presidente). "pl" : {
  "displayName" : "",
  "name" : "Jan",
  "lastname" : "Kowalski",
  "position" : "Prezes"
},
La versione russa non sarà scaricabile, anche se una parte dei dati sarà conservata sul server. "ru" : {
  "displayName" : "",
  "name" : "",
  "lastname" : "Ковалский",
  "position" : "Директор"
}

Variabili

Ogni variabile deve essere preventivamente validata prima che sia inviata al server. Se il valore della variabile inviata non sarà conforme all'espressione regolare assegnatale, il server le assegnerà null e ciò nonostante rimanderà una risposta positiva success=true di aver salvato i dati.
Variabili
Nome
Tipo
Multilingue
Descrizione
name
string
nome
  • richiesta per generare il Biglietto da Visita nel modo personale
  • salvata ed ignorata nel modo business
  • /^[a-zA-Z0-9]{2,25}$/
lastname
string
cognome
  • salvata ed ignorata nel modo business
  • salvata ed ignorata nel modo business
  • /^[a-zA-Z0-9]{32,128}$/
displayName
string
nome visualizzato
  • richiesta per generare il Biglietto da visita nel modo business
  • /^[a-zA-Z0-9]{32,128}$/
company
string
nome dell'azienda
  • /^[a-zA-Z0-9]{32,128}$/
position
string
carica
  • salvata ed ignorata nel modo business
  • /^[a-zA-Z0-9]{32,128}$/
keywords
string
parole chiave che descrivono meglio la persona o l'azienda
  • virgola come un separatore
  • /^[a-zA-Z0-9]{1,150}$/
thumbnail
string
foto dell'Utente o logo visualizzato sul dispositivo mobile
  • immagine salvata in base64
  • dimensioni fisse 300px x 300px
  • dimensione massima del file 50kB
phoneA
string
numero di telefono
  • zeri iniziali e segni non-numerici saranno omessi
  • il cliente deve citare il prefisso del paese
  • aggiungiamo noi "+" all'inizio
  • /^[a-zA-Z0-9]{32,128}$/
phoneB
string
come sopra
mobileA
string
numero del cellulare
  • zeri iniziali e segni non-numerici saranno omessi
  • il cliente deve citare il prefisso del paese
  • aggiungiamo noi "+" all'inizio
  • /^[a-zA-Z0-9]{32,128}$/
mobileB
string
come sopra
skypeA
string
nome dell'Utente di Skype
  • /^[a-zA-Z0-9]{32,128}$/
skypeB
string
come sopra
faxA
string
numero di fax
  • zeri iniziali e segni non-numerici saranno omessi
  • il cliente deve citare il prefisso del paese
  • aggiungiamo noi "+" all'inizio
  • /^[a-zA-Z0-9]{32,128}$/
faxB
string
come sopra
emailA
string
e-mail
emailB
string
come sopra
webA
string
URL
  • /^[a-zA-Z0-9]{32,128}$/
webB
string
come sopra
webC
string
come sopra
addrStreet
string
indirizzo - via
  • /^[a-zA-Z0-9]{32,128}$/
addrCity
string
indirizzo - città
  • /^[a-zA-Z0-9]{32,128}$/
addrState
string
indirizzo - regione / provincia
  • /^[a-zA-Z0-9]{32,128}$/
addrZip
string
indirizzo - CAP
  • /^[a-zA-Z0-9]{32,128}$/
addrCountry
string
indirizzo - paese
  • /^[a-zA-Z0-9]{32,128}$/

parametri

Parametri
Variabile
Tipo
Descrizione
langStatus
integer
0 = off, 1 = on
Attiva / disattiva lingua senza rimuovere i dati
  • default = 0
usePhoto
integer
0 = off, 1 = on
Attiva / disattiva la foto senza rimuoverla
  • default = 1
cardStatus
integer
0 = off, 1 = on
Attiva / disattiva il Biglietto da Visita senza rimuoverlo
  • default = 1

Supporto linguistico

Bonder permette ai suoi Utenti di creare Biglietti da Visita in oltre 60 lingue e questa funzionalità chiave è disponibile anche agli Utenti dell'API. Per il tuo conforto abbiamo preparato repertori che contengono codici tradotti delle lingue supportati da Bonder che puoi utilizzare durante la creazione della propria applicazione. Per gestire le Lingue utilizziamo la variabile lang. La utilizzerai per aggiungere, modificare e rimuovere le lingue.
  • Comando repositories
  • Richiesta 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 \
Successo HTTP/1.1 200 OK
{
  "success": true,
  "errors" : [],
  "result" : {
    "langList" : [local, lang]
  }
}
langList
valore
Tipo
Descrizione
lang
string
codice della lingua conforme ad ISO 639-1:2002
local
string
elenco dei nomi locali delle lingue, per esempio: en => English, ru => Русский
Risposta di esempio Il server rimanda l'elenco delle risorse disponibili: local, inglese, russo, polacco, cinese HTTP/1.1 200 OK
{
  "success": true,
  "errors" : [],
  "result" : {
    "langList" : ["local", "en", "ru", "pl", "zh"]
  }
}
Utilizza i valori da langList per scaricare le risorse di cui ha bisogno. Riceverai sempre la risposta come una coppia chiave : .

Scarica l'elenco dei nomi locali delle lingue

  • Comando repositories
  • Richiesta 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" \
Successo HTTP/1.1 200 OK
{
  "success": true,
  "errors" : [],
  "result" : {
    "pl" : "Polski",
    "en" : "English",
    "ru" : "Русский",
    ...,
    "chiave" : "valore"
 }
}

Scarica i nomi tradotti delle lingue

  • Comando repositories
  • Richiesta GET
Modifica la suddetta richiesta conformemente all'esempio seguente: "https:// {{API_URL}} /repositories/ru" \
"https:// {{API_URL}} /repositories/en" \
Se nei repertori non possiediamo la risorsa che stai cercando, comunicalo alla Sezione di Supporto. Integriamo le mancanze quanto prima. Se non puoi aspettare la nostra risposta, ti suggeriamo di scaricare i codici delle lingue disponibili e fare la tua traduzione.
Fallimento HTTP/1.1 200OK
{
  "success" : false,
  "errors" : [codice-di-errore],
  "result" : {}
}
codice-di-errore
Errore
Descrizione
INVALID_CREDENTIALS_ERROR
Password o e-mail sbagliata o il token invalido
  • Suggerimenti: ripeti l'autorizzazione
RESOURCE_NOT_FOUND_ERROR
La risorsa che stai cercando non esiste
  • Suggerimenti: controlla la richiesta inviata
altri
vedi CODICE-ERRORE nella sezione Autorizzazione

Creazione del nuovo Profilo

  • Comando users
  • Richiesta post
curl -k -X POST \
-H "X-Auth-Key : {{access_token}}" \
-H "X-Auth-Email : {{username}}" \
-H "Accept : application/json" \
"https:// {{API_URL}} /users" \
Successo HTTP/1.1 200 OK
{
  "success": true,
  "errors" : [],
  "result" : {
    "cardId" : string,
    "cardQrc" : string,
    "cardAddr" : string (url)
  }
}
RISULTATI DELLA RICHIESTA
Variabile
Tipo
Descrizione
cardId
string
numero del Biglietto da Visita del Profilo creato
  • distingue le maiuscole
  • /^[a-zA-Z0-9]{32,128}$/
cardAddr
string
indirizzo del Biglietto da Visita creato
cardQrc
string
codice QR dell'indirizzo del Biglietto da Visita salvato in base64
Le variabili cardId cardQrc cardAddr devono essere conservate localmente sul tuo server e assegnate al Profilo. La variabile cardId è necessaria per una comunicazione corretta con l'API.
Fallimento HTTP/1.1 200 OK
{
  "success" : false,
  "errors" : [codice-di-errore],
  "result" : {}
}
codice-di-errore
Errore
Descrizione
INVALID_CREDENTIALS_ERROR
Password o e-mail sbagliata o il token invalido
  • Suggerimenti: ripeti l'autorizzazione
PROFILE_LIMIT_REACHED_ERROR
Il limite dei Profili è stato raggiunto
  • Suggerimenti: contatta la Sezione di Supporto al fine di modificare le Impostazioni dell'Account
altri
vedi CODICE-ERRORE nella sezione Autorizzazione

Memorizzazione dei dati

  • Non utilizziamo modelli fissi delle richieste. Invia solo i dati che devono essere aggiornati.
  • Per creare un nuovo Profilo utilizza il comando PUT.
  • Aggiungi una lingua utilizzando le chiavi lang nella sezione translatable.
  • Se il cliente non vuole specificare la lingua, imposta lang=un il che significa universale.
  • Modifica sino a cinque lingue in una richiesta (aggiornamento, aggiunzione). Le versioni linguistiche oltre i 5 saranno ignorate.
  • Comando users
  • Richiesta 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 ' {
Quando cardStatus=0 Biglietto da Visita sarà disattivato, non sarà scaricabile.   "settings" : {
    "cardStatus" : "0",
    "usePhoto" : "1"
  },
  "translatable" : {
Utilizza langStatus per attivare e disattivare le lingue.     "pl" : {
      "name" : "John",
      "lastname" : "Connor",
      "position" : "Dyrektor Zarządzający"
    },
Quando aggiungiamo una nuova lingua, impostiamo come predefinito langStatus=0. Puoi eludere questa impostazione assegnando langStatus=1 durante l'aggiunzione della lingua.     "en" : {
      "name" : "John",
      "lastname" : "Connor",
      "position" : "Managing Director",
      "displayName" : "The Great John Connor",
      "keywords" : "steel, steel pipe, tubular products"
    },
Nonostante l'impostazione langStatus=1, una data lingua non sarà pronta per il download fino a quando non sia soddisfatta la condizione (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}} \
Successo HTTP/1.1 200 OK
{
  "success": true,
  "errors" : [codice-di-errore],
  "result" : {}
}
Anche se rimanda success=true, il server può comunicare un errore, quando aggiungi la foto del profilo alla richiesta.
codice-di-errore
Errore
Descrizione
THUMBNAIL_REJECTED_ERROR
I dati sono stati salvati ma l'immagine inviata è stata respinta
  • Suggerimenti: controlla il tuo generatore delle immagini
Fallimento HTTP/1.1 200 OK
{
  "success" : false,
  "errors" : [codice-di-errore],
  "result" : {}
}
codice-di-errore
Errore
Descrizione
INVALID_CREDENTIALS_ERROR
Password o e-mail sbagliata o il token invalido
  • Suggerimenti: ripeti l'autorizzazione
CARD_ID_NOT_FOUND_ERROR
ll Biglietto da Visita cardId non esiste o non sei autorizzato a modificare questa risorsa
  • Suggerimenti: controlla la richiesta inviata
altri
vedi CODICE-ERRORE nella sezione Autorizzazione

Modificazione delle impostazioni

Parametri
Parametro
Tipo
Descrizione
status
string
<enable, disable>

Modificazione dello status del Biglietto da Visita

  • Comando users
  • Richiesta 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}}

Modificazione dello status della foto

  • Comando users
  • Richiesta 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}}

Modificazione dello status della lingua

  • Comando users
  • Richiesta 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}}
Successo HTTP/1.1 200 OK
{
  "success" : true,
  "errors" : [],
  "result" : {}
}
Fallimento HTTP/1.1 200 OK
{
  "success" : false,
  "errors" : [codice-di-errore],
  "result" : {}
}
codice-di-errore
Errore
Descrizione
tutti
vedi CODICE-ERRORE nella sezione Memorizzazione dei dati

Download dei dati

  • Comando users
  • Richiesta 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}}" \
Successo HTTP/1.1 200 OK
{
"success": true,
"errors" : [],
"result" : {
  "translatable" : {
    "lang" : {
      "langStatus" : "1",
      "chiave" : "valore"
    },
    "lang" : {
      "langStatus" : "0",
      "chiave" : "valore"
    }
  },
  "non-translatable" : {
    "thumbnail" : "base64_encoded_image",
    "chiave" : "valore"
  },
  "settings" : {
    "cardStatus" : "1",
    "usePhoto" : "1",
    "cardQrc" : "base64_encoded_image",
    "cardAddr" : "URL",
    "usePhoto" : "1"
  }
}
Fallimento HTTP/1.1 200 OK
{
  "success" : false,
  "errors" : [codice-di-errore],
  "result" : {}
}
codice-di-errore
Errore
Descrizione
INVALID_CREDENTIALS_ERROR
Password o e-mail sbagliata o il token invalido
  • Suggerimenti: ripeti l'autorizzazione
CARD_ID_NOT_FOUND_ERROR
ll Biglietto da Visita cardId non esiste o non sei autorizzato a modificare questa risorsa
  • Suggerimenti: controlla la richiesta inviata
altri
vedi CODICE-ERRORE nella sezione Autorizzazione

Rimozione dei dati

Rimozione della lingua

  • Comando users
  • Richiesta 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}}" \

Rimozione del Profilo

  • Comando users
  • Richiesta 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}}" \
Successo HTTP/1.1 200 OK
{
  "success" : true,
  "errors" : [],
  "result" : {}
}
Fallimento HTTP/1.1 200 OK
{
 "success" : false,
 "errors" : [codice-di-errore],
 "result" : {}
}
codice-di-errore
Errore
Descrizione
INVALID_CREDENTIALS_ERROR
Password o e-mail sbagliata o il token invalido
  • Suggerimenti: ripeti l'autorizzazione
CARD_ID_NOT_FOUND_ERROR
ll Biglietto da Visita cardId non esiste o non sei autorizzato a modificare questa risorsa
  • Suggerimenti: controlla la richiesta inviata
altri
vedi CODICE-ERRORE nella sezione Autorizzazione
Pagina precedente