Comment connecter KdoFid à votre TPE ou caisse enregistreuse

Vous utilisez un TPE ou une caisse enregistreuse qui n'est pas nativement intégré à KdoFid ? Pas de panique. KdoFid propose une solution universelle par webhook et API REST qui fonctionne avec la quasi-totalité des logiciels de caisse du marché. Ce guide vous explique les deux méthodes de connexion disponibles et vous aide à choisir celle qui convient à votre situation.

Temps estimé : 20 à 40 minutes (selon la méthode choisie)

Sommaire

• Prérequis
• Étape 1 : Comprendre les deux méthodes de connexion
• Étape 2 : Générer votre clé API et votre webhook KdoFid
• Étape 3 : Méthode A — Connexion par webhook (pour les caisses compatibles)
• Étape 4 : Méthode B — Connexion par API directe (avec l'aide d'un prestataire)
• Étape 5 : Tester et valider la connexion
• Problèmes fréquents et solutions
• Conclusion

Prérequis

Avant de commencer, identifiez les éléments suivants :

• Un compte KdoFid actif en offre Pro ou Enterprise
• Le nom exact de votre logiciel de caisse ou TPE (fabricant, modèle, version)
• La capacité de votre caisse à envoyer des données vers des services externes (renseignez-vous auprès de votre fournisseur caisse ou lisez la documentation technique)
• Un accès administrateur sur votre logiciel de caisse
• Si votre caisse n'est pas compatible webhook : les coordonnées de votre prestataire informatique ou du support technique de votre caisse

Bon à savoir : Si vous utilisez Lightspeed ou SumUp, des guides dédiés et simplifiés existent pour ces deux solutions. Ce guide est destiné aux autres systèmes de caisse (Clover, iZettle, Zettle, Square, logiciels propriétaires, TPE bancaires avec API, etc.).

Étape 1 : Comprendre les deux méthodes de connexion

KdoFid propose deux approches pour se connecter à n'importe quel système de caisse :

Méthode A — Webhook (recommandée pour les non-développeurs)

Un webhook est une notification automatique que votre caisse envoie à KdoFid à chaque événement (nouvelle vente, remboursement, etc.). Imaginez-le comme un sonnette : quand une vente est enregistrée dans votre caisse, elle "sonne" chez KdoFid, qui déclenche alors le crédit de points.

Cette méthode est recommandée si :

• Votre logiciel de caisse supporte nativement les webhooks (la plupart des solutions modernes le font)
• Vous ne souhaitez pas faire appel à un développeur

Méthode B — API directe (pour les caisses sans support webhook)

L'API directe permet à votre logiciel de caisse d'interroger KdoFid de manière proactive : après chaque vente, il envoie une requête à KdoFid pour créditer les points. Cette méthode nécessite généralement l'intervention d'un prestataire informatique ou d'un développeur qui connaît votre logiciel de caisse.

Choisissez la méthode selon vos capacités techniques et la compatibilité de votre caisse.

Étape 2 : Générer votre clé API et votre webhook KdoFid

Quelle que soit la méthode choisie, vous avez besoin des éléments de connexion KdoFid.

Clé API :

1. Connectez-vous à app.kdofid.fr
2. Allez dans Paramètres > API et intégrations
3. Cliquez sur "Créer une clé API"
4. Nommez-la : Caisse - [Nom ou modèle de votre caisse]
5. Environnement : Production (live)
6. Permissions requises :

- transactions:write

- customers:read

- customers:write

- rewards:read

- rewards:write

1. Cliquez sur "Générer" et copiez immédiatement la clé

URL de webhook KdoFid :

1. Dans la même page Paramètres > API et intégrations, descendez jusqu'à la section "Webhooks entrants"
2. Cliquez sur "Créer un webhook entrant"
3. Nommez-le : Caisse - [Nom de votre système]
4. Sélectionnez le format de données que votre caisse envoie (JSON ou form-encoded — vérifiez dans la documentation de votre caisse)
5. Cliquez sur "Générer l'URL"

KdoFid génère une URL unique de la forme :

