API Boncado

L'API Boncado est organisée sur base de l'architecture REST. Les requêtes effectuées sur l'URI produisent une réponse dont le corps est formaté en JSON. Les méthodes HTTP disponibles sont GET, POST, PUT, PATCH, DELETE. Les tableaux imbriqués et les objects complexes sont à envoyer au format JSON.

URL de base
api.boncado.be

Clé API

Pour utiliser l'API, vous devez fournir votre clé API. Gardez toujours la clé API que nous vous communiquons sur votre dashboard secrète! Cette clé devra être incluse dans chacune des requêtes API

Clé API
La clé API est renseignée dans les paramètres du compte Boncado. Connectez-vous ou demandez au gestionnaire du compte de vous la transmettre.

Erreurs

Boncado utilise des codes de réponse HTTP conventionnels pour indiquer le succès ou l'échec d'une requête API. Les codes de la gamme 2xx indiquent le succès. Les codes dans la plage 4xx indiquent une erreur de formulation de la requête. Les codes de la gamme 5xx indiquent une erreur avec les serveurs de Boncado.

Codes d'erreur
200 Tout s'est déroulé comment attendu!
400 La requête a été rejetée, la raison la plus fréquente est l'oubli d'un paramètre.
401 La clé d'API est inconnue.
402 La requête est correcte mais l'API est incapable de renvoyer une réponse. Cela peut survenir par exemple quand les paramètres du compte sont incomplets.
403 La clé d'API n'octroie pas les permissions nécessaires à la requête.
404 La ressource n'existe pas.
429 Trop de requêtes ont été exécutées dans un délai court.
50x Le serveur Boncado est en échec, nous sommes probablement déjà au courant.

ME

L'objet ME contient les informations relatives à votre profil client. L'API vous permet de récupérer les informations et de modifier certaines valeurs.

ME >> Définition

login string

Adresse email principale et login du compte

emails array

Adresses emails secondaires où recevoir des copies des emails transactionnels Boncado

company string

Nom de société

vatnumber string

Numéro de TVA

first_name string

Prénom

last_name string

Nom de famille

street string

Rue

street2 string

Complément d'adresse

house_number string

Numéro de rue

mail_box string

Boite postale

city string

Localité

post_code string

Code postal

country string

Code pays (ISO 3166-1 alpha-2)

phone string

Numéro de téléphone fixe

mobile_phone string

Numéro de GSM

newsletter_flag boolean

language string

Langue de l'utilisateur

plan string

Plan tarifaire actuel

iban string

Numéro de compte IBAN sur lequel Boncado reverse l'argent des chèques-cadeaux dépensés dans l'un de vos commerces.

expiration_date date

Date du dernier renouvellement de l'abonnement

Objet
{
   "login": "" ,
   "emails": ,
   "company": "" ,
   "vatnumber": "" ,
   "first_name": "" ,
   "last_name": "" ,
   "street": "" ,
   "street2": "" ,
   "house_number": "" ,
   "mail_box": "" ,
   "city": "" ,
   "post_code": "" ,
   "country": "" ,
   "phone": "" ,
   "mobile_phone": "" ,
   "newsletter_flag": false ,
   "language": "" ,
   "plan": "" ,
   "iban": "" ,
   "expiration_date": ,
}

ME >> GET

Renvoyer les informations de votre compte.

Endpoint
GET /v1/me
1. curl https://api.boncado.be/v1/me \
2. -H "Authorization: Bearer " \

ME >> PATCH

Modifier les valeurs éditables de votre compte.

Endpoint
PATCH /v1/me
1. curl https://api.boncado.be/v1/me \
2. -H "Authorization: Bearer " \
3. -d street="Rue Nouvelle"

BUSINESS

L'objet BUSINESS contient les informations relatives à une activité commerciale enregistrée sur votre compte Boncado. L'API vous permet de lister toutes vos activités, de récupérer les informations relatives à une activité et de modifier les valeurs éditables.

BUSINESS >> Définition

id string

Identifiant numérique de l'établissement commercial.

online boolean

Booléen indiquant si l'enseigne est publiée/active.

name string

Nom de l'établissement commercial.

alias string

Fragment d'url unique assigné à l'établissement commercial.

street string

Rue

street2 string

Complément d'adresse

house_number string

