Utiliser l’API web¶

La lecture get_match_snapshot, les lectures de journées/phases/groupes avec jeton et la snapshotUrl des notifications WebSocket sont disponibles depuis la V3.0.1.

L’API web fonctionne depuis un navigateur, AppSport ou un client HTTP externe, même lorsque vous n’avez aucun match ouvert sur votre PC. Chaque jeton appartient à une entreprise et donne accès uniquement à ses données, aux sports sélectionnés et aux opérations autorisées.

Créer un jeton d’entreprise¶

1. Connectez-vous à l’application avec un compte administrateur de l’entreprise.
2. Ouvrez le menu de votre compte, puis API et tokens et choisissez l’Entreprise active.
3. Donnez un nom au jeton, par exemple « tableau de bord résultats ».
4. Choisissez Lecture seule ou, si votre outil écrit des événements, Lecture et écriture d’événements.
5. Choisissez une durée : 7, 30, 90 ou 365 jours. L’API de gestion accepte une durée entière de 1 à 365 jours.
6. Cochez les sports utiles et cliquez sur Créer le jeton.
7. Cliquez sur Copier et enregistrez ce secret dans la configuration privée de votre outil. Le jeton complet n’est affiché qu’à la création. La liste conserve uniquement son préfixe, ses droits, son expiration et sa dernière utilisation.

Tous les administrateurs de la même entreprise peuvent consulter ses jetons, les créer, les modifier et les révoquer. Les autres utilisateurs n’ont accès ni à cette rubrique, ni au Swagger intégré, ni aux endpoints de gestion, même en saisissant leur adresse directement.

Cliquez sur Modifier pour changer le nom, les sports, la permission ou l’expiration. Conserver l’expiration maintient la date actuelle ; choisir une durée renouvelle l’accès à partir d’aujourd’hui. Le secret reste identique et n’est pas affiché de nouveau. Pour remplacer un secret perdu ou compromis, créez un nouveau jeton, mettez à jour votre outil puis révoquez l’ancien.

Pour désactiver un outil, cliquez sur Révoquer dans la liste. Toute nouvelle requête avec ce jeton sera refusée. Une opération déjà en cours peut se terminer. Un jeton révoqué ne peut pas être réactivé.

Le statut actif du créateur, son rôle administrateur et la licence de l’entreprise sont relus à chaque requête. Un jeton est refusé si son créateur est désactivé, supprimé ou n’administre plus l’entreprise ; un autre administrateur peut alors le révoquer et créer un remplacement. Les droits d’un administrateur sur d’autres entreprises ne sont jamais transmis au jeton. La gestion exige une session administrateur connectée ; un jeton d’intégration ne peut pas créer d’autres jetons ni accéder à la gestion du compte.

Envoyer une requête¶

Adresse publique : https://app.mylivesport.fr. Chaque requête utilise :

Authorization: Bearer mls_api_VOTRE_JETON

N’envoyez pas le jeton dans l’URL. Aucun cookie de session n’est nécessaire à votre outil. Les jetons web n’imposent pas l’IP ni le User-Agent du navigateur qui les a créés.

Exemple PowerShell, avec des identifiants de démonstration à remplacer :

$env:MLS_API_TOKEN = 'copier_ici_le_jeton_cree'
$headers = @{ Authorization = "Bearer $env:MLS_API_TOKEN" }
Invoke-RestMethod -Uri 'https://app.mylivesport.fr/api/futsal/get_match?championship_id=1&match_id=2' -Headers $headers

Exemple curl :

curl --header "Authorization: Bearer $MLS_API_TOKEN" \
  'https://app.mylivesport.fr/api/futsal/get_match?championship_id=1&match_id=2'

Les données sont généralement enveloppées dans { "success": true, "data": ... }. Une réponse 204 a un corps vide : ne tentez pas de la décoder en JSON. Les champs disponibles dépendent du sport ; consultez le Swagger web.

Opérations disponibles¶

Remplacez {sport} par football, futsal, hockey, basketball, handball ou tennis. Le sport doit être autorisé dans le jeton.

