API pour logiciels de gestion externes

1. Ce que permettent les API

Avec une clé API, tu peux, depuis ton logiciel, lire et écrire sur le calendrier de tes infrastructures :

• lire les infrastructures et les terrains avec leurs identifiants, nécessaires pour tous les autres appels ;
• lire les réservations d'une période, d'une infrastructure ou d'un seul terrain, pour les aligner avec tes archives ;
• créer des réservations depuis l'extérieur (par exemple lorsqu'un client réserve depuis ton site), avec les mêmes contrôles de chevauchement et de fermeture du panneau ;
• modifier ou annuler une réservation existante (changement d'horaire ou de terrain, encaissement, notes, annulation) ;
• lire la disponibilité d'un terrain pour un jour donné : créneaux déjà occupés, horaires d'ouverture et fermetures exceptionnelles, afin de proposer les créneaux libres sans avoir à répliquer les règles ;
• lire la grille tarifaire d'un terrain pour afficher les prix au client final.

Ne font pas partie de ces API les demandes des organisateurs pour l'utilisation des terrains lors des tournois (elles sont approuvées depuis l'application), la création de structures et de terrains, l'enregistrement des horaires, des fermetures et de la grille tarifaire : ce sont des opérations du panneau de gestion.

2. Prérequis et activation

1. Un compte gestionnaire de terrains VolleyFriends avec au moins une structure et un terrain.
2. Un abonnement en cours avec une offre incluant la fonctionnalité « API pour logiciels de gestion externes ». L'intégralité de la v1 — même les simples lectures — est réservée à ceux qui disposent de cette fonctionnalité : il s'agit d'une option payante, pas d'un accessoire du panneau.
3. Une clé API générée depuis le panneau de gestion : admin.volleyfriends.com → Paramètres → Clés API → Nouvelle clé.

La clé a la forme vfk_ suivie de 40 caractères hexadécimaux (44 caractères en tout) et n'est affichée qu'une seule fois, immédiatement après sa création : seule son empreinte sha256 reste dans la base de données, elle n'est donc récupérable d'aucune façon. Si tu la perds, révoque-la et génères-en une nouvelle. Dans la liste du panneau, tu ne vois que le préfixe (ex. vfk_9f2c), la date de création et celle de la dernière utilisation.

3. Authentification

Chaque requête doit être authentifiée avec l'en-tête X-Api-Key. Pas besoin de jeton, de connexion, d'expiration ou de renouvellement : la clé reste valide tant que tu ne la révoques pas.

# Les clés de cette page sont des exemples : remplace-les par la tienne.
curl -s https://www.volleyfriends.com/api/manager-api/v1/venues   -H "X-Api-Key: vfk_9f2c41a7b83d05e6c19af4728b60d35e1c9a7f42"

Dans les exemples qui suivent, la clé est lue à partir de la variable d'environnement VF_API_KEY, comme il convient de le faire également en production.

En-tête absent, plus court que 12 caractères, inconnu ou appartenant à une clé révoquée : la réponse est 401 avec ce corps.

{
  "error": "invalid_key",
  "message": "Chiave API mancante o non valida (header X-Api-Key)."
}

4. URL de base

https://www.volleyfriends.com/api

Les chemins documentés ci-dessous doivent être ajoutés à la base. Le préfixe /api appartient au proxy inverse, l'adresse complète d'un point de terminaison est donc par exemple :

GET https://www.volleyfriends.com/api/manager-api/v1/availability

Toutes les réponses sont au format application/json avec un encodage UTF-8. Les requêtes avec corps (POST, PATCH) doivent avoir Content-Type: application/json.

5. Limitation de débit

La limite est de 120 requêtes par minute par clé API (fenêtre glissante de 1 minute). Le décompte se fait par clé, non par adresse IP : les logiciels de gestion sont souvent derrière la même adresse de fournisseur et une limite par IP pénaliserait différents gestionnaires hébergés sur la même infrastructure. Si l'en-tête X-Api-Key est totalement absent, le décompte se base sur l'adresse IP.