Numéro de rue

post_code string

Code postal

city string

Localité

country string

Code pays (ISO 3166-1 alpha-2)

latitude string

Latitude de la position géographique de l'établissement commercial.

longitude string

Longitude de la position géographique de l'établissement commercial.

email string

Email principal.

email2 string

Email secondaire.

phone string

Numéro de téléphone.

mobile string

Numéro de GSM.

facebook string

URL de la page Facebook.

instagram string

URL de la page Instagram.

linkedin string

URL de la page LinkedIn.

website string

URL du site Internet.

category1 string

Secteur d'activité principal de l'établissement commercial.

category2 string

Secteur d'activité secondaire de l'établissement commercial

nace string

Code NACE principal.

iban string

Numéro de compte IBAN sur lequel Boncado reverse l'argent des chèques-cadeaux dépensés dans l'établissement commercial. S'il est renseigné au niveau de BUSINESS, il écrase la valeur définie au niveau ME.

Objet
{
   "id": "591" ,
   "online": false ,
   "name": "Cordage express" ,
   "alias": "cordageexpresswegnez" ,
   "street": "Rue Emile Vandervelde" ,
   "street2": "" ,
   "house_number": "145" ,
   "post_code": "4860" ,
   "city": "Wegnez" ,
   "country": "be" ,
   "latitude": "50.577419" ,
   "longitude": "5.827995" ,
   "email": "coune.j@hotmail.com" ,
   "email2": "" ,
   "phone": "087/81 04 01" ,
   "mobile": "0494 78 83 89" ,
   "facebook": "https://www.facebook.com/cordageexpress/" ,
   "instagram": "https://www.instagram.com/cordage.express/" ,
   "linkedin": "" ,
   "website": "http://www.cordageexpress.be/" ,
   "category1": "634" ,
   "category2": "585" ,
   "nace": "47.640#47.711" ,
   "iban": "" ,
}

BUSINESS >> LIST

Renvoyer une liste des activités commerciales liées à votre compte Boncado.

Endpoint
GET /v1/business
1. curl https://api.boncado.be/v1/business \
2. -H "Authorization: Bearer " \

BUSINESS >> GET

Renvoyer les informations de votre compte.

Endpoint
GET /v1/business/id
1. curl https://api.boncado.be/v1/business/1234 \
2. -H "Authorization: Bearer " \

BUSINESS >> PATCH

Modifier les valeurs éditables de votre compte.

Endpoint
PATCH /v1/business/id
1. curl https://api.boncado.be/v1/business/1234 \
2. -H "Authorization: Bearer " \
3. -d latitude="53"

VOUCHER

L'objet VOUCHER contient les informations relatives à un chèque Boncado. L'API vous permet de lister tous les chèques enregistrés par vos activités commerciales, de vérifier la validité d'un chèque en circulation sur le réseau Boncado, de récupérer les informations relatives à un chèque enregistré et de modifier le statut du chèque.

VOUCHER >> Définition

voucher_value decimal

Valeur faciale du chèque Boncado.

voucher_majoration_value string

Part offerte par un ou plusieurs promoteurs.

where_type string

Type de Boncado.

promoter_id string

Numéro d'identifiant du promoteur lorsque le chèque est vendu via une ville, une association ou un site délabellisé

business string

Numéro de l'établissement commercial.

gift_from string

Nom de la personne qui offre imprimé sur le chèque.

gift_to string

Nom du bénficiaire imprimé sur le chèque.

majs array

Liste des majorations appliquées sur le chèque.

delivery string

Méthode de livraison

host string

Hôte sur lequel le chèque a été acheté.

expiration_date string

Date d'expiration

voucher_id string

Chaîne alphanumérique unique identifiant le chèque Boncado.

is_recorded int

Entier [0,1] indiquant si le chèque a été encaissé.

is_active int

Entier [0,1] indiquant si le chèque est actif.

refund_date date

Date à laquelle le bon a été reversé au commerçant.

Objet
{
   "voucher_value": ,
   "voucher_majoration_value": "" ,
   "where_type": "" ,
   "promoter_id": "" ,
   "business": "" ,
   "gift_from": "" ,
   "gift_to": "" ,
   "majs": ,
   "delivery": "" ,
   "host": "" ,
   "expiration_date": "" ,
   "voucher_id": "" ,
   "is_recorded": ,
   "is_active": ,
   "refund_date": ,
}

