API per gestionali esterni

1. Cosa permettono le API

Con una chiave API puoi, dal tuo software, leggere e scrivere sul calendario delle tue strutture:

• leggere strutture e campi con i loro identificativi, necessari a tutte le altre chiamate;
• leggere le prenotazioni di un periodo, di una struttura o di un singolo campo, per allinearle al tuo archivio;
• creare prenotazioni dall'esterno (per esempio quando un cliente prenota dal tuo sito), con gli stessi controlli di sovrapposizione e chiusura del pannello;
• modificare o annullare una prenotazione esistente (spostamento di orario o campo, incasso, note, annullamento);
• leggere la disponibilità di un campo in un giorno: slot già occupati, orari di apertura e chiusure straordinarie, così da proporre gli slot liberi senza replicare le regole;
• leggere il listino di un campo per mostrare i prezzi al cliente finale.

Non fanno parte di queste API le richieste degli organizzatori per l'uso dei campi nei tornei (si approvano dall'app), la creazione di strutture e campi, il salvataggio di orari, chiusure e listino: sono operazioni del pannello gestore.

2. Requisiti e attivazione

1. Un account gestore campi VolleyFriends con almeno una struttura e un campo.
2. Un abbonamento in corso con un piano che include la funzione «API per gestionali esterni». L'intera v1 — anche le sole letture — è riservata a chi ha questa funzione: è una funzione venduta, non un accessorio del pannello.
3. Una chiave API generata dal gestionale: admin.volleyfriends.com → Impostazioni → Chiavi API → Nuova chiave.

La chiave ha la forma vfk_ seguito da 40 caratteri esadecimali (44 caratteri in tutto) e viene mostrata una sola volta, subito dopo la creazione: nel database resta soltanto la sua impronta sha256, quindi non è recuperabile in nessun modo. Se la perdi, revocala e generane una nuova. Nell'elenco del pannello vedi solo il prefisso (es. vfk_9f2c), la data di creazione e quella dell'ultimo utilizzo.

3. Autenticazione

Ogni richiesta va autenticata con l'header X-Api-Key. Non servono token, login, scadenze o rinnovi: la chiave resta valida finché non la revochi.

# Le chiavi di questa pagina sono di esempio: sostituisci con la tua.
curl -s https://www.volleyfriends.com/api/manager-api/v1/venues   -H "X-Api-Key: vfk_9f2c41a7b83d05e6c19af4728b60d35e1c9a7f42"

Negli esempi che seguono la chiave è letta dalla variabile d'ambiente VF_API_KEY, come conviene fare anche in produzione.

Header assente, più corto di 12 caratteri, sconosciuto o appartenente a una chiave revocata: la risposta è 401 con questo corpo.

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

4. Base URL

https://www.volleyfriends.com/api

I path documentati qui sotto vanno accodati alla base. Il prefisso /api appartiene al reverse proxy, quindi l'indirizzo completo di un endpoint è per esempio:

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

Tutte le risposte sono application/json con codifica UTF-8. Le richieste con corpo (POST, PATCH) devono avere Content-Type: application/json.

5. Rate limiting

Il limite è di 120 richieste al minuto per chiave API (finestra scorrevole di 1 minuto). Il conteggio è per chiave, non per indirizzo IP: i gestionali stanno spesso dietro lo stesso indirizzo del provider e un limite per IP penalizzerebbe gestori diversi ospitati sulla stessa infrastruttura. Se l'header X-Api-Key manca del tutto, il conteggio ricade sull'indirizzo IP.

Ogni risposta riporta lo stato del contatore negli header x-ratelimit-limit, x-ratelimit-remaining e x-ratelimit-reset (secondi al reset). Al superamento viene aggiunto anche retry-after.

Risposta al superamento — 429

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

6. Endpoint

Sei endpoint, tutti sotto /manager-api/v1. Ogni chiamata passa dalla stessa catena di controlli, nell'ordine: chiave API valida → funzione «API per gestionali esterni» inclusa nel piano → rate limit → validazione dei parametri → verifica che la risorsa sia tua.

6.1 Strutture e campi

Elenca le tue strutture, ciascuna con i propri campi annidati. È la chiamata da cui partire: gli id dei campi (courtId) servono a tutti gli altri endpoint. Le strutture sono ordinate per nome, i campi per nome.

Parametri

Nessuno.

Esempio di richiesta

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

Esempio di risposta — 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
        }
      ]
    }
  ]
}

Campi della risposta

Se l'account non ha ancora strutture la risposta è {"venues": []}.

Errori specifici

Nessuno oltre a quelli generali.

6.2 Elenco prenotazioni