Chaque réponse indique l'état du compteur dans les en-têtes x-ratelimit-limit, x-ratelimit-remaining et x-ratelimit-reset (secondes avant réinitialisation). En cas de dépassement, retry-after est également ajouté.

Réponse en cas de dépassement — 429

{
  "error": "rate_limited",
  "message": "Limite di 120 richieste al minuto superato per questa chiave API."
}

6. Endpoints

Six endpoints, tous sous /manager-api/v1. Chaque appel passe par la même chaîne de contrôles, dans l'ordre : clé API valide → fonctionnalité « API pour logiciels de gestion externes » incluse dans le forfait → rate limit → validation des paramètres → vérification que la ressource t'appartient.

6.1 Structures et terrains

Liste tes structures, chacune avec ses propres terrains imbriqués. C'est l'appel de départ : les id des terrains (courtId) sont nécessaires pour tous les autres endpoints. Les structures sont triées par nom, les terrains par nom.

Paramètres

Aucun.

Exemple de requête

curl -s https://www.volleyfriends.com/api/manager-api/v1/venues   -H "X-Api-Key: $VF_API_KEY"

Exemple de réponse — 200

{
  "venues": [
    {
      "id": "b3f8e5c1-2d47-4a90-8f31-6c0d9a7e4512",
      "name": "Centro Sportivo Aurora",
      "city": "Verona",
      "address": "Via delle Palestre 12",
      "verified": true,
      "courts": [
        {
          "id": "7c94a0d2-58b1-4e6f-9a3c-1d20f8b47e05",
          "venueId": "b3f8e5c1-2d47-4a90-8f31-6c0d9a7e4512",
          "name": "Campo 1",
          "surface": "parquet",
          "indoor": true,
          "lighting": true
        },
        {
          "id": "e2a71f64-9c03-4bd8-b512-38f6cd90a7e1",
          "venueId": "b3f8e5c1-2d47-4a90-8f31-6c0d9a7e4512",
          "name": "Campo 2 beach",
          "surface": "sabbia",
          "indoor": false,
          "lighting": true
        }
      ]
    }
  ]
}

Champs de la réponse

Si le compte n'a pas encore de structures, la réponse est {"venues": []}.

Erreurs spécifiques

Aucune autre que les générales.

6.2 Liste des réservations

Retourne les réservations de tes structures, triées par heure de début croissante. La liste est paginée : au maximum limit lignes par appel (par défaut 500, plafond 1000) — si tu reçois exactement limit lignes, effectue un nouvel appel avec un offset augmenté pour la page suivante. En production, filtre toujours au moins par plage de dates.

Paramètres (query string)

Exemple de requête

curl -s -G https://www.volleyfriends.com/api/manager-api/v1/bookings   -H "X-Api-Key: $VF_API_KEY"   --data-urlencode "courtId=7c94a0d2-58b1-4e6f-9a3c-1d20f8b47e05"   --data-urlencode "from=2026-08-01"   --data-urlencode "to=2026-08-31"

Exemple de réponse — 200

{
  "bookings": [
    {
      "id": "9d51c7b4-0e28-4f3a-a6d9-72b48e105c3f",
      "venueId": "b3f8e5c1-2d47-4a90-8f31-6c0d9a7e4512",
      "courtId": "7c94a0d2-58b1-4e6f-9a3c-1d20f8b47e05",
      "courtName": "Campo 1",
      "startsAt": "2026-08-12T16:00:00.000Z",
      "endsAt": "2026-08-12T17:30:00.000Z",
      "customerName": "Marta Bellini",
      "customerPhone": "+39 340 1122334",
      "customerEmail": "marta.bellini@example.com",
      "priceCents": 3000,
      "playersCount": null,
      "status": "confirmed",
      "paymentMethod": null,
      "paymentLink": null,
      "notes": "Prenotato dal sito della struttura",
      "source": "api",
      "recurrenceId": null,
      "createdAt": "2026-07-28T09:14:02.517Z",
      "updatedAt": "2026-07-28T09:14:02.517Z"
    }
  ],
  "limit": 500,
  "offset": 0
}

