Mostra le tue prenotazioni sul tuo sito web con l'API pubblica

Molte agenzie e artisti mostrano le loro prossime date sul proprio sito web: una pagina tour, un calendario concerti o una semplice lista di show. L'API pubblica di Artistu ti offre un feed in sola lettura delle tue prenotazioni annunciate, così il tuo sito web mostra sempre le stesse date che gestisci in Artistu. Niente copia manuale, niente pagine tour non aggiornate.

L'API è in sola lettura ed espone solo le informazioni che hai esplicitamente contrassegnato come pubbliche. Cachet, deal, contatti, note interne e show non annunciati non sono mai inclusi.

Come funziona

Tre elementi lavorano insieme:

1. Un token API, generato una sola volta nelle impostazioni di Artistu, che autentica il tuo sito web.
2. Impostazioni online per prenotazione, che controllano se una prenotazione è annunciata e quali dettagli pubblici contiene.
3. Un singolo endpoint che restituisce le prenotazioni annunciate di un artista in JSON.

Genera il tuo token API

Vai su Impostazioni → Integrazioni e trova la sezione API pubblica. Clicca su Genera token. Per farlo devi essere admin della tua organizzazione.

Il token è una stringa di 64 caratteri. Trattalo come una password: chiunque lo possieda può leggere i tuoi dati pubblici delle prenotazioni. Dopo la generazione viene mascherato nell'interfaccia, usa il pulsante Mostra per rivelarlo di nuovo.

Una volta creato il token sono disponibili altre due azioni:

• Rigenera token crea un nuovo token e invalida immediatamente quello vecchio. Qualsiasi sito web o integrazione che usa ancora il vecchio token smette subito di funzionare.
• Revoca token elimina il token senza crearne uno nuovo. Tutto l'accesso all'API si ferma finché non generi un nuovo token.

Controlla quali prenotazioni appaiono

Non tutte le prenotazioni devono stare sul tuo sito web. Una prenotazione appare nell'API solo quando tutte queste condizioni sono vere:

1. Lo stato della prenotazione è opzione o confermata. Le prenotazioni in sospeso e annullate non appaiono mai.
2. La prenotazione è annunciata: o l'interruttore Annunciato è attivo, o la data di Annuncia il è passata.
3. L'interruttore Nascondi dall'API pubblica è disattivato.

Gestisci tutto questo per singola prenotazione. Apri una prenotazione, vai alla scheda Impostazioni e scorri fino alla sezione Online. Lì trovi:

Campo	Funzione
Annuncia il	Data da cui la prenotazione diventa automaticamente annunciata
Annunciato	Contrassegna manualmente la prenotazione come annunciata da subito
Nascondi dall'API pubblica	Tieni la prenotazione fuori dall'API anche quando è annunciata
Sito web	Sito web pubblico dell'evento o del locale, incluso nella risposta dell'API
Link biglietti	Link alla vendita dei biglietti, incluso nella risposta dell'API
Line-up	Testo pubblico della line-up, incluso nella risposta dell'API
Note pubbliche	Qualsiasi testo pubblico aggiuntivo, incluso nella risposta dell'API

La data di Annuncia il è utile quando uno show è confermato ma sotto embargo fino alla data dell'annuncio ufficiale. Imposta la data e la prenotazione apparirà nell'API automaticamente da quel giorno.

Nascondi dall'API pubblica è il controllo per gli show annunciati altrove ma che non devono comparire sul tuo sito web, per esempio eventi privati.

Trova l'ID del tuo artista

L'API restituisce le prenotazioni di un artista alla volta. Trovi l'ID dell'artista nella barra degli indirizzi quando visualizzi l'artista nella tua dashboard:

https://artistu.io/dashboard/artists/{artistId}

L'ultima parte dell'URL è l'ID da passare all'API. Se il tuo sito web mostra più artisti, fai una richiesta per ogni artista.

Recupera le prenotazioni

GET https://artistu.io/api/public/bookings/{artistId}

Autenticati con il tuo token nell'header Authorization:

Authorization: Bearer YOUR_API_TOKEN

Parametri di query

Parametro	Formato	Predefinito	Descrizione
startDate	YYYY-MM-DD	oggi	Prima data inclusa
endDate	YYYY-MM-DD	startDate + 1 mese	Ultima data inclusa

L'intervallo di date può coprire al massimo 366 giorni e startDate deve essere uguale o precedente a endDate.

Esempio di richiesta

curl -X GET 'https://artistu.io/api/public/bookings/{artistId}?startDate=2026-08-01&endDate=2026-12-31' \
  --header 'Authorization: Bearer YOUR_API_TOKEN'

Esempio di risposta

{
  "bookings": [
    {
      "bookingId": "uq1ye3nqnb4m5f234auf69gk",
      "artistName": "DJ Example",
      "name": "Summer Festival 2026",
      "date": "2026-08-15T00:00:00.000Z",
      "time": "22:00",
      "duration": 90,
      "venue": "Festival Grounds",
      "capacity": 15000,
      "status": "confirmed",
      "address": {
        "description": "Festival Grounds, Amsterdam, Netherlands",
        "geometry": { "lat": 52.3676, "lng": 4.9041 },
        "components": {
          "city": "Amsterdam",
          "country": "Netherlands",
          "countryCode": "NL"
        }
      },
      "website": "https://summerfestival.example",
      "ticketLink": "https://tickets.example/summer-festival",
      "lineUp": "DJ Example, Support Act",
      "publicNotes": "Main stage closing set"
    }
  ],
  "truncated": false
}

Le prenotazioni sono ordinate per data crescente. duration è in minuti. status è option oppure confirmed. I campi senza valore sono null.

Una risposta contiene al massimo 500 prenotazioni. Se il tuo intervallo di date ne include di più, truncated è true e viene incluso un campo maxResults. Riduci l'intervallo di date per recuperare il resto.

Limiti di richieste

• 60 richieste al minuto per token
• 120 richieste al minuto per indirizzo IP

Ogni risposta include gli header X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset. Se superi un limite, l'API risponde con stato 429 e ti dice quanti secondi aspettare.

Per un sito web tipico, metti in cache la risposta dell'API sul tuo server per qualche minuto invece di chiamare l'API a ogni visita. La tua pagina tour resta veloce e rimani ben lontano dai limiti.

Risoluzione dei problemi

• 401 Unauthorized: il token manca, è malformato, oppure è stato rigenerato o revocato. Controlla l'header Authorization: Bearer e confronta il token con quello in Impostazioni → Integrazioni.
• 404 Artist not found: l'ID dell'artista non esiste o appartiene a un'organizzazione diversa da quella del token.
• 400 Bad request: una data non è nel formato YYYY-MM-DD, startDate è successiva a endDate, oppure l'intervallo supera i 366 giorni.
• Manca una prenotazione: verifica le tre condizioni di visibilità qui sopra. Nella maggior parte dei casi la prenotazione non è ancora annunciata, oppure il suo stato è ancora in sospeso.