Les championnats, matchs, compositions et classements d’une autre entreprise sont refusés, même si le créateur du jeton administre également cette entreprise. Les écritures conservent les validations métier du sport.

Lire le contexte sportif complet¶

GET /api/{sport}/get_match_snapshot?championship_id=1&match_id=2 renvoie { "success": true, "data": { "contextKey": "futsal:1:2", "context": { ... }, "match": { ... }, "matchDays": [], "scorers": [], "standings": [] } }.

Ces quatre rubriques suivent le contrat de l’API locale : noms complets, compétition et saison, journée réelle, date/heure, scores, lieu, officiels, commentateurs, météo, autres rencontres des journées voisines, buteurs ou paniers et classement. Le snapshot web lit les données enregistrées en base et le classement courant ; l’état local lit celles chargées dans la page. Il ne déclenche aucune mise à jour des scores, aucun scraping ni aucun recalcul du classement.

Le match doit appartenir au championnat demandé et être visible. Les autres rencontres sont filtrées avec les restrictions d’équipes de la session. Les jetons conservent leurs limites d’entreprise, de sport, d’expiration et de permission. Les champs internes de configuration ne sont pas inclus dans ce nouveau contrat. Un score inconnu vaut null, un texte inconnu "" ; aucun numéro de journée n’est déduit de son ID.

scorers contient uniquement les événements de score sauvegardés, hors tirs au but. points vaut 1 pour un but, ou 1/2/3 au basketball ; ownGoal distingue les CSC et side désigne l’équipe bénéficiaire. Le nom est récupéré dans les deux clubs du match et reste vide si aucun joueur correspondant n’est disponible. Au tennis, scorers est vide ; les scores du snapshot représentent les sets gagnés. Utilisez get_match_sets pour les jeux et sets détaillés.

Les notifications du WebSocket web existant, lorsqu’elles ciblent un match (match_data, match_event, match_player, match_set), fournissent aussi snapshotUrl. Relisez cette URL relative sur l’origine de l’application avec votre authentification habituelle pour obtenir le contexte enrichi. Cette relecture applique les droits de chaque destinataire aux autres matchs. Le WebSocket conserve son authentification de session actuelle ; un jeton HTTP d’entreprise ne devient pas un jeton WebSocket. Le flux local /api/v1/ws, lui, transmet directement les quatre rubriques dans state.

Écrire un événement¶

Utilisez Content-Type: application/json et un jeton autorisé en écriture. id: "new" crée un événement ; un ID existant modifie un événement de ce même match. Au tennis, les champs incluent set_number et note. Pour les sports collectifs, ils incluent club_id, timer, additional_timer, player_id_in et value. Les schémas et exemples sont dans le Swagger.

Les types sont propres à chaque sport : le type 1 ne désigne pas le même événement au football, au basket et au tennis. Reprenez les types utilisés dans votre match.

La sauvegarde peut recalculer le score et changer les statuts terrain / banc pour un remplacement. Elle informe les interfaces connectées via le mécanisme existant. Elle ne diffuse pas automatiquement un graphique du poste AppSport.

Ces écritures web ne disposent pas d’une clé d’idempotence. Après une coupure sans réponse, relisez les événements pour vérifier si la sauvegarde a eu lieu avant de réessayer.

Tester avec Swagger¶

Avec un compte administrateur d’entreprise, ouvrez API et tokens → Ouvrir Swagger, ou le Swagger intégré. Cliquez sur Authorize, saisissez uniquement le jeton, puis choisissez une opération et utilisez Try it out. Remplacez les identifiants d’exemple par ceux de l’entreprise du jeton. Les essais exigent un jeton, même si une session navigateur est ouverte.

Le Swagger public permet de consulter le contrat sans compte et sans saisir de secret. Les essais sont réservés à l’application pour rester sur la même origine.

Diagnostic¶

La date de dernière utilisation est actualisée au plus une fois toutes les cinq minutes. Elle indique une authentification autorisée ; elle ne garantit pas le succès métier de l’opération.