Champs d'une réservation

La même structure est retournée par POST et PATCH (dans la clé booking).

Erreurs spécifiques

6.3 Nouvelle réservation

Crée une réservation sur l'un de tes terrains. La réservation est créée avec source: "api", ce qui permet de la distinguer dans le panneau de celles saisies manuellement, et le gérant reçoit une notification push « Nouvelle réservation » sur l'app.

Les mêmes règles que celles du panneau sont appliquées, dans l'ordre :

1. fermeture exceptionnelle de la structure à la date de début → 409 venue_closed;
2. chevauchement avec une autre réservation non annulée du même terrain → 409 overlap;
3. tarif absent → calculé à partir de la grille tarifaire du terrain (null si l'heure de début ne correspond à aucun créneau). Si le créneau a un tarif par personne, playersCount est également requis : sans cela, la demande est rejetée avec 400 players_required (à moins d'indiquer un priceCents explicite).

Les horaires d'ouverture ne bloquent pas la création : ils sont informatifs, le gérant reste maître de son terrain. Si tu veux empêcher les réservations en dehors des horaires, vérifie toi-même hours renvoyé par /availability avant d'appeler la POST.

Corps de la requête (JSON)

Exemple de requête

curl -s -X POST https://www.volleyfriends.com/api/manager-api/v1/bookings   -H "X-Api-Key: $VF_API_KEY"   -H "Content-Type: application/json"   -d '{
    "courtId": "7c94a0d2-58b1-4e6f-9a3c-1d20f8b47e05",
    "startsAt": "2026-08-12T18:00:00+02:00",
    "endsAt": "2026-08-12T19:30:00+02:00",
    "customerName": "Marta Bellini",
    "customerPhone": "+39 340 1122334",
    "customerEmail": "marta.bellini@example.com",
    "notes": "Prenotato dal sito della struttura"
  }'

Exemple de réponse — 201

{
  "booking": {
    "id": "9d51c7b4-0e28-4f3a-a6d9-72b48e105c3f",
    "venueId": "b3f8e5c1-2d47-4a90-8f31-6c0d9a7e4512",
    "courtId": "7c94a0d2-58b1-4e6f-9a3c-1d20f8b47e05",
    "courtName": "Campo 1",
    "startsAt": "2026-08-12T16:00:00.000Z",
    "endsAt": "2026-08-12T17:30:00.000Z",
    "customerName": "Marta Bellini",
    "customerPhone": "+39 340 1122334",
    "customerEmail": "marta.bellini@example.com",
    "priceCents": 3000,
    "playersCount": null,
    "status": "confirmed",
    "paymentMethod": null,
    "paymentLink": null,
    "notes": "Prenotato dal sito della struttura",
    "source": "api",
    "recurrenceId": null,
    "createdAt": "2026-07-28T09:14:02.517Z",
    "updatedAt": "2026-07-28T09:14:02.517Z"
  }
}

Dans l'exemple, priceCents n'avait pas été indiqué : 90 minutes sur un créneau à 20,00 €/heure donnent 3000 centimes (le calcul est proportionnel aux minutes réelles, avec le tarif du créneau dans lequel commence la réservation).

Erreurs spécifiques

// 409 — chevauchement
{ "error": "overlap", "message": "Il campo è già prenotato in quell'orario." }

// 409 — fermeture exceptionnelle (le motif, s'il est indiqué par le gérant, figure dans le message)
{ "error": "venue_closed", "message": "Struttura chiusa in quella data (manutenzione)." }

6.4 Modification de réservation

Met à jour une réservation existante. C'est une mise à jour partielle : envoie uniquement les champs qui changent, les autres restent inchangés. Le corps doit contenir au moins un champ.

