SportApi
Documentation API

Intégration du système pour le calcul des paris et des coupons

Ce système est conçu pour les opérateurs de paris sportifs, les bookmakers et les développeurs de plateformes qui souhaitent automatiser le processus de calcul des paris et de gestion des coupons. Il permet une intégration rapide du calcul des résultats, fournissant des données précises sur le statut des coupons (gain, perte ou remboursement), et simplifie l'interaction entre le serveur de l'opérateur et le système de calcul.

POST /v1/coupon json
{
  "coupon_id": "A7F3K9",
  "type": "express",
  "events": [
    { "id": 88213, "pick": "1", "odds": 2.10, "result": "win" },
    { "id": 88150, "pick": "over_2_5", "odds": 1.80, "result": "win" }
  ],
  "total_odds": 3.78, "status": "won"
}

Comment fonctionne le système ?

Comment fonctionne le système de calcul des cotes et des résultats ?

L'intégration avec notre système de calcul des paris et des coupons comprend trois étapes clés :

Étape 1 : Autorisation

Dans un premier temps, vous devez vous autoriser dans le système. Cela se fait en effectuant une requête POST avec les identifiants de l'utilisateur (identifiant et mot de passe). Une autorisation réussie renvoie une session sous forme de cookie, qui doit être enregistré. Ces cookies sont requis pour toutes les requêtes suivantes car ils permettent d'identifier la session de l'utilisateur dans le système.

Étape 2 : Envoi d'un pari