VOUCHER >> LIST

Renvoyer une liste des chèques enregistrés/encaissés depuis votre compte Boncado.

Endpoint
GET /v1/vouchers
1. curl https://api.boncado.be/v1/vouchers \
2. -H "Authorization: Bearer " \

VOUCHER >> GET

Renvoyer les informations relatives à un chèque cadeau. Cette requête API vous permet de vérifier qu'un chèque Boncado est valide et peut-être accepté comme mode de paiement.

Endpoint
GET /v1/voucher/id
1. curl https://api.boncado.be/v1/voucher/XXXXXXXXXXXXX \
2. -H "Authorization: Bearer " \

VOUCHER >> PATCH

Modifier le statut d'un chèque en circulation, à utiliser pour l'acceptation d'un chèque sur un site e-commerce.

Endpoint
PATCH /v1/voucher/id
1. curl https://api.boncado.be/v1/voucher/XXXXXXXXXXXXX \
2. -H "Authorization: Bearer " \
3. -d is_recorded ="1"

CHECKOUT

L'objet CHECKOUT contient les informations nécessaires à l'achat d'un chèque Boncado. Ce point d'ancrage est à utiliser dans une requête POST et retourne soit une URL où le paiement peut-être finalisé, soit - losque vous travaillez dans un cadre de facturation mensuelle - directement la/les chaîne(s) alphanumérique(s) unique(s) identifiant le(s) chèque(s) Boncado généré(s).

CHECKOUT >> Définition

voucher_qty integer

Nombre entier indiquant le nombre de chèques à générer

voucher_value decimal

Valeur faciale et unitaire du chèque Boncado.

voucher_template integer

Nombre entier indiquant le visuel Boncado à appliquer au recto papier/pdf du chèque-cadeau. Voir les visuels Boncado. Par défaut la valeur est 480.

delivery object

Données de livraison. En fonction de la propriété type, certains champs deviennent requis/facultatifs.

type string

Méthode de livraison. Valeurs acceptées: "post","email". Par défaut "email"

last_name string

Nom.

first_name string

Prénom.

street string

Rue. Requis si type=post.

house_number string

Numéro de rue. Requis si la propriété type a la valeur 'post'.

house_box string

Numéro de de boîte. Requis si la propriété type a la valeur 'post'.

pc string

Code postal. Requis si la propriété type a la valeur 'post'.

city string

Localité. Requis si la propriété type a la valeur 'post'.

email string

Adresse email. Requis si la propriété type a la valeur 'email' et si la propriété phone est vide ou nulle.

phone string

Numéro de téléphone. Requis si la propriété type a la valeur 'email' et si la propriété email est vide ou nulle.

gift_from string

Nom de la personne qui offre imprimé sur le chèque.

gift_to string

Nom du bénficiaire imprimé sur le chèque.

gift_reason string

Message personnel à l'attention du bénéficiaire du chèque-cadeau.

billing object

Données de facturation. Si cet objet est null, le chèque sera facturé au compte associé au jeton API à condition que ce compte soit dans le cadre de la facturation mensuelle.

last_name string

Nom.

first_name string

Prénom.

street string

Rue.

house_number string

Numéro de rue.

house_box string

Numéro de de boîte.

pc string

Code postal.

city string

Localité.

email string

Adresse email.

success_url string

URL où rediriger l'acheteur après un paiement réussi.

cancel_url string

URL où rediriger l'acheteur après un paiement en échec.

webhook string

Avec un webhook, Boncado peut transmettre des notifications en temps réel à votre application sous forme de charge utile JSON, grâce au protocole HTTPS.

Objet
{
   "voucher_qty": ,
   "voucher_value": ,
   "voucher_template": ,
   "delivery":
{
   "type": "",
   "last_name": "",
   "first_name": "",
   "street": "",
   "house_number": "",
   "house_box": "",
   "pc": "",
   "city": "",
   "email": "",
   "phone": "",
}
,
   "gift_from": "" ,
   "gift_to": "" ,
   "gift_reason": "" ,
   "billing":
{
   "last_name": "",
   "first_name": "",
   "street": "",
   "house_number": "",
   "house_box": "",
   "pc": "",
   "city": "",
   "email": "",
}
,
   "success_url": "" ,
   "cancel_url": "" ,
   "webhook": "" ,
}