Il n'existe pas de point de terminaison d'annulation : pour annuler une réservation, on définit status: "cancelled". L'historique reste dans le panneau et le créneau redevient libre (les réservations annulées n'occupent pas le terrain et ne génèrent pas d'overlap).

Paramètre de chemin

Corps de la requête (JSON)

Tous les champs sont facultatifs. Ceux marqués « annulable » acceptent null pour vider la valeur.

Exemple de requête — déplacement et encaissement

curl -s -X PATCH   https://www.volleyfriends.com/api/manager-api/v1/bookings/9d51c7b4-0e28-4f3a-a6d9-72b48e105c3f   -H "X-Api-Key: $VF_API_KEY"   -H "Content-Type: application/json"   -d '{
    "startsAt": "2026-08-12T19:00:00+02:00",
    "endsAt": "2026-08-12T20:30:00+02:00",
    "status": "paid",
    "paymentMethod": "cash",
    "priceCents": 3000
  }'

Exemple de requête — annulation

curl -s -X PATCH   https://www.volleyfriends.com/api/manager-api/v1/bookings/9d51c7b4-0e28-4f3a-a6d9-72b48e105c3f   -H "X-Api-Key: $VF_API_KEY"   -H "Content-Type: application/json"   -d '{ "status": "cancelled" }'

Exemple de réponse — 200

La réservation mise à jour, dans le même format que la POST :

{
  "booking": {
    "id": "9d51c7b4-0e28-4f3a-a6d9-72b48e105c3f",
    "venueId": "b3f8e5c1-2d47-4a90-8f31-6c0d9a7e4512",
    "courtId": "7c94a0d2-58b1-4e6f-9a3c-1d20f8b47e05",
    "courtName": "Campo 1",
    "startsAt": "2026-08-12T17:00:00.000Z",
    "endsAt": "2026-08-12T18:30:00.000Z",
    "customerName": "Marta Bellini",
    "customerPhone": "+39 340 1122334",
    "customerEmail": "marta.bellini@example.com",
    "priceCents": 3000,
    "playersCount": null,
    "status": "paid",
    "paymentMethod": "cash",
    "paymentLink": null,
    "notes": "Prenotato dal sito della struttura",
    "source": "api",
    "recurrenceId": null,
    "createdAt": "2026-07-28T09:14:02.517Z",
    "updatedAt": "2026-07-28T11:02:47.883Z"
  }
}

Erreurs spécifiques

6.5 Disponibilité d'un terrain sur une journée

Renvoie, pour un terrain et un jour, les créneaux occupés, les horaires d'ouverture de ce jour de la semaine et l'éventuelle fermeture exceptionnelle. C'est l'endpoint à utiliser pour calculer les créneaux libres sur un site externe sans dupliquer les règles du logiciel de gestion : soustrais les réservations de la fenêtre d'ouverture.

Sont listés tous les créneaux qui occupent le terrain, dans n'importe quel état sauf cancelled : donc également les demandes de réservation en ligne encore pending. Le jour est le jour local italien et les intervalles sont semi-ouverts : une réservation qui se termine exactement à minuit appartient au jour précédent. Une réservation à cheval sur minuit apparaît dans les deux jours qu'elle intersecte, avec ses instants réels (qui peuvent tomber en dehors du jour demandé).

Paramètres (query string)

Exemple de requête

curl -s -G https://www.volleyfriends.com/api/manager-api/v1/availability   -H "X-Api-Key: $VF_API_KEY"   --data-urlencode "courtId=7c94a0d2-58b1-4e6f-9a3c-1d20f8b47e05"   --data-urlencode "date=2026-08-12"

Exemple de réponse — 200

