Viventii
Evenementen zoekenRelease Radar
InloggenRegistreren
Viventii
Viventii Logo

Ontdek lokale evenementen, concerten, workshops en meer met Viventii.

Ontdekken

Alle steden bekijken

Categorieën

Partys & clubbingMuziek & festivalsBeurzen & kermissenShopping & marktenBars & restaurantsFamilie & kinderenAlle categorieën bekijken

Bedrijf

Jobs & carrièreFAQSupport & contactPromoties & Aanbiedingen

Ontdek het nachtleven of plan je eigen privé-highlights. Of het nu een groot concert is of een gezellige spelletjesavond met vrienden – Viventii brengt alles samen.

ColofonPrivacybeleidGebruiksvoorwaardenCookiebeleidGegevensbronnen en licenties

© ... Viventii UG (haftungsbeschränkt). Alle rechten voorbehouden.

OntdekKaartRadarTickets
OntdekKaartRadarTickets

Ontwikkelaar-documentatie

Volledige referentie voor de Viventii-Organizer-API.

OpenAPI-specificatie downloaden

Viventii API – Volledige Documentatie (A-Z)

Deze documentatie beschrijft elke functie, elk endpoint en elke integratiemogelijkheid van de Viventii API – zonder afkortingen.

Base URL: https://viventii.com/api/v1/organizer

🚀 0. Snelstart: Interactieve Code-Generator

Gebruik onze interactieve tool om direct bruikbare code voor jouw systeem te genereren. Voer gewoon je API-key en een naam voor je systeem in – onze Universal Sync regelt de rest automatisch.


🔐 1. Authenticatie & API-keys

Wat is een API-key?

Een API-key is een geheime sleutel waarmee jouw systeem namens jouw Viventii-account kan handelen. Formaat: sk_live_a1b2c3d4e5f6...

Hoe krijg je een API-key?

  1. Open je Viventii Dashboard
  2. Ga naar Profiel → Developer
  3. Klik op "API-key aanmaken"
  4. Kies een Naam en Machtigingen (Scopes)
  5. De sleutel wordt eenmalig getoond – bewaar deze direct veilig!

Scopes (Machtigingen)

ScopeRechtenWanneer gebruiken?
readGegevens lezenIdeaal voor widgets, statistieken of backup-systemen.
writeGegevens aanmaken & wijzigenNodig voor CMS-sync (WordPress/Shopify) en toegangs-apps.
adminVolledige toegangAlleen gebruiken voor interne tools of teambeheersystemen.

Authenticatie-flow

  1. Verzoek: Jouw server stuurt een HTTP-request naar Viventii.
  2. Header: Je voegt de header Authorization: Bearer sk_live_... toe.
  3. Validatie: Viventii controleert de sleutel en jouw machtigingen (Scopes).
  4. Identificatie: Viventii wijst het verzoek toe aan jouw organisatie.
  5. Antwoord: Je ontvangt de gegevens (200 OK) of een foutmelding (401 Unauthorized).

Veiligheids-Best-Practices

  • Nooit in de frontend gebruiken: Een API-key hoort in de backend (Node.js, PHP, Python). Deze mag nooit in de JavaScript-code van een website staan (gevaar voor diefstal!).
  • Twee-Sleutel-Principe: Gebruik aparte keys voor verschillende systemen (bijv. één key voor WordPress, één voor de scanner-app). Als een systeem gecompromitteerd wordt, hoef je maar één key in te trekken.
  • Rotatie: Vernieuw je keys elke 6-12 maanden.

Alternatief: Firebase ID Token

Mobiele apps (iOS/Android) kunnen in plaats van een API-key een Firebase ID Token van de ingelogde gebruiker sturen. Viventii herkent de gebruiker automatisch en verleent de juiste rechten.

⚠️ De sleutel wordt maar ÉÉN KEER getoond!


🧪 2. Sandbox-modus (Test vs. Live)

Viventii scheidt testgegevens strikt van echte live-gegevens. Zo voorkom je dat test-events per ongeluk zichtbaar worden voor klanten.

Vergelijking: Live vs. Test

FeatureLive-modus (sk_live_...)Test-modus (sk_test_...)
ZichtbaarheidOpenbaar op ViventiiAlleen voor jou (Draft/Privé)
BrandingNormale titelKrijgt automatisch [TEST] in de titel
WebhooksEchte webhooksTest-webhooks (voor ontwikkeling)
GeldigheidJuridisch bindendPuur gesimuleerde gegevens

Ideale Workflow voor Ontwikkelaars

  1. Test-key: Maak een test-key (isTest: true) aan in het Dashboard.
  2. Ontwikkeling: Integreer de API en stuur test-events naar Viventii.
  3. Validatie: Controleer in het Dashboard onder "Test-events" of alle velden correct binnenkomen.
  4. Live gaan: Maak een live-key aan zodra je tests succesvol zijn.
  5. Omschakeling: Wijzig de omgevingsvariabele van je server naar de live-key.

