Intégrations POS

La page de paramètres Intégrations relie un serveur HandyCafe éligible à un terminal Ödeal D2D. La disponibilité est vérifiée auprès de HandyCafe Cloud. Le menu et la page sont entièrement masqués lorsque le café n'est pas autorisé à utiliser Ödeal.

Avant de commencer

Vous avez besoin d'un abonnement HandyCafe Cloud actif, d'une clé marchand Ödeal et d'une clé secrète Ödeal. Vous devez également créer le terminal dans l'espace Cihazlarım d'Ödeal. Le nom exact attribué à ce terminal constitue son externalDeviceKey. Commencez par l'environnement Stage. Ne passez en Production qu'une fois les identifiants de production et la configuration des callbacks validés par Ödeal.

Configurer Ödeal

1. Ouvrez Paramètres et sélectionnez Intégrations.
2. Dans Compte Ödeal, saisissez la clé marchand et la clé secrète fournies par Ödeal. HandyCafe envoie ces valeurs directement à HandyCafe Cloud. Elles y sont chiffrées, ne sont pas stockées dans la base de données locale et ne sont plus jamais affichées.
3. Sélectionnez Test de connexion. Lorsque de nouvelles clés sont présentes, HandyCafe les enregistre de façon sécurisée avant de tester la connexion à l'API Ödeal. Ce test vérifie uniquement le compte Ödeal. Il ne prouve pas que le terminal est appairé ou en ligne.
4. Ajoutez le terminal. Saisissez un nom d'appareil local explicite. Dans Nom d'appareil Ödeal (externalDeviceKey), saisissez le nom d'appareil exact créé dans Ödeal. Renseignez ensuite le PaxID facultatif, l'environnement, le délai d'attente de paiement, la ville du client, le district du client, le taux de TVA des sessions et le taux de TVA des commandes.
5. Activez Intégration POS active puis sélectionnez Enregistrer.
6. Réalisez un ticket en espèces et un paiement par carte en environnement Stage pour vérifier l'appairage du terminal et les deux circuits d'encaissement.

Un seul terminal Ödeal actif est pris en charge par serveur dans cette version. Cela évite qu'un paiement soit acheminé vers un terminal non souhaité tant qu'aucun sélecteur de terminal n'est disponible côté caisse.

HandyCafe enregistre l'inventaire des terminaux en local avant que Cloud ne vérifie une nouvelle paire d'identifiants. Un rejet des identifiants par Ödeal ne fait perdre ni le nom du terminal ni les champs d'appairage. Un terminal qui nécessite de nouveaux identifiants est conservé comme inactif jusqu'à la vérification de ces identifiants pour l'environnement sélectionné.

La page Intégrations lit l'inventaire des terminaux directement dans la base de données SQLite locale et l'affiche sans attendre Cloud. Seuls l'état des identifiants chiffrés et l'autorisation du fournisseur distant nécessitent une requête vers Cloud.

Si Ödeal refuse la configuration, HandyCafe affiche l'explication renvoyée par Ödeal. Une réponse indiquant qu'aucun profil d'organisation n'a été trouvé signifie que la paire clé marchand et clé secrète n'appartient à aucune organisation dans l'environnement Stage ou Production sélectionné.

Comportement des paiements

Lorsque le mode de paiement actif correspond aux espèces ou à la carte, l'encaissement d'une session PC, l'encaissement d'une session console et la clôture d'une commande indépendante envoient un panier idempotent à Ödeal. Les espèces sont transmises via l'option de paiement CASH documentée par Ödeal. Le terminal enregistre le paiement en espèces et imprime le ticket fiscal ou le reçu e-Archive sans ouvrir d'écran d'encaissement par carte. La carte est transmise en CREDITCARD ; HandyCafe attend le résultat du callback pendant que le client finalise le paiement sur le terminal. Un encaissement mêlant espèces et carte envoie les deux options de paiement avec leurs montants respectifs.

Le client peut choisir un paiement en plusieurs fois sur le terminal lorsque la carte et le contrat marchand le permettent. Le nombre d'échéances communiqué est enregistré avec la vente locale. La vente locale n'est validée qu'après confirmation de la transaction par Ödeal. Si la validation locale échoue après cette confirmation, HandyCafe demande une annulation le jour même. L'échec de cette annulation génère une erreur de rapprochement manuel qui doit être vérifiée dans le rapport des transactions Ödeal. Les modes de paiement autres que les espèces et la carte continuent de suivre le circuit d'encaissement HandyCafe existant.