```

https://api.kdofid.fr/webhooks/incoming/wh_xxxxxxxxxxxxxxxx

```

Notez cette URL — c'est l'adresse à saisir dans votre logiciel de caisse.

Identifiant de programme :

Toujours sur cette page, notez également votre Program ID (identifiant du programme de fidélité) — visible en haut de la page sous la forme prog_xxxxxxxxxxxxxxxx.

Étape 3 : Méthode A — Connexion par webhook

Cette méthode est réalisable sans développeur si votre logiciel de caisse dispose d'une section "Webhooks" ou "Notifications HTTP" dans ses paramètres.

Configuration dans votre logiciel de caisse :

La procédure exacte varie selon votre caisse, mais les étapes générales sont :

1. Ouvrez les paramètres de votre logiciel de caisse
2. Recherchez une section nommée : "Webhooks", "Notifications HTTP", "Intégrations tierces" ou "API"
3. Cliquez sur "Ajouter un webhook" ou "Nouvelle notification"
4. Renseignez les champs suivants :

- URL de destination : collez l'URL de webhook KdoFid générée à l'étape 2

- Événement déclencheur : sélectionnez "Nouvelle vente" ou "Transaction complétée"

- Format : JSON (si le choix est proposé)

- Méthode HTTP : POST

1. Si un champ "Secret" ou "Signature" est demandé, retournez dans KdoFid sur votre webhook entrant et copiez le Webhook Secret affiché
2. Enregistrez la configuration

Configuration du mappage des données dans KdoFid :

Une fois le webhook créé dans votre caisse, KdoFid doit savoir comment interpréter les données reçues. Chaque logiciel envoie ses données dans un format légèrement différent.

1. Dans KdoFid, allez dans Paramètres > API et intégrations > Webhooks entrants > [Votre webhook]
2. Cliquez sur l'onglet "Mappage des champs"
3. KdoFid affiche un formulaire avec les champs à mapper :

- Montant de la transaction : indiquez le nom du champ JSON de votre caisse (ex: total, amount, sale_total)

- Identifiant client : customer_phone, customer_email ou le nom exact dans votre format

- Date de la transaction : created_at, date, timestamp selon votre caisse

- Référence de la transaction : id, receipt_number, transaction_id

Si vous ne connaissez pas les noms exacts des champs de votre caisse, demandez au support de votre logiciel de vous fournir un exemple de payload JSON envoyé lors d'une vente.

1. Cliquez sur "Enregistrer le mappage"

Étape 4 : Méthode B — Connexion par API directe

Si votre caisse ne supporte pas les webhooks, votre prestataire informatique peut programmer un appel API direct vers KdoFid après chaque vente. Voici ce qu'il doit faire.

Endpoint de crédit de points :

```

POST https://api.kdofid.fr/v1/transactions

Authorization: Bearer kf_live_sk_[VOTRE_CLE_API]

Content-Type: application/json

```

Corps de la requête (format JSON) :

```json

{

"program_id": "prog_xxxxxxxxxxxxxxxx",

"customer_identifier": "+33612345678",

"identifier_type": "phone",

"amount": 2500,

"currency": "EUR",

"reference": "TICKET-2026-001",

"timestamp": "2026-03-01T14:30:00Z"

}

```

Description des champs :

• program_id : votre identifiant de programme KdoFid (voir Étape 2)
• customer_identifier : le numéro de téléphone ou email du client
• identifier_type : "phone" ou "email"
• amount : montant de la vente en centimes (2500 = 25,00€)
• currency : "EUR" pour l'euro
• reference : référence unique de la transaction (numéro de ticket)
• timestamp : date et heure de la transaction au format ISO 8601

Réponse de KdoFid en cas de succès :

```json

{

"status": "success",

"points_credited": 25,

"customer_total_points": 340,

"transaction_id": "txn_xxxxxxxxxxxxxxxx"

}

```

Votre prestataire peut utiliser ces informations pour afficher un message sur votre terminal de caisse ("25 points crédités — Total : 340 points").

Documentation complète de l'API :