💡 Live-keys kunnen geen test-events lezen/schrijven en vice versa.


📝 3. Events – Aanmaken (POST /events)

Scope: write

Wanneer heb je dit endpoint nodig?

Elke keer dat er in jouw bronsysteem (CMS, website, database) een nieuw event wordt aangemaakt. Dit is het startpunt voor de automatische sync.

Het Synchronisatie-proces (Universal Sync)

Viventii gebruikt een "Upsert"-principe (Update or Insert). Je hoeft geen Viventii-ID's in jouw database op te slaan.

  • Stap 1: Jouw systeem stuurt POST /events mit een sourceId (bijv. jouw WordPress Post-ID).
  • Stap 2: Viventii controleert: "Ken ik deze sourceId van deze organisator al?"
    • Nee: Er wordt een nieuw event aangemaakt.
    • Ja: Het bestaande event wordt bijgewerkt met de nieuwe gegevens.
  • Stap 3 (Achtergrond):
    • 📍 Geocoding: Het adres wordt omgezet in coördinaten voor de kaart.
    • 🌐 AI-vertaling: De teksten worden automatisch vertaald naar 6 talen.
    • 🔗 SEO: Er wordt een leesbare link (slug) gegenereerd.
    • 🖼️ Asset-flow: Jouw afbeelding wordt geoptimaliseerd en geüpload naar het CDN.
  • Stap 4: Je ontvangt een bevestiging (action: "created" of "updated").

Belangrijke Velden & Details

VeldBetekenisPraktijktip
sourceIdJOUW IDDe ID uit jouw bronsysteem (bijv. wp-123). Belangrijk voor auto-sync!
name_sourceDe titelGebruik hier de originele titel van jouw systeem.
description_sourceDe beschrijvingEenvoudige HTML toegestaan (p, br, strong).
externalTicketStatsLive-verkoopStuur hier direct actuele verkoopcijfers (Sold/Capacity) mee!
imageDataUriDe titelafbeeldingStuur hier de hoofdafbeelding als Base64-string.
galleryImagesFotogalerijEen array van objecten (URL of Base64) voor extra afbeeldingen.
seriesIdTour/SerieGebruik dezelfde ID voor alle events van een tour.
capacityCapaciteitBelangrijk voor de "Bijna uitverkocht" berekening.

🛠️ Field Mapping & Schema (BELANGRIJK)

De Viventii-API gebruikt een statisch doel-schema. Dit betekent: de veldnamen (keys) die je naar ons stuurt (bijv. name_source), moeten altijd exact zo benoemd zijn als in deze documentatie beschreven.

Hoe werkt de mapping? Jouw systeem (bijv. WordPress) heeft eigen veldnamen. Je moet deze in jouw code "vertalen" naar onze namen:

Jouw Veld (Voorbeeld)Viventii Doelveld
$post->post_titlename_source
$meta['location']location
$event['start']date / time

Waar vindt de mapping plaats? De mapping vindt plaats in jouw systeem (bijv. in un cronjob, een sync-script of middleware). Voordat je het POST-verzoek naar Viventii stuurt, wijs je jouw lokale variabelen toe aan de Viventii-keys.

🔌 WordPress Speciale Tip

Als je WordPress gebruikt, vindt de mapping meestal plaats in de functions.php van je theme of in een eigen plugin. Een beproefd patroon is het gebruik van de save_post hook.

Het Brug-principe (Belangrijk om te begrijpen) Velen vragen: 'Hoe weet Viventii welk veld in mijn systeem wat betekent?'

Het antwoord: Viventii weet het niet. Viventii is een passieve ontvanger (het doel). Jouw systeem is de actieve afzender (de bron).

  1. Jouw Verantwoordelijkheid: Je schrijft een klein script (de brug) dat gegevens uit jouw database opvraagt.
  2. The Mapping: Je beslist in dit script welke waarde in welk Viventii-veld vloeit.
  3. The Push: Jouw script 'drukt' (POST) de volledig vertaalde gegevens naar ons.
// Voorbeeld voor de 'vertaling' in WordPress functions.php: add_action('save_post', function($post_id) { // Stap A: Jouw interne gegevens ophalen $mijn_interne_titel = get_the_title($post_id); $mijn_intern_adres = get_post_meta($post_id, 'wp_field_address', true); // Stap B: Mapping (Je wijst jouw waarde toe aan onze key) $payload = [ 'name_source' => $mijn_interne_titel, // Vertaling: WP-Title -> Viventii-Key 'location' => $mijn_intern_adres, // Vertaling: WP-Meta -> Viventii-Key 'sourceId' => 'wp-' . $post_id ]; // Stap C: Verzenden naar Viventii wp_remote_post('https://api.viventii.com/v1/organizer/events', ['body' => json_encode($payload)]); }, 10, 1);

