Authentification
Toutes les requêtes doivent inclure la clé API dans le header x-api-key. La clé est fournie par PTM lors de l'onboarding partenaire.
Ne jamais exposer la clé API côté client. Tous les appels doivent transiter par votre backend.
Codes d'erreur
| Code | Signification | Description |
|---|---|---|
| 200 | OK | Succès, y compris les cas métier (not_found, multiple…) |
| 201 | Created | Inscription créée (statut confirmed, pending ou waitlist) |
| 400 | Bad Request | Paramètre requis manquant ou mal formé (email, téléphone) |
| 401 | Unauthorized | Clé API absente, invalide ou désactivée |
| 404 | Not Found | Ressource inexistante ou non publiée sur Pista |
| 409 | Conflict | Doublon d'inscription (paire déjà inscrite) |
| 500 | Server Error | Erreur interne PTM |
Les cas métier de /partner-players-verify (joueur introuvable, homonymie…) retournent toujours HTTP 200 avec un champ status dans le body. Seules les erreurs d'infrastructure utilisent les codes 4xx/5xx.
Liste des tournois
Retourne la liste des tournois publiés sur Pista avec les inscriptions ouvertes (registration_open = true). Tous les filtres sont optionnels et cumulables.
| Paramètre | Type | Description |
|---|---|---|
| date_from | date (YYYY-MM-DD) | Tournois à partir de cette date |
| date_to | date (YYYY-MM-DD) | Tournois jusqu'à cette date |
| gender | string | Filtrer par genre : Masculin, Féminin, Mixte |
| level | string | Filtrer par niveau : P25, P100, P250… |
| club_id | uuid | Restreindre aux tournois d'un club spécifique |
| lat | number | Latitude du point de référence (requis avec lng et radius_km) |
| lng | number | Longitude du point de référence |
| radius_km | number | Rayon de recherche en km autour du point lat/lng |
available_spots peut être null si le tournoi n'a pas de limite de paires définie. La réponse est limitée à 100 résultats. Une pagination cursor-based (?cursor=) sera disponible prochainement.
Détail d'un tournoi
| Paramètre | Type | Requis | Description |
|---|---|---|---|
| id | uuid | requis | Identifiant du tournoi |
Vérification de licence
Cet endpoint est déprécié et sera retiré dans une prochaine version. La vérification FFT est désormais réalisée côté PTM, automatiquement, au moment de l'inscription (partner-register) — aucun pré-appel n'est nécessaire.
À ne pas intégrer pour de nouveaux développements. Documenté ici uniquement pour référence.
| Paramètre | Type | Requis | Description |
|---|---|---|---|
| first_name | string | requis | Prénom du joueur |
| last_name | string | requis | Nom du joueur |
| licence | string | optionnel | Numéro de licence FFT. Si fourni, affine la recherche et détecte les incohérences. |
Inscription d'une paire
À l'inscription, PTM vérifie chaque joueur auprès de la FFT. Trois issues possibles :
status: confirmed— joueurs vérifiés et places disponibles : la paire est ajoutée au tableau.status: waitlist— tournoi complet : la paire est placée en liste d'attente (avec sa position).status: pending— un joueur n'a pas pu être vérifié (introuvable FFT, licence incorrecte, homonymie, ou service FFT temporairement indisponible) : la place est réservée mais l'inscription attend une validation manuelle du juge-arbitre.
Les champs requis manquants ou mal formés (email, téléphone) sont rejetés en 400 avant toute création.
| Champ | Type | Description |
|---|---|---|
| tournament_id | uuid | ID du tournoi cible |
| player1.licence_number | string | Licence FFT joueur 1 |
| player1.first_name | string | Prénom joueur 1 |
| player1.last_name | string | Nom joueur 1 |
| player1.phone | string | Téléphone joueur 1 (≥ 6 chiffres) |
| player1.email | string | Email joueur 1 (format validé) |
| player2.licence_number | string | Licence FFT joueur 2 |
| player2.first_name | string | Prénom joueur 2 |
| player2.last_name | string | Nom joueur 2 |
| player2.phone | string | Téléphone joueur 2 (≥ 6 chiffres) |
| player2.email | string | Email joueur 2 (format validé) |
L'email (format) et le téléphone (au moins 6 chiffres) sont validés ; une valeur mal formée renvoie un 400. La licence est requise (présence) ; son exactitude est vérifiée auprès de la FFT après l'inscription (peut produire status: pending).
field identifie le problème : nom du champ manquant (ex. player2.last_name) ou suffixe _invalid pour un format incorrect (player1.email_invalid, player1.phone_invalid).
Désinscription d'une paire
La désinscription n'est possible que pour les inscriptions créées via Pista (source: pista). Elle est bloquée si le tournoi est en cours ou terminé. La promotion automatique de la liste d'attente n'est pas gérée, le JA continue à promouvoir manuellement.
| Champ | Type | Description |
|---|---|---|
| registration_id | uuid | ID de l'inscription à annuler |
Webhooks · disponible (staging)
PTM notifie des changements sur le cycle de vie des inscriptions et des tournois (et non sur les attributs des joueurs : classement/contact ne sont pas synchronisés — servis par GET tournaments/:id). L'émission est active sur staging ; il reste à échanger l'URL d'abonnement et le secret de signature, et à confirmer le mapping de l'annulation (voir plus bas).
Chaque événement est envoyé en POST vers l'URL d'abonnement, signé en HMAC-SHA256 du corps brut (header X-PTM-Signature, hex). Un header X-PTM-Event-Id (UUID) permet la déduplication idempotente. En cas d'échec, réessais en backoff exponentiel (jusqu'à 8 tentatives, puis abandon). Seuls les changements visibles côté partenaire sont émis (pas de notification si le statut projeté ne change pas) ; un changement initié par le partenaire n'est pas réémis vers lui.
Émis sur les transitions de statut projeté confirmed / pending / waitlist / rejected : ex. le juge-arbitre valide une inscription en anomalie (pending → confirmed), promeut une liste d'attente (waitlist → confirmed ou → pending), ou rejette une inscription (→ rejected). roster reflète la paire courante (peut être null en liste d'attente). N'est émis que pour les inscriptions d'origine partenaire (porteuses d'un partner_booking_id).
Émis sur changement de status du tournoi (notamment → CANCELLED : toutes les inscriptions du tournoi sont à retirer côté partenaire). N'est émis que pour les tournois ayant au moins une inscription d'origine partenaire.
Mapping exact de l'annulation (un cancelled PTM est projeté provisoirement en rejected — à confirmer : rejected vs événement de désinscription dédié) ; identifiant joueur opaque pour la réconciliation par slot lors d'un remplacement ; URL d'abonnement + secret de signature à échanger.