API Tournai City Chèque

L'API Tournai City Chèque 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 Tournai City Chèque. Connectez-vous ou demandez au gestionnaire du compte de vous la transmettre.

Erreurs

Tournai City Chèque 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 Tournai City Chèque.

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 Tournai City Chèque 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 Tournai City Chèque


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 Tournai City Chèque 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 Tournai City Chèque. 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 Tournai City Chèque 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 Tournai City Chèque.

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 Tournai City Chèque. 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 Tournai City Chèque, 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 Tournai City Chèque.


voucher_majoration_value string

Part offerte par un ou plusieurs promoteurs.


where_type string

Type de Tournai City Chèque.


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 Tournai City Chèque.


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 Tournai City Chèque.

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 Tournai City Chèque 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 Tournai City Chèque. 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) Tournai City Chèque 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 Tournai City Chèque.


voucher_template integer

Nombre entier indiquant le visuel Tournai City Chèque à appliquer au recto papier/pdf du chèque-cadeau. Voir les visuels Tournai City Chèque. 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, Tournai City Chèque 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 Tournai City Chèque. 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 Tournai City Chèque 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 Tournai City Chèque

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



USER CASE 1 >> Vérifier la validité du chèque Tournai City Chèque

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 Tournai City Chèque, 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= "Tournai City Chèque 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 Tournai City Chèque 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 paiementTournai City Chèque 30,00€

USER CASE 1 >> Enregistrement du chèque Tournai City Chèque

Lors du traitement final de la commande, l'API est interrogée en PATCH afin d'enregistrer définitivement le chèque Tournai City Chèque 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 Tournai City Chèque 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.