CHECKOUT >> POST

Générer une quantité de chèques-cadeaux Boncado. Envoyer paramètres au format JSON.

Endpoint
POST JSON /v1/checkout
1. curl https://api.boncado.be/v1/checkout \
2. -H "Authorization: Bearer " \
3. -H "Content-Type: application/json" \
4. -X "POST" \
5. -d '{"voucher_qty":1,"voucher_value":2,"voucher_template":3,"delivery":{"type":"print","last_name":"Jane","first_name":"Doe","street":"Elm street","house_number":"2","house_box":"","pc":"4000","city":"Alpha Town","email":"janedoe@boncado.be","phone":""},"gift_from":"John","gift_to":"Jane","gift_reason":"Happy BDay!","buyer":{"last_name":"Doe","first_name":"John","street":"Elm street","house_number":"2","house_box":"","pc":"4000","city":"Alpha Town","email":"janedoe@boncado.be","success_url":"","cancel_url":""}}'

USER CASE 1

Proposer un voucher Boncado comme méthode de paiement

USER CASE 1 >> Choix de la méthode de paiement

A l'étape de paiement, le client choisir sa méthode de paiement et dans le cas qui nous intéresse la possibilité de payer avec un chèque cadeau

USER CASE 1 >> Collecter l'identifiant du Boncado

Le client indique dans un champ texte l'identifiant alphanumérique unique du chèque Boncado qu'il désire utiliser

USER CASE 1 >> Vérifier la validité du chèque Boncado

L'identifiant alphanumérique est inclus dans une requête AJAX. Du côté serveur, l'API est interrogée en GET et renvoie les données relatives au chèque Boncado, et notamment s'il est valide et suffisamment alimenté pour permettre de poursuivre la procédure d'achat.

Endpoint
GET /v1/voucher/id
$.ajax({
  type: "POST",
  url: "/ajax.php",
  data: {
    action: "checkvoucher",
    voucherid: $("#voucher-code"),
  },
  datatype: "json",
  success: function (response) {
    if(response.code==1){
      document.location.href=response.value
    }else{
      alert(response.value);
    }
  }
});
$baseurl = "https://api.boncado.be";
$endpoint = "/v1/voucher/".$_POST["voucherid"];
$apiKey = "";
$headers = array(
  "Authorization: Bearer " . $apiKey
);
$ch = curl_init($baseurl . $endpoint);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
$voucher = curl_exec($ch);
$voucher=json_decode($voucher);
if ($voucher->voucher_value >= $carttotal && $voucher->expiration_date>=date("Y-m-d") && $voucher->is_recorded==0) {
  $value= "/overview";
  $code = 1;
} else {
  $value= "Boncado invalide";
  $code = -1;
}
$response = array(
  "code" => $code,
  "value" => $value,
);
echo json_encode($response);

USER CASE 1 >> Le chèque est valide, le panier est récapitulé

Le client indique dans un champ texte l'identifiant alphanumérique unique du chèque Boncado qu'il désire utiliser

Récapitulatif

ArticleQtéPrixSous-total
Article 1210,00€20,00€
Article 1110,00€10,00€
Total30,00€
Méthode de paiementBoncado 30,00€

USER CASE 1 >> Enregistrement du chèque Boncado

Lors du traitement final de la commande, l'API est interrogée en PATCH afin d'enregistrer définitivement le chèque Boncado dont la valeur sera reversée au marchand.

Endpoint
PATCH /v1/voucher/id
$baseurl = "https://api.boncado.be";
$apiKey = "";
$headers = array(
  "Authorization: Bearer " . $apiKey
);
$endpoint = "/v1/voucher/" . $voucherid;
$ch = curl_init($baseurl . $endpoint);
$post = [
  "is_recorded" => 1,
];
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $post);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($ch);
curl_close($ch);

Le site Internet Boncado utilise des cookies. Certains cookies sont nécessaires au bon fonctionnement du site Internet et, s'ils sont désactivés, provoquent une dégradation de l'expérience utilisateur ou désactivent certaines fonctionnalités du site. D'autres cookies sont utilisés à des fins d'analyse ou de marketing.

Accepter les cookies

Gérer les cookies