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. Una chiave API, creata nelle impostazioni di Artistu e limitata agli artisti che scegli, 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.

Crea una chiave API

Vai su Impostazioni → Integrazioni e trova la sezione Chiavi dell'API pubblica. Clicca su Crea chiave, dai un nome alla chiave (per esempio il sito a cui serve) e scegli gli artisti che può leggere, oppure seleziona Tutti gli artisti. Devi essere amministratore della tua organizzazione.

La chiave viene mostrata una sola volta, subito dopo la creazione. Copiala subito: Artistu conserva solo un'impronta della chiave, quindi nessuno può recuperarla, nemmeno noi. Persa? Revocala e creane una nuova.

Le chiavi sono limitate ai loro artisti. Una chiave creata per il sito di un artista restituisce solo gli ingaggi di quell'artista, quindi una chiave trapelata espone quell'artista e non tutto il tuo roster. Crea una chiave per ogni sito.

Ogni chiave nell'elenco mostra i suoi artisti, quando è stata creata e quando è stata usata l'ultima volta. Revoca blocca una chiave all'istante. Qualsiasi sito o integrazione che la usa ancora smette subito di funzionare.

Hai creato un token prima che esistessero le chiavi? Per ora continua a funzionare e ha accesso a tutti gli artisti. Crea una nuova chiave, aggiorna il tuo sito e poi revoca il vecchio 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 Dettagli e scorri fino alla sezione Pubblico. 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: la chiave manca, è malformata o è stata revocata. Controlla l'header Authorization: Bearer e confronta l'inizio della chiave con l'elenco in Impostazioni → Integrazioni.
• 404 Artist not found: l'ID dell'artista non esiste, appartiene a un'altra organizzazione o non è tra gli artisti della chiave.
• 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.