API de loterie : tirages, résultats et règlement
L’intégration d’une API de tirages et de résultats de loterie doit conserver le lien entre le bon tirage, le billet accepté, le résultat autorisé et le règlement qui en découle. La difficulté consiste à définir les heures limites de vente, les fuseaux horaires, les révisions des résultats et la reprise après des messages manquants ou […]
L’intégration d’une API de tirages et de résultats de loterie doit conserver le lien entre le bon tirage, le billet accepté, le résultat autorisé et le règlement qui en découle. La difficulté consiste à définir les heures limites de vente, les fuseaux horaires, les révisions des résultats et la reprise après des messages manquants ou répétés, et non simplement à afficher les numéros gagnants.
Ce guide expose des exigences indépendantes du fournisseur. Il ne décrit pas les endpoints réels de WhiteLotto et ne promet pas que toutes les interfaces présentées sont incluses. Commencez par le guide d’architecture API de loterie et convenez du contrat réel avec l’équipe de livraison.
Utiliser des identifiants de tirage stables, pas uniquement des dates
Une date ne permet pas d’identifier un tirage de manière fiable si un produit propose plusieurs tirages quotidiens, des reports ou plusieurs fuseaux horaires. Faites correspondre l’identifiant du produit, celui du tirage chez le fournisseur et celui de la plateforme. Conservez ces références sur les billets et dans les rapports. Décidez si un tirage reporté garde son identité et quel est l’effet d’une annulation sur les billets acceptés.
| Enregistrement | À définir avant l’implémentation | Preuve d’acceptation |
|---|---|---|
| Calendrier des tirages | Identifiant stable, produit, heure prévue, limite de vente et fuseau horaire applicable. | Une trace unique entre catalogue, achat et reporting. |
| Acceptation du billet | Heure d’acceptation faisant autorité, règle de clôture et traitement des réponses incertaines. | Cas juste avant, à la limite et juste après. |
| Résultat | Source faisant autorité, statut, heure de publication, version et exhaustivité. | Scénarios non publiés, provisoires et définitifs. |
| Correction | Référence de révision, motif, approbation et traitement des billets concernés. | Piste d’audit reliant résultat précédent et corrigé. |
| Règlement | Déclencheur, responsabilité du calcul, références d’écriture et rapprochement. | Un seul effet financier par règlement prévu. |
Convenir de la sémantique temporelle et de la limite de vente
Enregistrez un instant sans ambiguïté ainsi que le fuseau horaire local nommé utilisé pour l’affichage client et les règles métier. Le format de date et d’heure RFC 3339 constitue une référence utile pour représenter un instant avec un décalage UTC. Ce décalage seul ne décrit pas les futures règles de changement d’heure d’une région.
Précisez si l’acceptation dépend de l’arrivée sur la plateforme, de l’acceptation par un fournisseur ou d’un autre événement contractuel. Le compte à rebours de l’interface est informatif : il ne doit pas décider de l’existence d’un billet. Testez la synchronisation, la dérive des horloges, les requêtes retardées et les changements d’heure. Affichez un résultat clair lorsque les ventes sont closes.
Un dépassement de délai près de la clôture nécessite une recherche du résultat ou un processus d’exception avec responsable. Une nouvelle tentative aveugle peut créer un doublon ou un billet pour un autre tirage. Conservez les références de l’opération initiale et du tirage demandé.
Traiter les corrections de résultat comme des changements contrôlés
Distinguez les résultats reçus, validés, définitifs et corrigés dans le modèle d’état convenu. Un champ manquant ne doit pas transformer un billet en billet perdant. Définissez qui peut autoriser le règlement et comment la source est authentifiée. En cas de correction, conservez la version précédente et reliez l’ajustement à son motif et à son approbateur.
Rejouer une notification ne doit pas régler deux fois le même billet. Un ancien résultat reçu tardivement ne doit pas remplacer une révision autorisée plus récente. Les corrections financières doivent rester traçables, et non réécrire silencieusement l’historique comptable initial. Le guide d’intégration des paiements présente la discipline correspondante pour les événements financiers asynchrones.
Rendre les événements manquants visibles
- Détecter les tirages dont les résultats attendus n’arrivent pas dans la fenêtre opérationnelle convenue.
- Comparer le catalogue source et l’inventaire local des tirages après une panne.
- Récupérer les événements manquants par un mécanisme pris en charge de rejeu ou de consultation.
- Distinguer les billets en attente de résultat de ceux en attente de règlement.
- Attribuer l’escalade et préparer les messages clients en cas de retard des tirages ou résultats.
Les recommandations HTTP sur l’idempotence aident à encadrer les nouvelles tentatives sûres, mais les garanties applicatives concernant billets et règlements doivent être spécifiées séparément. Utilisez le cadre d’indicateurs de l’opérateur pour mesurer l’exhaustivité des règlements et l’ancienneté des exceptions.
Liste d’acceptation d’un flux de résultats
Utilisez des tirages et billets fictifs dans un environnement de test autorisé. Couvrez les changements de calendrier, annulations, messages dupliqués et désordonnés, sources indisponibles, résultats incomplets et correction d’un résultat définitif. Vérifiez ensemble l’état des billets, les informations visibles par les joueurs, les écritures de règlement et les exports. Consignez la version d’interface et la configuration testée dans le dossier de réception UAT.
Séparez publication du résultat, approbation du règlement et autorisation du retrait
Un flux de résultats ne doit pas devenir une instruction sans restriction pour déplacer de l’argent. Définissez trois limites d’approbation : ce qui peut être affiché aux joueurs, la version du résultat pouvant servir au règlement des billets et ce qui permet d’autoriser un retrait associé. Ces décisions peuvent relever de systèmes et d’équipes différents. Demandez au fournisseur de démontrer ces limites dans la configuration réellement proposée, plutôt que de supposer qu’un champ « définitif » autorise toutes les actions suivantes.
Fournissez à l’opérateur un enregistrement vérifiable de chaque décision : preuves de la source, tirage concerné, version du résultat, périmètre d’autorisation et personne ou règle automatisée approuvée responsable. Une mise à jour de l’affichage ne doit pas modifier silencieusement une décision de retrait. Coordonnez ces limites avec le guide de gestion des comptes joueurs et le guide d’intégration des paiements ; un gain crédité et un paiement externe achevé correspondent à des enregistrements différents.
| Point de décision | Preuves à conserver | Question de responsabilité |
|---|---|---|
| Publication destinée au joueur | Référence de la source, formulation autorisée pour l’affichage et version du résultat présentée. | Qui approuve la publication ou la correction des informations destinées au client ? |
| Traitement du règlement | Résultat approuvé, périmètre des billets concernés et synthèse des calculs ou écritures. | Qui peut approuver le traitement et résoudre les exceptions ? |
| Crédit du portefeuille | Résultat du billet, référence du crédit et rapprochement avec le traitement du règlement. | Qui examine un écart entre le résultat du billet et le solde disponible ? |
| Autorisation du retrait | Référence de paiement, contrôles applicables et décision enregistrée pour ce retrait. | Qui autorise le versement, l’examen ou une suspension permise ? |
| Litige sur la clôture des ventes | Tirage demandé, preuves d’acceptation et règle contractuelle de l’heure limite. | Qui statue sur la participation et communique la résolution ? |
Prévoyez une correction après le mouvement des fonds
Étendez les tests de correction au-delà d’un billet encore en attente de règlement. Incluez un gain crédité restant sur le compte, un retrait en cours d’examen et un paiement déjà achevé hors de la plateforme. Consignez les billets concernés, les écritures d’origine, les références de retrait et la différence découlant de la révision approuvée. Convenez de la transmission de ces dossiers aux finances, aux opérations et au support avant toute application d’un ajustement.
La réponse doit suivre le contrat applicable, les conditions client et le processus de décision autorisé ; ce guide ne prescrit pas de règle universelle de récupération. Ne supposez pas que modifier le résultat affiché annule un paiement externe, ni qu’un solde négatif soit la bonne réponse automatique. Demandez comment l’équipe consigne une décision de ne pas ajuster, un ajustement permis ou un dossier non résolu. Distinguez les responsabilités de financement des gains examinées dans le guide du risque de jackpot et du financement des gains de la livraison du flux de résultats.
Exigez un scénario de correction détaillé dans le dossier de réception UAT. Utilisez uniquement des enregistrements de test et vérifiez les preuves de revue de l’opérateur ainsi que l’explication au client, pas seulement le montant gagnant recalculé.
Documentez la résolution d’une participation contestée
Pour un achat contesté près de la clôture des ventes, constituez un dossier réunissant le tirage initialement demandé, la trace d’acceptation, l’enregistrement du paiement et la règle applicable. Un débit seul ne doit pas être considéré comme une preuve de participation. Identifiez qui peut obtenir les preuves du fournisseur et qui approuve la résolution pour le client. Toute décision sur la participation, le traitement du paiement ou la communication client doit rester liée à ce dossier, plutôt que devenir une solution de support non documentée.
Définissez les preuves nécessaires à la clôture de chaque exception, y compris les écarts non résolus entre les enregistrements du fournisseur, des billets et des finances. Utilisez le cadre d’indicateurs de l’opérateur pour distinguer la clôture du dossier de la simple réception d’un message, et la bibliothèque de préparation de l’opérateur pour préparer les équipes concernées. Présentez à WhiteLotto vos limites d’approbation et exigences relatives aux dossiers contestés. CONTACT
Questions sur les API de tirages
Publier les numéros gagnants suffit-il ?
Non. L’opérateur a également besoin de l’identité du tirage, d’un statut de résultat faisant autorité, de la correspondance avec les billets acceptés et d’un règlement auditable.
Un résultat corrigé peut-il remplacer l’ancien enregistrement ?
L’affichage peut changer, mais l’exploitation doit conserver une piste d’audit et le lien entre le règlement initial et tout ajustement autorisé.
Présentez vos fournisseurs de tirages, produits, règles de clôture et besoins de reporting lors de la discussion du périmètre de plateforme. CONTACT.