Restituisce le prenotazioni delle tue strutture, ordinate per orario di inizio crescente. L'elenco è paginato: al massimo limit righe per chiamata (default 500, tetto 1000) — se ricevi esattamente limit righe, richiama con offset aumentato per la pagina successiva. In produzione filtra comunque sempre almeno per intervallo di date.

Parametri (query string)

Esempio di richiesta

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"

Esempio di risposta — 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
}

Campi di una prenotazione

La stessa struttura è restituita da POST e PATCH (dentro la chiave booking).

Errori specifici

6.3 Nuova prenotazione

Crea una prenotazione su un tuo campo. La prenotazione nasce con source: "api", così nel pannello si distingue da quelle inserite a mano, e il gestore riceve una notifica push «Nuova prenotazione» sull'app.

Vengono applicate le stesse regole del pannello, nell'ordine:

1. chiusura straordinaria della struttura nella data di inizio → 409 venue_closed;
2. sovrapposizione con un'altra prenotazione non annullata dello stesso campo → 409 overlap;
3. prezzo assente → calcolato dal listino del campo (null se l'orario di inizio non ricade in nessuna fascia). Se la fascia ha il prezzo a persona, serve anche playersCount: senza, la richiesta è rifiutata con 400 players_required (a meno di indicare un priceCents esplicito).

Gli orari di apertura non bloccano la creazione: sono informativi, il gestore resta sovrano sul proprio campo. Se vuoi impedire prenotazioni fuori orario, controlla tu hours restituito da /availability prima di chiamare la POST.

Corpo della richiesta (JSON)

Esempio di richiesta

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"
  }'

Esempio di risposta — 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"
  }
}

Nell'esempio priceCents non era stato indicato: 90 minuti su una fascia da 20,00 €/ora danno 3000 centesimi (il calcolo è proporzionale ai minuti effettivi, con la tariffa della fascia in cui inizia la prenotazione).

Errori specifici

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

// 409 — chiusura straordinaria (il motivo, se indicato dal gestore, è nel messaggio)
{ "error": "venue_closed", "message": "Struttura chiusa in quella data (manutenzione)." }

6.4 Modifica prenotazione

Aggiorna una prenotazione esistente. È un aggiornamento parziale: manda solo i campi che cambiano, gli altri restano invariati. Il corpo deve contenere almeno un campo.

Non esiste un endpoint di cancellazione: per annullare una prenotazione si imposta status: "cancelled". Lo storico resta nel pannello e lo slot torna libero (le prenotazioni annullate non occupano il campo e non generano overlap).

Parametro di percorso

Corpo della richiesta (JSON)

Tutti i campi sono opzionali. Quelli marcati «annullabile» accettano null per svuotare il valore.

Esempio di richiesta — spostamento e incasso

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
  }'

Esempio di richiesta — annullamento

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" }'

Esempio di risposta — 200

La prenotazione aggiornata, nello stesso formato della 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"
  }
}

Errori specifici

6.5 Disponibilità di un campo in un giorno

Restituisce, per un campo e un giorno, gli slot occupati, gli orari di apertura di quel giorno della settimana e l'eventuale chiusura straordinaria. È l'endpoint da usare per calcolare gli slot liberi su un sito esterno senza duplicare le regole del gestionale: sottrai le prenotazioni dalla finestra di apertura.

Sono elencati tutti gli slot che occupano il campo, in qualunque stato tranne cancelled: quindi anche le richieste di prenotazione online ancora pending. Il giorno è quello locale italiano e gli intervalli sono semiaperti: una prenotazione che finisce esattamente a mezzanotte appartiene al giorno precedente. Una prenotazione a cavallo della mezzanotte compare in entrambi i giorni che interseca, con i suoi istanti reali (che possono cadere fuori dal giorno richiesto).

Parametri (query string)

Esempio di richiesta

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"

Esempio di risposta — 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"
    }
  ]
}

Campi della risposta

Errori specifici

6.6 Listino di un campo

Il listino del campo in sola lettura: serve a mostrare i prezzi al cliente prima della prenotazione, con le stesse fasce che il gestionale usa per calcolare il prezzo automatico. Le fasce si modificano solo dal pannello. Sono ordinate per fromMinute crescente.

Parametri (query string)

Esempio di richiesta

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"

Esempio di risposta — 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
    }
  ]
}

Campi della risposta

Errori specifici

Un campo senza listino risponde 200 con "rates": [].

7. Convenzioni dei dati

7.1 Date e orari

