API Deluxe WebFidelity® - Documentation technique

Vue d'ensemble

L'API n'expose pas une URL par fonction : un seul point d'entrée reçoit toutes les requêtes, et un champ request dans le corps JSON indique l'opération à exécuter. C'est ce champ - pas l'URL - qui distingue les 9 fonctions ci-après.

POINT D'ENTRÉE

https://webapp.deluxe-informatique.com/WebFidelity/api.php

Valeur de source pour iOS : le serveur n'accepte que quatre valeurs pour ce champ : WEB, VFP, Android ou IPhone. L'application iOS doit envoyer "source": "IPhone" - toute autre valeur (comme "iOS") sera rejetée.

Méthode HTTP	Format du corps	Réponse	Encodage
POST uniquement	`application/json`	`application/json; charset=utf-8`	UTF‑8

Flux d'authentification

Toute intégration suit la même séquence, dans cet ordre, avant de pouvoir appeler les fonctions métier :

Étape	Appel	Résultat
1	checkApiConnect	Vérifie que le serveur répond
2	getToken	Ouvre une session applicative : renvoie le jeton `tk` et le `subscription_Id`
3	getCard, saveCard, …	Chaque appel suivant transmet `tk` + `subscription_Id` + `suid` + `keyword` + `source`

Le jeton est vérifié à chaque appel. Le serveur recalcule le payload du JWT et compare subscription_Id, suid, keyword et source à ce qui a été signé lors de getToken. Si l'un de ces champs diffère, ou si le jeton est expiré, l'appel est rejeté - les 4 valeurs doivent donc être conservées telles quelles côté client entre les deux appels.

Format des erreurs

Toutes les réponses partagent la même enveloppe. Le client teste uniquement la valeur du champ Response.

SUCCÈS

{
  "Response": "Done",
  ... champs propres à l'appel
}

ÉCHEC

{
  "Response": "Error",
  "errorMessage": "Card not found!"
}

Les messages d'erreur métier (carte introuvable, email déjà utilisé, PIN invalide…) sont renvoyés en français, prêts à être affichés à l'utilisateur.

01 POST request = "checkApiConnect"

Vérifier la connexion au serveur

Appelé au lancement de l'app

Un simple ping applicatif, sans authentification. Sert à détecter une coupure réseau avant de tenter getToken.

REQUÊTE

{ "request": "checkApiConnect" }

RÉPONSE

{ "Response": "Done" }

02 POST request = "getToken"

Ouvrir une session (authentification)

Identifie le client de la plateforme SaaS (suid + keyword) et renvoie le jeton tk à réutiliser dans tous les appels suivants, ainsi que les informations de son abonnement.

Paramètre	Type	Requis	Description
uid	string	oui	Identifiant unique généré côté client pour cet appel
suid	string	oui	Identifiant du client dans la base Deluxe WebFidelity®
keyword	string	oui	Clé secrète associée à ce client
source	string	oui	`WEB` · `VFP` · `Android` · `IPhone`

Valeurs de uid et keyword : ces identifiants sont propres à chaque client de la plateforme et vous sont communiqués séparément, par e‑mail. Ils ne figurent pas dans ce document - les exemples ci‑dessous utilisent des valeurs de remplacement.

REQUÊTE

{
  "request": "getToken",
  "uid": "<uid généré par votre application>",
  "suid": "<suid fourni par e-mail>",
  "keyword": "<keyword fourni par e-mail>",
  "source": "IPhone"
}

RÉPONSE

{
  "Response": "Done",
  "subscription_Id": 5,
  "companyName": "Nom du client",
  "state_Id": 1,
  "stateName": "Actif",
  "userEmail": "contact@client.com",
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
}

Champ state_Id : si sa valeur n'est pas 1, l'abonnement de ce client est désactivé - l'application doit bloquer l'accès même si le jeton est valide.

03 POST request = "getCard"

Récupérer une carte de fidélité

Renvoie l'état complet d'une carte : identité du porteur, statuts de vérification et solde de points. Accepte soit l'identifiant interne, soit le code imprimé sur la carte physique - voir fonction 07 pour ce second usage.

Paramètre	Type	Requis	Description
card_Id	integer	l'un des deux	Identifiant interne de la carte
code	integer	l'un des deux	Code de carte (6 à 8 chiffres)
is_Demo	0/1	non	Renvoie une carte fictive, sans toucher la base - utile pour développer sans compte réel

REQUÊTE

{
  "request": "getCard",
  "card_Id": 3,
  "is_Demo": 0
}

RÉPONSE

{
  "Response": "Done",
  "id": 3,
  "code": 18000003,
  "firstName": "Jean",
  "lastName": "Dupont",
  "ddn": "1980-01-01",
  "email": "jean.dupont@example.com",
  "mobile": "+253 70 123 456",
  "is_Disable": 0,
  "is_vMail": 1,
  "is_vMobile": 1,
  "solde": 0.0
}