🚀 Vooruitblik: Viventii Connect (No-Code)

We werken momenteel aan Viventii Connect, een gespecialiseerde WordPress-plugin.

  • Upload & Go: Geen code meer bewerken.
  • Gevisualiseerde Mapping: Je kiest in een lijst simpelweg: 'Veld X uit mijn theme' -> 'Feld Y in Viventii'.
  • Auto-Health: De plugin waarschuwt je als een sync mislukt.

Als je de bètaversie wilt testen, neem dan contact op met onze support!


📚 De Volledige Velden-referentie (60+ velden)

Om het volledige potentieel van de Viventii-AI te benutten, stuur je zoveel mogelijk details mee. De AI gebruikt deze feiten om automatisch SEO-geoptimaliseerde beschrijvingen in 6 talen te schrijven.

A. Kern-metagegevens (Infrastructuur)

VeldTypeVerplichtBeschrijving
sourceIdString✅Jouw ID. Voorkomt duplicaten bij auto-sync (bijv. wp-123).
source_systemStringNeeNaam van jouw systeem (bijv. "Webshop 1").
name_sourceString✅De originele titel van jouw event.
description_sourceString✅De originele beschrijving (HTML toegestaan).
dateString✅Datum in formaat YYYY-MM-DD.
timeString✅Starttijd in formaat HH:MM.
slugStringNeeJouw gewenste permalink (Viventii genereert er anders één).
seriesIdStringNeeID van een event-serie of tournee.
organizationIdStringNeeID van jouw organisator/locatie (voor groepen).

B. Locatie & Adres

VeldTypeVerplichtBeschrijving
locationString✅Naam van de locatie (bijv. "Olympiastadion").
streetString✅Straat en huisnummer.
cityString✅Stad.
zipStringNeePostcode.
countryStringNeeLand (standaard: DE).
lat / lngNumberNeeHandmatige coördinaten (anders via auto-geocoding).

C. Toegankelijkheid

VeldTypeBeschrijving
isWheelchairAccessibleBooleanIs de locatie rolstoeltoegankelijk?
hasAccessibleRestroomsBooleanZijn er drempelvrije toiletten?
allowsServiceAnimalsBooleanZijn hulphonden welkom?
hasSignLanguageBooleanWordt het event vertaald in gebarentaal?
hasAutomaticDoorsBooleanZijn er automatische deuren/ingangen?
accessibilityNotes_sourceStringTekstuele details over de toegankelijkheid (bijv. "Oprit bij de achteringang").

D. Gastronomie & Etablissementen

VeldTypeBeschrijving
venueTypesArrayTypen: restaurant, cafe, bakery, ice_cream, cocktail_bar, wine_bar, beer_garden, pub, club, bistro, food_truck, fast_food, fine_dining_restaurant.
cuisineTypesArrayKeukens: german, italian, french, spanish, greek, turkish, asian, japanese, chinese, thai, indian, mexican, american, mediterranean, middle_eastern, vegetarian_vegan, seafood, steakhouse, pizza, burger, sushi, tapas, fusion, international, other.
dietaryOptionsArrayOpties: vegetarian, vegan, gluten_free, lactose_free, halal, kosher, organic, low_carb.
serviceOptionsArrayService: dine_in, takeaway, delivery, reservations, private_events, catering, brunch, happy_hour, outdoor_seating, live_music, sports_tv, air_conditioning, pets_allowed, smoking_area, rooftop, garden, fireplace.
atmosphereTypesArraySfeer: casual, cozy, romantic, family_friendly, trendy, upscale_elegant, rustic, modern, traditional, lively, quiet, business.
paymentMethodsArrayBetaling: cash, credit_card, debit_card, mobile_payment, voucher.
reservationUrlURLDirecte link naar het reserveringssysteem van het restaurant.
priceRangeEnumPrijsklasse: budget (€), moderate (€€), upscale (€€€), fine_dining (€€€€).

E. Logistiek & Weer

VeldTypeBeschrijving
publicTransportInfo_sourceStringDetails over de bereikbaarheid met bus/trein.
parkingInfo_sourceStringWaar kan men parkeren? (Parkeergarage, parkeerplaats, kosten).
isWeatherDependentBooleanVindt het event alleen plaats bij mooi weer?
weatherNotes_sourceStringWat gebeurt er bij regen? (Overdekt, indoor-optie).

F. Programma & Lineup

VeldTypeBeschrijving
lineupArrayLijst van acts: [{ "name": "Artiest A", "role": "Main" }].
scheduleArrayTijdschema: [{ "time": "20:00", "title": "Start show" }].
doorsOpenTimeStringInlooptijd (formaat HH:MM).
presaleInfo_sourceStringInformatie over de voorverkoop (bijv. "Early Bird tot mei").