• In ingresso gli istanti sono stringhe ISO 8601 con offset obbligatorio: 2026-08-12T18:00:00+02:00 oppure 2026-08-12T18:00:00Z. Una stringa senza offset (2026-08-12T18:00:00) viene rifiutata con 400: sarebbe ambigua, e per un calendario è una ambiguità che si paga con prenotazioni sbagliate di un'ora.
• In uscita gli istanti sono sempre normalizzati in UTC con suffisso Z e millisecondi: "2026-08-12T16:00:00.000Z". Convertili nel fuso locale prima di mostrarli.
• Le date secche (date, closure.from, closure.to, e from/to quando li usi in forma di giorno) sono AAAA-MM-GG e si riferiscono al giorno locale italiano.
• Gli intervalli sono semiaperti [inizio, fine): 18:00–19:00 e 19:00–20:00 non sono in conflitto.

7.2 Fuso orario

Le prenotazioni sono conservate come istanti assoluti, ma tutte le regole di calendario — giorno della settimana, fasce del listino, orari di apertura, date di chiusura, confini del giorno — sono valutate nel fuso Europe/Rome, con l'ora legale gestita automaticamente. Il campo timezone della risposta di /availability lo dichiara esplicitamente. Se il tuo server gira in UTC o in un altro fuso, non convertire a mano i minuti: sono già espressi in ora locale italiana.

7.3 Minuti dalla mezzanotte

Gli orari «da calendario» (openMinute, closeMinute, fromMinute, toMinute) sono interi da 0 a 1440 che contano i minuti dalla mezzanotte locale. Conversioni: ore = ⌊m / 60⌋, minuti = m mod 60.

7.4 Importi

Tutti gli importi sono interi in centesimi di euro (priceCents, pricePerHourCents): nessun valore in virgola mobile, nessun simbolo di valuta. 2000 = 20,00 €. Su una prenotazione, priceCents: null significa «prezzo da definire» ed è diverso da 0, che significa «gratuito».

7.5 Stati di una prenotazione

7.6 Origine e metodo di pagamento

Entrambi sono domini testuali: nuovi valori possono essere aggiunti in futuro senza cambiare versione, quindi il tuo codice non deve andare in errore su un valore che non conosce.

7.7 Dati personali dei clienti

Nome, telefono ed email che invii nelle prenotazioni sono dati personali dei tuoi clienti: sei tu il titolare del trattamento, VolleyFriends li conserva per tuo conto come responsabile ai sensi dell'art. 28 GDPR. Manda solo ciò che serve alla gestione del campo e informa i tuoi clienti. Il dettaglio è nella privacy policy.

8. Errori generali

Ogni errore ha lo stesso corpo: un codice stabile in error, pensato per il tuo codice, e un message in italiano, pensato per le persone. Fai le tue decisioni su error e sullo stato HTTP, non sul testo del messaggio, che può cambiare.

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

Gli errori di validazione aggiungono issues, l'elenco dettagliato dei problemi campo per campo:

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

Un path inesistente sotto la base risponde 404; lo stesso vale per un metodo non previsto su un path esistente:

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

Le risposte 502, 503 e 504 arrivano dal reverse proxy quando l'API non è raggiungibile (riavvio o manutenzione): in quei casi il corpo non è garantito in formato JSON. Trattale come errori temporanei e ritenta con backoff, senza tentare di leggerne il contenuto.

9. Versioni e compatibilità

La versione è nel path: /manager-api/v1. Non esistono header di versione né date di release da specificare: l'unica versione attualmente pubblicata è v1.

Che cosa possiamo cambiare senza avvisarti

• Aggiungere campi alle risposte esistenti.
• Aggiungere parametri opzionali alle richieste, con un valore predefinito che conserva il comportamento attuale.
• Aggiungere nuovi endpoint sotto /v1.
• Aggiungere valori ai campi testuali aperti (source, paymentMethod, surface).
• Riformulare i message degli errori, mantenendo invariati i codici error.

Che cosa non cambia dentro la v1

• Nessun campo verrà rimosso o rinominato dalle risposte.
• Nessun campo cambierà tipo o significato.
• Nessun parametro oggi opzionale diventerà obbligatorio.
• I codici error e gli stati HTTP documentati qui restano quelli.

Qualunque modifica che rompa queste garanzie arriverà su un nuovo prefisso (/v2), con la v1 mantenuta in servizio e un preavviso ai gestori che la stanno usando.

Changelog

10. Supporto all'integrazione

Per domande tecniche, comportamenti inattesi o richieste di endpoint che qui non trovi, scrivici dalla pagina Contatti. Per arrivare subito al punto, indica nel messaggio:

• endpoint e metodo che stai chiamando;
• data e ora della chiamata (con il fuso) e il codice HTTP ricevuto;
• codice error e messaggio della risposta;
• prefisso della chiave usata (es. vfk_9f2c).

Se hai bisogno di provare l'integrazione senza toccare il calendario reale, crea una struttura di prova con un campo dedicato e usa quella: tutte le chiamate sono limitate alle strutture del proprietario della chiave, quindi il resto del tuo account non è coinvolto.