04 POST request = "saveCard"

Créer ou modifier une carte

id = 0 crée une nouvelle carte ; tout autre id met à jour la carte existante. Le serveur valide chaque champ et renvoie un message d'erreur explicite en cas de rejet.

Paramètre	Type	Requis	Règle de validation
id	integer	oui	`0` pour une création
typeId	integer	oui	Type de carte
code	integer	selon contexte	6 à 8 chiffres, doit être unique
pin	integer	oui	4 chiffres (1000–9999)
firstName / lastName	string	oui	Non vides
ddn	date	oui	Date de naissance valide
email	string	oui	Format valide, unique sur l'abonnement
mobile	string	oui	8 chiffres minimum

REQUÊTE

{
  "request": "saveCard",
  "id": 0,
  "typeId": 1,
  "pin": 1234,
  "firstName": "Skander",
  "lastName": "SLITI",
  "ddn": "1980-01-01",
  "email": "skander@example.com",
  "mobile": "11223344"
}

RÉPONSE - SUCCÈS

{
  "Response": "Done",
  "id": 14,
  "code": 100014,
  "name": "Skander SLITI",
  "pin": 1234,
  "is_vMail": 0,
  "is_vMobile": 0
}

RÉPONSE - VALIDATION ÉCHOUÉE

{
  "Response": "Error",
  "errorMessage": "L'Email skander@example.com est déjà utilisé !"
}

05 POST request = "modifyPinCode"

Modifier le code PIN

Change le code PIN utilisé lors des paiements par points. Une confirmation est envoyée par email au porteur de la carte.

Paramètre	Type	Requis	Description
card_Id	integer	oui	Identifiant de la carte
pinCode	integer	oui	4 chiffres (1000–9999)
is_Demo	0/1	non	Simule un succès sans écrire en base

RÉPONSE

{ "Response": "Done" }

06 POST request = "sendConfirmationMail"

Envoyer l'email de confirmation

Envoie un lien de confirmation d'adresse email, valable 10 minutes. Refuse l'envoi si l'adresse est déjà confirmée (is_vMail).

Paramètre	Type	Requis	Description
card_Id	integer	oui	Identifiant de la carte
code	string	oui	Code de la carte, doit correspondre à `card_Id`
appName	string	oui	Nom de l'application affiché dans l'email envoyé au porteur de la carte
source	string	oui	`WEB` · `VFP` · `Android` · `IPhone`

RÉPONSE - DÉJÀ CONFIRMÉ

{
  "Response": "Error",
  "errorMessage": "Votre adresse mail est déjà confirmée !"
}

07 POST request = "getCard"

Rattacher un compte existant

Même opération serveur que la fonction 03, appelée ici avec le code imprimé sur la carte plutôt que l'identifiant interne - l'usage typique est un écran « J'ai déjà une carte » où l'utilisateur saisit son code et son email.

Paramètre	Type	Requis	Description
code	integer	oui	Code imprimé sur la carte physique

La vérification que l'email saisi correspond à celui enregistré sur la carte est effectuée côté client, en comparant le champ email de la réponse à la saisie de l'utilisateur - le serveur ne fait pas cette comparaison lui‑même.

REQUÊTE

{
  "request": "getCard",
  "code": 18000003
}

08 POST request = "getJsonAccount"

Historique du compte

Renvoie le solde de points ainsi que les 200 derniers mouvements (débits et crédits), les plus récents en premier.

Paramètre	Type	Requis	Description
card_Id	integer	oui	Identifiant de la carte

RÉPONSE

{
  "Response": "Done",
  "balance": 245.0,
  "count": 2,
  "items": [
    {
      "date": "04-09-2026",
      "time": "12:41",
      "debit": 0,
      "credit": 50,
      "description": "Achat",
      "posName": "Boutique Centre-ville"
    }
  ]
}

debit et credit sont deux colonnes distinctes plutôt qu'un montant signé unique : un mouvement donné remplit l'une ou l'autre, jamais les deux.

09 POST request = "forgotPinCode"

Récupérer un code PIN oublié

Renvoie le code PIN actuel par email au porteur de la carte - le serveur ne le retourne jamais directement dans la réponse JSON.

Paramètre	Type	Requis	Description
card_Id	integer	oui	Identifiant de la carte
is_Demo	0/1	non	Simule un succès sans envoyer d'email

RÉPONSE

{ "Response": "Done" }

Utiliser l'API Deluxe WebFidelity® depuis une nouvelle application

Vue d'ensemble

Flux d'authentification

Format des erreurs

Vérifier la connexion au serveur

Ouvrir une session (authentification)

Récupérer une carte de fidélité

Créer ou modifier une carte

Modifier le code PIN

Envoyer l'email de confirmation

Rattacher un compte existant

Historique du compte

Récupérer un code PIN oublié