Sviluppatori

Un'API REST pubblica per club e partner certificati: letture con ambito definito, prenotazioni via API e webhook firmati con HMAC.

Autenticazione

Ogni chiave viene generata dal pannello del club, in Amministrazione → API e webhook, e viaggia come intestazione Bearer.

curl -H "Authorization: Bearer mp_…" \
  https://api.meetandplay.mx/api/v1/clubs/{clubId}/bookings

La chiave completa viene mostrata una sola volta. Conservala in un posto sicuro.

Endpoint

Ogni chiave dichiara gli ambiti con cui è stata creata; una richiesta senza l'ambito necessario viene rifiutata.

GET/clubs/{clubId}/courts
Il catalogo dei campi del club.
GET/clubs/{clubId}/availability
Fasce occupate per campo, fino a 14 giorni.
GET/clubs/{clubId}/bookings
Le prenotazioni del club, più recenti prima.
GET/clubs/{clubId}/customers
La rubrica clienti del club — dati personali, dietro un ambito proprio.
POST/clubs/{clubId}/bookings
Crea una prenotazione, come alla reception del club.
POST/clubs/{clubId}/bookings/{bookingId}/cancel
Annulla una prenotazione; rimborsa o annulla il pagamento secondo la politica del club.

Webhook

Ricevi eventi firmati con HMAC-SHA256 sul tuo URL: prenotazione creata, confermata o annullata, pagamento riuscito e partita al completo. Ogni consegna riprova con backoff; dopo diversi tentativi falliti finisce nella coda delle consegne fallite, riconsegnabile dal pannello del club.

Autenticazione dei webhook

Oltre alla firma HMAC (x-map-signature), ogni webhook può inviare un header Authorization, Basic (nome utente e password) o Bearer (token). Si configura nel pannello del club, in Amministrazione → API e webhook, nell'autenticazione di ciascun webhook. La credenziale viene salvata cifrata e non viene più mostrata.

POST https://…/webhooks
x-map-signature: t=1767225600,v1=…
x-map-delivery: 0199…
Authorization: Bearer …

Viene inviato a ogni consegna, anche nei nuovi tentativi e nelle riconsegne dalla coda delle consegne fallite, con la credenziale valida al momento dell'invio: se la cambi o la rimuovi, la modifica vale anche per le consegne già in coda. Se il server non riesce a decifrare la credenziale, la consegna non parte mai senza: finisce nella coda delle consegne fallite. Se cambi l'URL o elimini il webhook, le consegne in coda per il vecchio URL vengono annullate o spostate nella coda delle consegne fallite: la credenziale non viene mai inviata a un URL che non hai più registrato.
Consigliamo comunque di verificare la firma HMAC: l'header Authorization dice chi chiama, ma solo la firma prova che il corpo non è stato modificato, e il suo timestamp (t=) ti permette di rifiutare consegne ripetute.
I reindirizzamenti non vengono seguiti: una risposta 3xx conta come consegna fallita e viene ritentata, quindi la credenziale non arriva mai a un altro URL. Registra l'URL finale del tuo ricevitore.

Limiti di utilizzo

Ogni chiave ha un limite di richieste al minuto. Una risposta 429 significa che è stato raggiunto; rallenta e riprova.

Partner certificati

Un partner certificato si connette con un clic dal pannello del club — senza copiare e incollare chiavi a mano.

Pronto a integrare il tuo club?

Accedi al pannello del club e genera la tua prima chiave in Amministrazione → API e webhook.

Vai al pannello del club Specifica OpenAPI