API-handleiding

Wat is het

Een API waarmee je alleen kunt lezen. Schrijven, aanpassen of verwijderen kan niet. Elke sleutel hoort bij een organisatie en ziet alleen de gegevens van die organisatie. Waar de grens ligt is geen afspraak in onze code die iemand kan vergeten: elke vraag loopt via de database, die de sleutel toetst en alleen rijen van die organisatie teruggeeft.

Er zijn twee soorten sleutels:

• Volledige sleutel, begint met ub_live_. Voor een koppeling met een CRM, een boekhouder of je eigen programma. Zet hem nooit in een website. Dit vraagt de API in je pakket: die zit in Ultimate Artist en Ultimate Agency. Bij Artist en Agency kun je hem erbij nemen voor € 15,00 per maand excl. btw.
• Website-sleutel, begint met ub_web_. Gratis in elk pakket. Geeft alleen je openbare shows (datum, zaal, stad, land, artiest) en mag daarom gewoon in de code van je website staan.

Een sleutel maken

1. Ga in Ultimate Bookings naar Instellingen, API-sleutels. Alleen de eigenaar van de organisatie kan hier sleutels maken, pauzeren en verwijderen.
2. Geef de sleutel een naam (tot 80 tekens), bijvoorbeeld Website of CRM.
3. Kies het soort: website-sleutel of volledige sleutel.
4. Bij een volledige sleutel vink je aan wat hij mag lezen: Shows (altijd aan), Agenda, Contacten, Artiesten en Geld. Geld staat standaard uit: pas als je dat aanvinkt ziet de sleutel gages en facturen.
5. Kies Sleutel maken. De sleutel staat daarna een keer in beeld. Kopieer hem meteen. Wij bewaren alleen een afgeleide waarde (een hash), dus we kunnen hem je niet opnieuw laten zien. Kwijt? Verwijder hem en maak een nieuwe.

Een sleutel kun je pauzeren: hij werkt dan meteen niet meer en je kunt hem later weer aanzetten. Verwijderen is definitief. In de lijst zie je per sleutel wanneer hij voor het laatst is gebruikt en hoe vaak.

Een show komt pas in de website-sleutel als je hem zelf hebt aangevinkt bij Op je website tonen in het boekingsformulier. Standaard staat dat uit, zodat een privefeest of een optie nooit vanzelf openbaar wordt.

Inloggen met je sleutel

Stuur de sleutel mee in de kop van elk verzoek:

Authorization: Bearer ub_live_JOUW_SLEUTEL

Een website-sleutel mag ook in het adres, als ?sleutel=ub_web_.... Dat is bedoeld voor een browser: die bron is voor elke website bereikbaar (CORS staat open), zodat je vanuit je eigen pagina rechtstreeks kunt ophalen. Dit werkt alleen voor openbare-shows. Een volledige sleutel in het adres wordt genegeerd; die moet altijd in de kop en hoort alleen op een server.

De zes bronnen

Alle adressen zijn GET en beginnen met https://ultimate-bookings.com/api/v1. Een volledige sleutel heeft het genoemde recht nodig; Shows heeft elke volledige sleutel. Velden zonder waarde ontbreken in het antwoord in plaats van null te zijn.

Parameters

• van en tot: een datum als 2026-10-01, in Amsterdamse tijd. Beide dagen tellen mee. Bij shows en agenda gaat het om de begintijd, bij facturen om de factuurdatum.
• limiet: hoeveel rijen per keer, een heel getal van 1 tot en met 500. Standaard 100.
• vanaf: hoeveel rijen je overslaat (offset), voor de volgende pagina. Standaard 0.

Een parameter die een bron niet gebruikt wordt wel gecontroleerd op geldigheid, maar doet verder niets.

Antwoord, fouten en limieten

Een gelukt verzoek geeft een data-lijst en een meta-blok terug. aantal is het aantal rijen in dit antwoord, limiet en vanaf zijn de waarden die we gebruikt hebben.

{
  "data": [
    {
      "id": "0b6f1c1e-...",
      "titel": "Zaterdagavond Paradiso",
      "status": "confirmed",
      "soort": "show",
      "start": "2026-10-10T20:00:00+00:00",
      "hele_dag": false,
      "zaal": "Paradiso",
      "stad": "Amsterdam",
      "land": "NL",
      "artiest_id": "5d0c9a52-...",
      "artiest": "Afro Bros",
      "openbaar": true
    }
  ],
  "meta": { "aantal": 1, "limiet": 50, "vanaf": 0 }
}

Bij een fout krijg je een error-blok met een vaste code (waar je op kunt controleren) en een message (leesbaar, kan veranderen):