Tests et opérations sur le terminal

Le Test de connexion vérifie uniquement les identifiants marchand Ödeal et l'accès à l'API. Il n'imprime aucun ticket, ne débite aucune carte et ne prouve pas que externalDeviceKey est appairé avec le terminal.

La documentation de l'API D2D fournie ne définit pas de point de terminaison distinct pour Imprimer un ticket de test ou Débit de test. La recette s'effectue avec des paniers normaux dans l'environnement Stage : envoyez un panier en espèces et vérifiez le ticket imprimé, puis envoyez un panier carte et réalisez une transaction comptant ou en plusieurs fois sur le terminal. Utilisez uniquement les données de carte de test Stage fournies par Ödeal.

Les cas de recette Ödeal incluent la clôture de journée et la réimpression du dernier ticket. Ce sont toutefois des opérations propres au terminal. D2D ne documente aucun appel API distant pour ces actions, HandyCafe ne les expose donc pas sous forme de boutons de commande à distance.

Activation et désactivation à distance

Les administrateurs HandyCafe pilotent Ödeal depuis Admin > Paramètres d'administration > Fournisseurs POS dans le tableau de bord HandyCafe. Le commutateur global constitue le contrôle principal. Les valeurs par défaut par pays utilisent les codes ISO à deux lettres, par exemple TR. Les contrôles par café permettent d'ouvrir ou de fermer explicitement Ödeal pour une licence donnée. Une décision propre à un café prévaut sur la valeur par défaut du pays. Réinitialiser la décision du café le fait de nouveau suivre son pays.

L'ordre de décision est le suivant : commutateur global, décision propre au café puis valeur par défaut du pays. Un commutateur global désactivé ferme Ödeal pour tous les cafés. Une fermeture explicite au niveau du café masque la page même si son pays est ouvert. Une ouverture explicite au niveau du café autorise la page même si son pays ne figure pas dans la liste par défaut. Couper l'accès bloque immédiatement la création de nouveaux paniers. Les transactions en attente existantes peuvent toujours être vérifiées ou annulées afin qu'un paiement en cours ne reste pas bloqué.

Le serveur vérifie la disponibilité auprès de HandyCafe Cloud et met en cache la dernière décision pays/café vérifiée avec succès. Le catalogue des fournisseurs renvoie un HTTP 200 accompagné d'un error.code structuré lorsque son identifiant est invalide. L'application de bureau traite cette réponse en actualisant l'identifiant puis en réessayant. Une panne temporaire d'authentification ou de réseau ne transforme pas une décision d'activation prise par l'administrateur en désactivation, le menu Intégrations reste donc stable. Une réponse ultérieure réussie met immédiatement le cache à jour, y compris pour une décision de désactivation par l'administrateur. En l'absence de décision vérifiée au préalable, un pays de café inconnu, un abonnement inactif ou un fournisseur désactivé maintient la page masquée. Toute nouvelle opération Ödeal fait toujours l'objet d'une nouvelle autorisation par Cloud, même lorsque la visibilité mise en cache est utilisée. Le pays enregistré sur la licence est utilisé lorsque le profil de café synchronisé n'en comporte aucun.

Sécurité et récupération

Les identifiants Ödeal sont chiffrés dans HandyCafe Cloud avec la clé du coffre de déploiement. Les requêtes de callback sont authentifiées par la clé de requête configurée ou par les en-têtes marchand et secret d'Ödeal. Les codes de référence de panier sont stables pour chaque commande ou session. Répéter le même encaissement ne crée pas un second débit.

L'annulation Ödeal n'est possible que dans le cadre des règles d'Ödeal pour le jour même, avant la clôture du lot du terminal. Un panier en attente peut être supprimé séparément avant la fin du paiement. Ödeal D2D ne propose pas d'opération de remboursement générale. Utilisez le back-office et le rapport des transactions Ödeal une fois la fenêtre d'annulation écoulée.

Ödeal D2D ne propose aucune opération documentée de rapport Z ou de clôture de journée à distance. Effectuez la clôture de journée sur le terminal. HandyCafe peut lire les rapports de transactions à des fins de rapprochement et enregistre les callbacks payback envoyés par Ödeal.