G. Marketing & Social Media

VeldTypeBeschrijving
facebookUrlURLLink naar Facebook-pagina of event.
instagramUrlURLLink naar Instagram-profiel.
twitterUrlURLLink naar Twitter/X profiel.
tiktokUrlURLLink naar TikTok profiel.
youtubeUrlURLLink naar een trailer of kanaal.
linkedinUrlURLLink voor business-events.
websiteUrlURLOfficiële event-website.
trackingPixelsObjectID's: facebook, google, tiktok, linkedin, snapchat.
specialOffers_sourceStringBeschrijving van aanbiedingen (bijv. "2-voor-1 drankjes").

H. Tickets & Statistieken

VeldTypeBeschrijving
ticketUrlURLLink naar de ticketshop (verschijnt als knop).
externalTicketStatsObjectLIVE-sync: source, totalSold, totalCapacity.
capacityNumberTotale capaciteit van het event.
priceNote_sourceStringTekstuele prijsinfo (bijv. "Vanaf 15€ voor scholieren").

I. Media & Galerie

VeldTypeBeschrijving
imageDataUriDataURIJouw hoofdafbeelding als Base64 (JPG/PNG).
galleryImagesArrayVerdere impressies: [{ "url": "...", "caption": "..." }].

📋 4. Events – Lijst (GET /events)

Scope: read — Ideaal voor het synchroniseren van jouw lokale voorraad met Viventii.

Filter-mogelijkheden

ParameterFunctie
limitBeperkt het aantal (Standaard: 20)
offsetVoor paginering (Pagina 1, 2, 3...)
organizationIdFiltert op een specifieke organisatie

📄 5. Event ophalen (GET /events/:id)

Scope: read — Geeft het volledige record terug, inclusief alle AI-gegenereerde vertalingen en coördinaten.


✏️ 6. Event bijwerken (PATCH /events/:id)

Scope: write — Stuur alleen de velden op die daadwerkelijk zijn gewijzigd.


🗑️ 7. Event verwijderen (DELETE /events/:id)

Scope: write — Verwijdert het event and alle media permanent van het CDN.


🔄 8. Event-status wijzigen (POST /events/:id/status)

Scope: write — Regelt de zichtbaarheid en informeert klanten.

Status-overzicht

StatusEffect
activeOpenbaar zichtbaar, tickets kunnen worden verkocht.
cancelledEvent wordt gemarkeerd als "Geannuleerd". Webhook wordt geactiveerd.
postponedGemarkeerd als "Uitgesteld".
draftAlleen voor jou zichtbaar. Standaard voor test-events.

🎟️ 9. Ticket-verkoopcijfers (POST /events/:id/tickets/stats)

Scope: write — Het belangrijkste onderdeel voor het "Live-gevoel" op Viventii.


👥 10. Deelnemerslijsten syncen (POST /events/:id/tickets/attendees)

Scope: write — Draag jouw kopersgegevens over naar Viventii voor de toegang.


✅ 11. Check-in / Toegangscontrole (POST /events/:id/tickets/validate)

Scope: write — Als je eigen scanner-apps of NFC-terminals gebruikt.


📥 12. Gastenlijst exporteren (GET /events/:id/tickets/export)

Scope: read — Ideaal voor offline-scanners of rapportages.


📊 13. Toegang-statistieken Live (GET /events/:id/stats/entry)

Scope: read — Voor live-dashboards op de evenementlocatie.


📈 14. Unified Ticket View (GET /events/:id/tickets)

Scope: read — Combineert alle verkoopgegevens uit verschillende bronnen.


📦 15. Inventario & Contingenten (PATCH /events/:id/inventory)

Scope: write — Beheer ticket-contingenten per kanaal of categorie.


🔗 16. Webhooks – Registreren & Beheren

Wat zijn Webhooks?

Webhooks zijn automatische meldingen die Viventii naar jouw systeem stuurt.

EventWanneer wordt het geactiveerd?
event.createdNieuw event aangemaakt
event.updatedEvent-gegevens gewijzigd
event.status_changedAnnulering, uitstel, publicatie
event.ticket_soldTicket via Viventii verkocht
event.attendee_addedNieuwe deelnemer toegevoegd

💳 17. Finance – Facturen & Facturering

Scope: read — Haalt alle Stripe-facturen van jouw Viventii-account op.


📣 18. Audience Sync – Marketing-doelgroepen

Scope: read — Exporteert e-mailhashes voor Custom Audiences (Facebook, Google, etc.).


🛠️ 19. Support & Hulp

Heb je vragen over de integratie? Ons tech-team helpt je graag verder.

  • E-mail: support@viventii.com
  • Web: Support & Contact

Veel succes met je integratie!