{
  "courtId": "7c94a0d2-58b1-4e6f-9a3c-1d20f8b47e05",
  "venueId": "b3f8e5c1-2d47-4a90-8f31-6c0d9a7e4512",
  "date": "2026-08-12",
  "timezone": "Europe/Rome",
  "hours": {
    "weekday": 2,
    "openMinute": 540,
    "closeMinute": 1380,
    "closed": false,
    "configured": true
  },
  "closure": null,
  "bookings": [
    {
      "startsAt": "2026-08-12T16:00:00.000Z",
      "endsAt": "2026-08-12T17:30:00.000Z",
      "status": "confirmed"
    },
    {
      "startsAt": "2026-08-12T18:00:00.000Z",
      "endsAt": "2026-08-12T19:00:00.000Z",
      "status": "paid"
    },
    {
      "startsAt": "2026-08-12T19:00:00.000Z",
      "endsAt": "2026-08-12T20:30:00.000Z",
      "status": "pending"
    }
  ]
}

Champs de la réponse

Erreurs spécifiques

6.6 Grille tarifaire d'un terrain

La grille tarifaire du terrain en lecture seule : elle sert à afficher les prix au client avant la réservation, avec les mêmes tranches que le logiciel de gestion utilise pour calculer le prix automatique. Les tranches se modifient uniquement depuis le panneau. Elles sont triées par fromMinute croissant.

Paramètres (query string)

Exemple de requête

curl -s -G https://www.volleyfriends.com/api/manager-api/v1/rates   -H "X-Api-Key: $VF_API_KEY"   --data-urlencode "courtId=7c94a0d2-58b1-4e6f-9a3c-1d20f8b47e05"

Exemple de réponse — 200

{
  "courtId": "7c94a0d2-58b1-4e6f-9a3c-1d20f8b47e05",
  "rates": [
    {
      "id": "4a1e0b72-6d35-4c81-93af-0b7e2d5814c6",
      "label": "Mattina infrasettimanale",
      "daysMask": 31,
      "fromMinute": 480,
      "toMinute": 840,
      "pricePerHourCents": 1500,
      "pricingMode": "court",
      "minPlayers": null
    },
    {
      "id": "c07d9b31-8f42-4a05-b6e9-15d3c8017a2b",
      "label": "Serale",
      "daysMask": 127,
      "fromMinute": 1080,
      "toMinute": 1380,
      "pricePerHourCents": 600,
      "pricingMode": "person",
      "minPlayers": 10
    }
  ]
}

Champs de la réponse

Erreurs spécifiques

Un terrain sans grille tarifaire répond 200 avec "rates": [].

7. Conventions des données

7.1 Dates et horaires

• En entrée les instants sont des chaînes ISO 8601 avec offset obligatoire : 2026-08-12T18:00:00+02:00 ou 2026-08-12T18:00:00Z. Une chaîne sans offset (2026-08-12T18:00:00) est rejetée avec 400 : elle serait ambiguë, et pour un calendrier, c'est une ambiguïté qui se paie par des réservations erronées d'une heure.
• En sortie, les instants sont toujours normalisés en UTC avec le suffixe Z et millisecondes : "2026-08-12T16:00:00.000Z". Convertis-les dans le fuseau horaire local avant de les afficher.
• Les dates simples (date, closure.from, closure.to et from/to quand tu les utilises sous forme de jour) sont AAAA-MM-GG et se réfèrent au jour local italien.
• Les intervalles sont semi-ouverts [inizio, fine) : 18:00–19:00 et 19:00–20:00 ne sont pas en conflit.

7.2 Fuseau horaire

Les réservations sont conservées comme des instants absolus, mais toutes les règles de calendrier — jour de la semaine, tranches de tarifs, horaires d'ouverture, dates de fermeture, limites de la journée — sont évaluées dans le fuseau Europe/Rome, avec l'heure d'été gérée automatiquement. Le champ timezone de la réponse de /availability le déclare explicitement. Si ton serveur tourne en UTC ou dans un autre fuseau, ne convertis pas les minutes à la main : elles sont déjà exprimées en heure locale italienne.

7.3 Minutes depuis minuit

Les horaires « de calendrier » (openMinute, closeMinute, fromMinute, toMinute) sont des entiers de 0 à 1440 qui comptent les minutes depuis minuit heure locale. Conversions : ore = ⌊m / 60⌋, minuti = m mod 60.

7.4 Montants