{
  "error": {
    "code": "geen_recht",
    "message": "Deze sleutel mag dit onderdeel niet lezen. Zet het vinkje aan bij Instellingen, API-sleutels."
  }
}

Limieten

• Maximaal 60 verzoeken per volledige sleutel per minuut. Een website-sleutel mag er 3000 per minuut, omdat al je bezoekers hem delen.
• Maximaal 120 verzoeken per IP-adres per minuut, over alle sleutels samen.
• Zit je erboven, dan krijg je status 429 met de kop Retry-After (in seconden). Wacht zo lang en probeer opnieuw.
• Antwoorden van openbare-shows mogen een minuut bewaard worden (met ?sleutel= in het adres ook door ons netwerk), dus een nieuwe show, of een website-sleutel die je pauzeert, kan een minuut op zich laten wachten. Alle andere bronnen worden nooit bewaard en een gepauzeerde volledige sleutel stopt meteen.

Voorbeelden

Shows van oktober ophalen met curl

Volledige sleutel, 50 shows per keer, vanaf de eerste.

curl -H "Authorization: Bearer ub_live_JOUW_SLEUTEL" \
  "https://ultimate-bookings.com/api/v1/shows?van=2026-10-01&tot=2026-10-31&limiet=50&vanaf=0"

Aankomende shows op je website

Met een website-sleutel. Dit vult een lijst op je pagina en zet de gegevens als tekst neer, niet als HTML, zodat vreemde tekens in een zaalnaam niets kapot kunnen maken. Wil je het eerst proberen:

curl "https://ultimate-bookings.com/api/v1/openbare-shows?limiet=10&sleutel=ub_web_JOUW_SLEUTEL"

<ul id="ub-shows"></ul>
<script>
  var SLEUTEL = "ub_web_JOUW_SLEUTEL";
  var ADRES = "https://ultimate-bookings.com/api/v1/openbare-shows?limiet=10&sleutel=" + SLEUTEL;
  var lijst = document.getElementById("ub-shows");

  fetch(ADRES)
    .then(function (antwoord) {
      if (!antwoord.ok) throw new Error("HTTP " + antwoord.status);
      return antwoord.json();
    })
    .then(function (uitkomst) {
      if (uitkomst.data.length === 0) {
        lijst.textContent = "Nog geen shows aangekondigd.";
        return;
      }
      uitkomst.data.forEach(function (show) {
        // datum is een kale dag (JJJJ-MM-DD); in UTC lezen, dan schuift hij nergens een dag op.
        var datum = new Date(show.datum + "T12:00:00Z").toLocaleDateString("nl-NL", {
          day: "numeric", month: "long", year: "numeric", timeZone: "UTC"
        });
        var plaats = [show.zaal, show.stad].filter(Boolean).join(", ");
        var regel = document.createElement("li");
        regel.textContent = datum + ": " + plaats + (show.artiest ? " (" + show.artiest + ")" : "");
        lijst.appendChild(regel);
      });
    })
    .catch(function () {
      lijst.textContent = "De showlijst kon niet worden geladen.";
    });
</script>

Alles ophalen met paginering

Vraag telkens een pagina en verhoog vanaf met limiet, tot een antwoord minder rijen heeft dan de limiet. De volgorde is vast (op begintijd en dan id), dus een pagina komt niet dubbel of overgeslagen terug zolang er niets verandert tijdens het ophalen. Dit werkt voor shows, agenda, contacten en facturen.

// Node 18 of nieuwer. Haalt alle shows op, 500 per keer.
const SLEUTEL = process.env.UB_SLEUTEL; // ub_live_...
const LIMIET = 500;

async function haalAlleShows() {
  const alles = [];
  let vanaf = 0;

  while (true) {
    const adres = "https://ultimate-bookings.com/api/v1/shows?limiet=" + LIMIET + "&vanaf=" + vanaf;
    const antwoord = await fetch(adres, { headers: { Authorization: "Bearer " + SLEUTEL } });

    if (antwoord.status === 429) {
      const wacht = Number(antwoord.headers.get("Retry-After")) || 60;
      await new Promise((klaar) => setTimeout(klaar, wacht * 1000));
      continue; // dezelfde pagina nog een keer
    }
    if (!antwoord.ok) {
      const { error } = await antwoord.json();
      throw new Error(error.code + ": " + error.message);
    }

    const { data, meta } = await antwoord.json();
    alles.push(...data);
    if (meta.aantal < LIMIET) return alles; // laatste pagina
    vanaf += LIMIET;
  }
}

Wat het (nog) niet kan

• Niets schrijven, aanpassen of verwijderen: de API is alleen lezen.
• Geen bestanden: geen contracten, PDF's, riders of bijlagen.
• Geen gedeelde shows van andere organisaties. Je ziet alleen wat van jouw organisatie is.