L'intégralité de la documentation API de KdoFid (tous les endpoints, les codes d'erreur, les exemples) est disponible depuis Paramètres > API et intégrations > Documentation API ou directement sur developer.kdofid.fr.

Étape 5 : Tester et valider la connexion

Une fois la connexion configurée (méthode A ou B), validez-la avec un test complet.

Test avec la Méthode A (webhook) :

1. Effectuez une vente test dans votre logiciel de caisse avec un client test existant dans KdoFid
2. Attendez 30 secondes
3. Vérifiez dans KdoFid (Clients > [Client test] > Historique de points) que la transaction est bien créditée
4. Consultez les logs du webhook dans Paramètres > API et intégrations > Webhooks entrants > [Votre webhook] > Logs — cherchez une entrée "Succès" pour votre transaction test

Test avec la Méthode B (API directe) :

Demandez à votre prestataire d'effectuer un appel API test depuis sa console ou depuis Postman/Insomnia avec les données suivantes :

• Un client test connu dans KdoFid
• Un montant de 1000 (= 10,00€)
• Une référence unique (ex: TEST-001)

Vérifiez que 10 points apparaissent dans l'historique du client test.

Surveillance en temps réel :

Le tableau de bord KdoFid propose un moniteur d'intégration en temps réel accessible depuis Paramètres > API et intégrations > Activité en temps réel. Chaque appel entrant y est affiché avec son statut dans les secondes qui suivent sa réception.

Problèmes fréquents et solutions

Q: Mon logiciel de caisse envoie bien les données mais KdoFid retourne une erreur 400 (bad request).

R: Une erreur 400 signifie que les données envoyées par votre caisse ne correspondent pas au format attendu par KdoFid. Consultez les logs dans Paramètres > API et intégrations > Logs et cliquez sur la requête en erreur pour voir le détail du message d'erreur. Les causes les plus fréquentes sont : un montant non exprimé en centimes (KdoFid attend 1000 pour 10€, pas 10.00), un champ obligatoire manquant (notamment program_id), ou un format de date incorrect.

Q: Le client est identifié dans ma caisse mais KdoFid dit qu'il n'existe pas.

R: Ce problème survient lorsque le numéro de téléphone ou l'email dans votre caisse n'est pas identique à celui enregistré dans KdoFid. Vérifiez le format du numéro de téléphone : KdoFid attend le format international avec indicatif pays (+33612345678 et non 0612345678). Si le client existe dans KdoFid mais avec un email différent, vous pouvez activer la "création automatique de client" dans les paramètres du webhook pour créer automatiquement la fiche KdoFid si le client n'est pas trouvé.

Q: Les points sont crédités en double pour certaines transactions.

R: Ce problème indique que votre caisse envoie le même événement deux fois (double envoi). Vérifiez dans les logs KdoFid que deux entrées identiques apparaissent pour la même référence de transaction. Pour résoudre ce problème, KdoFid dispose d'une protection anti-doublon basée sur le champ reference : assurez-vous que chaque transaction envoie une référence unique et non-vide. Activez le paramètre "Déduplication stricte" dans Paramètres > API et intégrations > [Votre intégration] > Paramètres avancés.

Conclusion

Quel que soit votre système de caisse, KdoFid offre une solution de connexion adaptée : webhook natif pour les caisses modernes compatibles, ou API directe pour les configurations sur mesure. Une fois la connexion établie, votre programme de fidélité fonctionne en totale autonomie, sans aucun geste supplémentaire de la part de vos équipes.

Cette flexibilité est l'une des forces de KdoFid pour les commerces de proximité : vous n'avez pas à changer votre matériel ni votre habitude de travail. Le programme de fidélité s'intègre silencieusement à votre flux de caisse existant et enrichit chaque transaction d'une dimension de fidélisation automatique.

Pour toute question spécifique à votre logiciel de caisse, l'équipe support KdoFid est disponible par chat depuis votre tableau de bord et peut vous orienter vers le bon type d'intégration.

Prêt à lancer votre programme de fidélité ?

Créez votre compte KdoFid gratuitement →

Article mis à jour le 2026-03-01. Catégorie : Guides pratiques. Temps de lecture : 11 min.