Tous les montants sont des entiers en centimes d'euro (priceCents, pricePerHourCents) : aucune valeur à virgule flottante, aucun symbole de devise. 2000 = 20,00 €. Sur une réservation, priceCents: null signifie « prix à définir » et est différent de 0, qui signifie « gratuit ».

7.5 États d'une réservation

7.6 Origine et mode de paiement

Les deux sont des domaines textuels : de nouvelles valeurs peuvent être ajoutées à l'avenir sans changement de version, ton code ne doit donc pas générer d'erreur sur une valeur qu'il ne connaît pas.

7.7 Données personnelles des clients

Le nom, le téléphone et l'e-mail que tu envoies dans les réservations sont des données personnelles de tes clients : tu es le responsable du traitement, VolleyFriends les conserve pour ton compte en tant que sous-traitant au sens de l'art. 28 GDPR. Envoie uniquement ce qui est nécessaire à la gestion du terrain et informe tes clients. Les détails figurent dans la privacy policy.

8. Erreurs générales

Chaque erreur a le même corps : un code stable dans error, conçu pour ton code, et un message en italien, conçu pour les personnes. Prends tes décisions sur error et sur le statut HTTP, non sur le texte du message, qui peut changer.

{
  "error": "overlap",
  "message": "Il campo è già prenotato in quell'orario."
}

Les erreurs de validation ajoutent issues, la liste détaillée des problèmes champ par champ :

{
  "error": "invalid_input",
  "message": "Dati non validi",
  "issues": [
    {
      "code": "invalid_string",
      "validation": "datetime",
      "path": ["startsAt"],
      "message": "Invalid datetime"
    }
  ]
}

Un chemin inexistant sous la base renvoie 404 ; il en va de même pour une méthode non prévue sur un chemin existant :

{
  "error": "not_found",
  "message": "Risorsa non trovata"
}

Les réponses 502, 503 et 504 proviennent du reverse proxy lorsque l'API n'est pas joignable (redémarrage ou maintenance) : dans ces cas, le corps n'est pas garanti au format JSON. Traite-les comme des erreurs temporaires et réessaye avec un backoff, sans tenter d'en lire le contenu.

9. Versions et compatibilité

La version est dans le path : /manager-api/v1. Il n'existe aucun header de version ni date de release à spécifier : la seule version actuellement publiée est v1.

Ce que nous pouvons modifier sans te prévenir

• Ajouter des champs aux réponses existantes.
• Ajouter des paramètres optionnels aux requêtes, avec une valeur par défaut qui conserve le comportement actuel.
• Ajouter de nouveaux endpoints sous /v1.
• Ajouter des valeurs aux champs textuels ouverts (source, paymentMethod, surface).
• Reformuler les message des erreurs, en maintenant inchangés les codes error.

Ce qui ne change pas au sein de la v1

• Aucun champ ne sera supprimé ou renommé dans les réponses.
• Aucun champ ne changera de type ou de signification.
• Aucun paramètre actuellement optionnel ne deviendra obligatoire.
• Les codes error et les statuts HTTP documentés ici restent les mêmes.

Toute modification rompant ces garanties arrivera sur un nouveau préfixe (/v2), la v1 étant maintenue en service avec un préavis pour les gestionnaires qui l'utilisent.

Changelog

10. Support à l'intégration

Pour des questions techniques, des comportements inattendus ou des demandes d'endpoints que tu ne trouves pas ici, écris-nous depuis la page Contacts. Pour aller droit au but, indique dans le message :

• l'endpoint et la méthode que tu appelles ;
• la date et l'heure de l'appel (avec le fuseau horaire) et le code HTTP reçu ;
• le code error et le message de la réponse ;
• le préfixe de la clé utilisée (ex. vfk_9f2c).

Si tu as besoin de tester l'intégration sans toucher au calendrier réel, crée une structure d'essai avec un terrain dédié et utilise-la : tous les appels sont limités aux structures du propriétaire de la clé, le reste de ton compte n'est donc pas concerné.