À cette étape, un code de pari est envoyé à notre système contenant :

  • L'ID du match, correspondant à l'événement.
  • Le code de pari, décrivant le résultat sélectionné (par exemple, victoire de l'équipe, handicap ou total).
  • Les cotes du pari, valables au moment de l'envoi.

Lors de l'envoi des données, les cookies obtenus lors de l'autorisation doivent être inclus. Cela garantit une identification correcte de l'utilisateur et le traitement du pari.

Étape 3 : Réception des résultats

Une fois les résultats ou les coupons calculés, notre système envoie des requêtes POST au remote_host spécifié. Cette requête contient :

  • Le statut du coupon (gain, perte ou remboursement).
  • Les statuts de tous les résultats inclus dans le coupon.

Les résultats sont envoyés dès que le dénouement est déterminé. Par exemple :

  • Si le pari a été placé sur un résultat intermédiaire (par exemple, handicap de 2,5 et le troisième but est marqué), le calcul peut être effectué pendant le match.
  • Si le pari porte sur le résultat final (par exemple, victoire de l'équipe), les informations sur le statut seront envoyées immédiatement après la fin du match.

Consultez maintenant chaque étape en détail. Nous avons décrit les requêtes, les paramètres et les réponses API de manière détaillée.

Autorisation de l'utilisateur

L'identifiant, le mot de passe et l'hôte pour l'envoi des requêtes peuvent être obtenus auprès du gestionnaire.

URL de la requête :

{APIHOST}/WebServices/BCService.asmx/LogIn/

Type d'envoi des données : POST

Données envoyées :

ParamètreDescription
loginIdentifiant de l'utilisateur
passwordMot de passe de l'utilisateur

Important !

  • Lors de l'autorisation, la réponse contient des cookies. Ces cookies doivent être enregistrés et envoyés avec les requêtes suivantes.

Recommandations pour une intégration simplifiée :

  • Assurez-vous que le champ login est transmis sous forme de chaîne de caractères.
  • Vérifiez l'enregistrement et l'envoi corrects des cookies, car cela affecte l'exécution des requêtes suivantes.
  • En cas d'erreur, la requête renverra un objet vide. Veillez à gérer ce scénario de manière appropriée.

Les cookies sont valables 3 mois. Cependant, ils peuvent être réinitialisés en cas de redémarrage du serveur. Par conséquent, vous devez vous réautoriser si vous rencontrez une erreur lors de l'enregistrement d'un coupon.

Réponse d'erreur json
"errorCode":1,
"fullErrorCode":99,
"errorMessage":"Invalid access level"

Exemple d'envoi de requête (utilisez les données fournies par le gestionnaire) :

Exemple de réponse :

Réussie :

{"d":{"UserId":"36557"}}

Échouée :

{"d":{}}

Description des champs de la réponse :

ChampDescription
UserIdIdentifiant unique de l'utilisateur
dObjet racine de la réponse

Recommandations générales :

  • Avant la première requête, assurez-vous que l'utilisateur a saisi les identifiants corrects.
  • Configurez la gestion des erreurs pour afficher à l'utilisateur les raisons de l'échec de l'autorisation (par exemple, identifiant ou mot de passe incorrect).
  • Enregistrez les tentatives réussies et échouées pour analyse et surveillance.

Les cookies doivent être enregistrés et envoyés avec les requêtes suivantes.

POST {APIHOST}/WebServices/BCService.asmx/LogIn/ python
import requests
import json

url = "https://example-domain-calc.com/WebServices/BCService.asmx/LogIn/"

payload = json.dumps({
  "login": "[email protected]",
  "password": "demo-password"
})
headers = {
  'Content-Type': 'application/json'
}

print(response.text)

Méthode d'envoi de pari ou de coupon

Pour envoyer un pari, vous devez utiliser les cookies obtenus lors de l'étape d'autorisation. Ces données sont requises pour identifier votre session et traiter les requêtes.

URL de la requête :

{HOST_API}/bet/place/
Exemple de corps de payload json
{
    "data":{
        "list_bets":[
            "line#586464528|17|954|2.5#4.27",  "live#586464528|87|4|0#1.12"
        ],
        "realAmount":"2",
        "currency":"USD",
        "lang":"en",
        "remote_host":"https://mysites.com",
        "rate_mode":"reject"
    }
}

Paramètres remote_host & rate_mode

Description des champs

ParamètreDescription
list_betsCode du pari et cotes. Format : "event_type#match_ID|bet_code#odds". Exemple : "live#579216393|1|1|0#2.1"
realAmountMontant du pari. Doit être transmis sous forme de chaîne de caractères, par exemple, "150".
currencyDevise du coupon.
langLa langue dans laquelle le pari et le coupon sont enregistrés. Par exemple : "en", "ru" ou "tr".
remote_hostL'URL à laquelle envoyer les résultats du calcul du coupon. Ne pas inclure de barre oblique finale.
rate_modeOption pour gérer l'acceptation du coupon en cas de modification des cotes : "reject" (rejeter en cas de modification) ou "accept" (accepter malgré les modifications). Par défaut : "accept".

Remarque : Assurez-vous que les paramètres sont transmis dans le bon format. Par exemple, list_bets doit être un tableau, même s'il n'y a qu'un seul pari.

We do not validate the bet amount. You can submit either the actual bet amount or any arbitrary value. This is to ensure the confidentiality of your financial data. Our task is to provide calculation results. You are responsible for crediting winnings to your players.

Paramètres requis pour envoyer un pari :

  • list_bets — contient les informations sur le pari et le match correspondant.
  • remote_host — l'URL à laquelle nous enverrons les résultats du calcul pour le coupon ou le résultat.
  • rate_mode — détermine comment le système gère les changements de cotes.

Les autres paramètres doivent également être envoyés, mais ils sont facultatifs et peuvent être utilisés pour votre commodité.

Description du paramètre remote_host

remote_host est l'adresse de votre serveur vers laquelle nous envoyons les requêtes contenant les résultats des calculs de paris. Cet hôte doit être configuré pour accepter les requêtes de notre serveur. Vous trouverez ci-dessous des exemples de valeurs possibles et des détails spécifiques sur l'utilisation de ce paramètre.

Vous pouvez spécifier diverses options pour remote_host :

  • Hôte simple : https://mysites.com
  • Hôte avec port : https://mysites.com:78665
  • Hôte avec chemins supplémentaires : https://mysites.com/request/sportapi/sender
  • Hôte avec paramètres : https://mysites.com/request.php?action=webhook

Important : Lors de l'envoi d'une requête, notre système ajoute automatiquement la chaîne /api/bet/result au remote_host spécifié. Ainsi, l'adresse finale pour recevoir les requêtes est formée sous la forme remote_host + "/api/bet/result". Assurez-vous que votre serveur est configuré pour recevoir des données à cet emplacement.

Exemples :
  • Vous spécifiez remote_host = https://mysites.com. Nous envoyons les requêtes à : https://mysites.com/api/bet/result.
  • Vous spécifiez remote_host = https://mysites.com/request.php?action=webhook. Nous envoyons les requêtes à : https://mysites.com/request.php?action=webhook/api/bet/result.

Détails techniques :

  • Les requêtes sont envoyées à l'aide de la méthode POST.
  • Votre serveur doit être prêt à accepter les données JSON que nous envoyons.
  • Votre serveur doit renvoyer un code de statut 200 lors de la réception réussie des données.

Assurez-vous que votre serveur traite correctement le chemin et les requêtes spécifiés. La section suivante fournit un exemple de la structure des données envoyées par notre serveur.

Description du paramètre rate_mode

Le paramètre rate_mode définit le comportement du système en cas de modification des cotes. Il peut prendre deux valeurs :

  • accept : Dans ce mode, le coupon sera accepté avec les cotes actuelles, même si elles ont changé. Par exemple, un joueur ajoute un pari "Manchester Gagne" avec une cote de 2,02. Pendant qu'il appuie sur le bouton "Placer le pari", la cote passe à 1,37 ou 2,78. En mode accept, le système enregistre le coupon avec les nouvelles cotes sans en informer votre système.
  • reject : Dans ce mode, le système rejette le coupon si les cotes ont changé. La réponse contiendra une erreur signalant que les cotes ont été modifiées.

Choisissez le mode qui convient le mieux à vos processus commerciaux et qui offre le plus de commodité à vos utilisateurs.

Recommandations importantes

  1. Formatage JSON : Assurez-vous que les données sont correctement sérialisées au format JSON avant de les envoyer.
  2. Cookies : Incluez les cookies obtenus lors de l'autorisation pour identifier avec succès la session de l'utilisateur.
  3. Gestion des erreurs : Gérez les réponses du serveur, en particulier les cas où errorCode = 1 est renvoyé.
  4. Tests : Effectuez des tests à toutes les étapes de l'intégration, y compris l'envoi de paris simples et multiples.

Champs de réponse & description des erreurs

Champs de la réponse

ParamètreDescription
betCodeNuméro de pari unique dans notre système
errorCodeStatut principal du résultat de la requête
fullErrorCodeDétails de l'erreur
errorMessageMessages d'erreur système textuels
AmountOutMontant du gain potentiel
CountEventsNombre de paris dans le coupon
CoefCoefficients des résultats
IsLiveType de pari : en direct ou d'avant-match (true/false)
LinesIdID du match
EventDateDate du match

Description de l'erreur pour l'envoi du pari

Diverses erreurs peuvent survenir lors de l'envoi d'un pari. La réponse du serveur contient trois champs clés :

  • errorCode : Statut principal de la requête.
  • fullErrorCode : Détails de l'erreur.
  • errorMessage : Description textuelle de l'erreur.

Opération réussie

Opération réussie json
{
  "errorCode": 0,
  "fullErrorCode": 0,
  "errorMessage": ""
}

Codes d'erreur

Si le pari est accepté avec succès, le serveur renvoie une réponse de succès (voir ci-dessus). Le coupon a été accepté et il n'y a pas d'erreur.

Si une erreur survient, le serveur renvoie une réponse d'erreur générale (voir ci-dessus). L'une des erreurs possibles s'est produite. Vous trouverez ci-dessous les codes d'erreur et les messages correspondants.

Codes d'erreur possibles et descriptions

Code d'erreur (fullErrorCode)Message d'erreur (errorMessage)Description
1error_wrong_bet_dataDonnées de pari incorrectes. Vérifiez le paramètre list_bets et les autres champs requis.
1error_block_bet_dataLe pari est temporairement bloqué et ne peut être accepté.
1error_repeat_bet_dataLes paris répétés sur le même résultat pour un même match ne sont pas autorisés.
2label_change_rateLes cotes ont changé. Le coupon a été rejeté en raison d'une différence entre les cotes spécifiées et actuelles.
3error_exist_betLe résultat du pari spécifié n'existe plus. Vérifiez l'exactitude des données.
99Niveau d'accès invalideL'utilisateur n'a pas les droits pour effectuer cette opération. Il est probable qu'une réautorisation soit nécessaire, que les cookies soient manquants ou que le compte soit bloqué.
99Erreur d'hôte distant existant !Le paramètre remote_host est incorrect ou manquant. Vérifiez les paramètres de votre serveur.

Recommandations pour la gestion des erreurs

  • Validation des données d'entrée : Assurez-vous que tous les paramètres requis sont fournis correctement. Vérifiez le format de list_bets et la présence de tous les champs obligatoires.
  • Gestion des cotes : Si rate_mode = reject est utilisé, gérez les erreurs liées aux changements de cotes (label_change_rate).
  • Configuration du serveur : Assurez-vous que votre serveur est correctement spécifié dans le paramètre remote_host.
  • Journalisation des erreurs : Enregistrez toutes les erreurs (errorCode, fullErrorCode, errorMessage) pour simplifier le débogage et l'interaction avec le support.
  • Actions en cas d'erreurs critiques : En cas d'erreurs de niveau 99, vérifiez les droits d'accès et les configurations de l'API de votre côté.
Erreur générale json
{
  "errorCode": 1,
  "fullErrorCode": [ERROR_CODE],
  "errorMessage": "[ERROR_DESCRIPTION]"
}

Recommandations pour la gestion des erreurs en cas de modification des cotes

Recommandations pour la gestion des erreurs en cas de modification des cotes json
{
    "errorCode":1,
    "fullErrorCode":2,
    "errorMessage":"Odds have changed",
    "rate_mode":"reject",
    "changed":[
        {
            "gid":"586464528", // match ID
            "rb":2.15, // odds in your coupon
            "rg":"2.27", // current real odds
            "rt":0 // status of change. 0 - decreased, 1 - increased
        }
    ]
}

Envoi des résultats de calcul

Lorsqu'un pari est ajouté à notre système et calculé, nous envoyons les résultats du coupon à votre serveur. Ceux-ci peuvent inclure :

  • Les résultats du coupon (calcul complet).
  • Les statuts du coupon (gain, perte, remboursement).

Les requêtes sont envoyées à l'adresse que vous avez spécifiée dans le paramètre remote_host. La chaîne /api/bet/result y est automatiquement ajoutée. Assurez-vous que votre serveur est configuré pour recevoir des données à cet emplacement.

Exemple de l'adresse finale :

Si vous avez spécifié : remote_host = https://mon-site.com, nous enverrons les données à : https://mon-site.com/api/bet/result.

Exemple de données pour un seul coupon json
{
    "remote_host": "https://mysite.com",
    "Heads": [{
        "KeyHead": {
            "Id": "344143",
            "BarCode": "x9c52i8411"
        },
        "Status": 2,
        "ExtStatus": 0,
        "AmountOut": 11130,
        "DateReceive": "1597075782"
    }]
}

Exemple de données pour plusieurs coupons

Description des champs

ChampDescription
remote_hostL'adresse de votre serveur vers laquelle les données sont envoyées.
IdIdentifiant unique du pari dans notre système. Ignoré dans la plupart des cas.
BarCodeNuméro de coupon unique.
StatusStatut actuel du coupon. Valeurs possibles : 2 — gain, 4 — perte.
ExtStatusStatut supplémentaire en cas de remboursement : 0 — pas de modifications, 1 — un ou plusieurs résultats ont été calculés avec un coefficient modifié.
AmountOutMontant du gain (si le coupon a gagné).
DateReceiveL'heure et la date auxquelles le coupon a été calculé.

Comment interpréter Status et ExtStatus

  • Status = 2 et ExtStatus = 0 : Le coupon a gagné.
  • Status = 4 et ExtStatus = 0 : Le coupon a perdu.
  • Status = 2 et ExtStatus = 1 : Remboursement. Le coupon a été calculé avec un coefficient de 1.

Points importants pour l'intégration

  • Gestion de ExtStatus = 1 : Cela peut se produire si un match a été annulé ou s'est terminé prématurément. Dans de tels cas, tous les paris sont calculés avec un coefficient de 1.
  • Spécifications techniques : Les requêtes sont envoyées à l'aide de la méthode POST. Votre serveur doit être prêt à accepter les données JSON à l'adresse remote_host + /api/bet/result.
Exemple de données pour plusieurs coupons json
{
    "remote_host": "https://mysite.com",
    "Heads": [{
        "KeyHead": {
            "Id": "313",
            "BarCode": "75vz48t935"
        },
        "Status": 2,
        "ExtStatus": 0,
        "AmountOut": 19.85,
        "DateReceive": "1592937968"
    }, {
        "KeyHead": {
            "Id": "312",
            "BarCode": "77i0r6e15t"
        },
        "Status": 2,
        "ExtStatus": 0,
        "AmountOut": 12.51,
        "DateReceive": "1592937280"
    }]
}