API - Boncado

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.

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

curl
php

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

curl
php

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": "2336",
   "online": true,
   "name": "",
   "alias": "5f1c1ce0effc5a",
   "street": "",
   "street2": "",
   "house_number": "",
   "post_code": "",
   "city": "",
   "country": "",
   "latitude": "0.000000",
   "longitude": "0.000000",
   "email": "",
   "email2": "",
   "phone": "",
   "mobile": "",
   "facebook": "",
   "instagram": "",
   "linkedin": "",
   "website": "",
   "category1": "0",
   "category2": "0",
   "nace": "",
   "iban": "",
}

BUSINESS >> LIST

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

Endpoint

GET /v1/business

curl
php

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

curl
php

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

curl
php

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é.

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": ,
   "refund_date": ,
}

VOUCHER >> LIST

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

Endpoint

GET /v1/vouchers

curl
php

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

curl
php

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

curl
php

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

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

Payer avec une carte bancaire

Payer avec un chèque Boncado

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

Veuillez indiquer l'identifiant alphanumérique de votre Boncado

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

javascript
php

$.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

Article	Qté	Prix	Sous-total
Article 1	2	10,00€	20,00€
Article 1	1	10,00€	10,00€
Total			30,00€
Méthode de paiement			Boncado 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);

API Boncado

Clé API

Erreurs

ME

ME >> Définition

login string

emails array

company string

vatnumber string

first_name string

last_name string

street string

street2 string

house_number string

mail_box string

city string

post_code string

country string

phone string

mobile_phone string

newsletter_flag boolean

language string

plan string

iban string

expiration_date date

ME >> GET

ME >> PATCH

BUSINESS

BUSINESS >> Définition

id string

online boolean

name string

alias string

street string

street2 string

house_number string

post_code string

city string

country string

latitude string

longitude string

email string

email2 string

phone string

mobile string

facebook string

instagram string

linkedin string

website string

category1 string

category2 string

nace string

iban string

BUSINESS >> LIST

BUSINESS >> GET

BUSINESS >> PATCH

VOUCHER

VOUCHER >> Définition

voucher_value decimal

voucher_majoration_value string

where_type string

promoter_id string

business string

gift_from string

gift_to string

majs array

delivery string

host string

expiration_date string

voucher_id string

is_recorded int

refund_date date

VOUCHER >> LIST

VOUCHER >> GET

VOUCHER >> PATCH

USER CASE 1

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

USER CASE 1 >> Collecter l'identifiant du Boncado

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

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

login `string`

emails `array`

company `string`

vatnumber `string`

first_name `string`

last_name `string`

street `string`

street2 `string`

house_number `string`

mail_box `string`

city `string`

post_code `string`

country `string`

phone `string`

mobile_phone `string`

newsletter_flag `boolean`

language `string`

plan `string`

iban `string`

expiration_date `date`

id `string`

online `boolean`

name `string`

alias `string`

street `string`

street2 `string`

house_number `string`

post_code `string`

city `string`

country `string`

latitude `string`

longitude `string`

email `string`

email2 `string`

phone `string`

mobile `string`

facebook `string`

instagram `string`

linkedin `string`

website `string`

category1 `string`

category2 `string`

nace `string`

iban `string`

voucher_value `decimal`

voucher_majoration_value `string`

where_type `string`

promoter_id `string`

business `string`

gift_from `string`

gift_to `string`

majs `array`

delivery `string`

host `string`

expiration_date `string`

voucher_id `string`

is_recorded `int`

refund_date `date`