Volledige referentie voor de Viventii-Organizer-API.
Deze documentatie beschrijft elke functie, elk endpoint en elke integratiemogelijkheid van de Viventii API – zonder afkortingen.
Base URL: https://viventii.com/api/v1/organizer
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.
Een API-key is een geheime sleutel waarmee jouw systeem namens jouw Viventii-account kan handelen. Formaat: sk_live_a1b2c3d4e5f6...
| Scope | Rechten | Wanneer gebruiken? |
|---|---|---|
read | Gegevens lezen | Ideaal voor widgets, statistieken of backup-systemen. |
write | Gegevens aanmaken & wijzigen | Nodig voor CMS-sync (WordPress/Shopify) en toegangs-apps. |
admin | Volledige toegang | Alleen gebruiken voor interne tools of teambeheersystemen. |
Authorization: Bearer sk_live_... toe.200 OK) of een foutmelding (401 Unauthorized).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!
Viventii scheidt testgegevens strikt van echte live-gegevens. Zo voorkom je dat test-events per ongeluk zichtbaar worden voor klanten.
| Feature | Live-modus (sk_live_...) | Test-modus (sk_test_...) |
|---|---|---|
| Zichtbaarheid | Openbaar op Viventii | Alleen voor jou (Draft/Privé) |
| Branding | Normale titel | Krijgt automatisch [TEST] in de titel |
| Webhooks | Echte webhooks | Test-webhooks (voor ontwikkeling) |
| Geldigheid | Juridisch bindend | Puur gesimuleerde gegevens |
isTest: true) aan in het Dashboard.💡 Live-keys kunnen geen test-events lezen/schrijven en vice versa.
Scope: write
Elke keer dat er in jouw bronsysteem (CMS, website, database) een nieuw event wordt aangemaakt. Dit is het startpunt voor de automatische sync.
Viventii gebruikt een "Upsert"-principe (Update or Insert). Je hoeft geen Viventii-ID's in jouw database op te slaan.
POST /events mit een sourceId (bijv. jouw WordPress Post-ID).sourceId van deze organisator al?"
action: "created" of "updated").| Veld | Betekenis | Praktijktip |
|---|---|---|
sourceId | JOUW ID | De ID uit jouw bronsysteem (bijv. wp-123). Belangrijk voor auto-sync! |
name_source | De titel | Gebruik hier de originele titel van jouw systeem. |
description_source | De beschrijving | Eenvoudige HTML toegestaan (p, br, strong). |
externalTicketStats | Live-verkoop | Stuur hier direct actuele verkoopcijfers (Sold/Capacity) mee! |
imageDataUri | De titelafbeelding | Stuur hier de hoofdafbeelding als Base64-string. |
galleryImages | Fotogalerij | Een array van objecten (URL of Base64) voor extra afbeeldingen. |
seriesId | Tour/Serie | Gebruik dezelfde ID voor alle events van een tour. |
capacity | Capaciteit | Belangrijk voor de "Bijna uitverkocht" berekening. |
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_title | name_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.
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).
// 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);
We werken momenteel aan Viventii Connect, een gespecialiseerde WordPress-plugin.
Als je de bètaversie wilt testen, neem dan contact op met onze support!
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.
| Veld | Type | Verplicht | Beschrijving |
|---|---|---|---|
sourceId | String | ✅ | Jouw ID. Voorkomt duplicaten bij auto-sync (bijv. wp-123). |
source_system | String | Nee | Naam van jouw systeem (bijv. "Webshop 1"). |
name_source | String | ✅ | De originele titel van jouw event. |
description_source | String | ✅ | De originele beschrijving (HTML toegestaan). |
date | String | ✅ | Datum in formaat YYYY-MM-DD. |
time | String | ✅ | Starttijd in formaat HH:MM. |
slug | String | Nee | Jouw gewenste permalink (Viventii genereert er anders één). |
seriesId | String | Nee | ID van een event-serie of tournee. |
organizationId | String | Nee | ID van jouw organisator/locatie (voor groepen). |
| Veld | Type | Verplicht | Beschrijving |
|---|---|---|---|
location | String | ✅ | Naam van de locatie (bijv. "Olympiastadion"). |
street | String | ✅ | Straat en huisnummer. |
city | String | ✅ | Stad. |
zip | String | Nee | Postcode. |
country | String | Nee | Land (standaard: DE). |
lat / lng | Number | Nee | Handmatige coördinaten (anders via auto-geocoding). |
| Veld | Type | Beschrijving |
|---|---|---|
isWheelchairAccessible | Boolean | Is de locatie rolstoeltoegankelijk? |
hasAccessibleRestrooms | Boolean | Zijn er drempelvrije toiletten? |
allowsServiceAnimals | Boolean | Zijn hulphonden welkom? |
hasSignLanguage | Boolean | Wordt het event vertaald in gebarentaal? |
hasAutomaticDoors | Boolean | Zijn er automatische deuren/ingangen? |
accessibilityNotes_source | String | Tekstuele details over de toegankelijkheid (bijv. "Oprit bij de achteringang"). |
| Veld | Type | Beschrijving |
|---|---|---|
venueTypes | Array | Typen: restaurant, cafe, bakery, ice_cream, cocktail_bar, wine_bar, beer_garden, pub, club, bistro, food_truck, fast_food, fine_dining_restaurant. |
cuisineTypes | Array | Keukens: 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. |
dietaryOptions | Array | Opties: vegetarian, vegan, gluten_free, lactose_free, halal, kosher, organic, low_carb. |
serviceOptions | Array | Service: 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. |
atmosphereTypes | Array | Sfeer: casual, cozy, romantic, family_friendly, trendy, upscale_elegant, rustic, modern, traditional, lively, quiet, business. |
paymentMethods | Array | Betaling: cash, credit_card, debit_card, mobile_payment, voucher. |
reservationUrl | URL | Directe link naar het reserveringssysteem van het restaurant. |
priceRange | Enum | Prijsklasse: budget (€), moderate (€€), upscale (€€€), fine_dining (€€€€). |
| Veld | Type | Beschrijving |
|---|---|---|
publicTransportInfo_source | String | Details over de bereikbaarheid met bus/trein. |
parkingInfo_source | String | Waar kan men parkeren? (Parkeergarage, parkeerplaats, kosten). |
isWeatherDependent | Boolean | Vindt het event alleen plaats bij mooi weer? |
weatherNotes_source | String | Wat gebeurt er bij regen? (Overdekt, indoor-optie). |
| Veld | Type | Beschrijving |
|---|---|---|
lineup | Array | Lijst van acts: [{ "name": "Artiest A", "role": "Main" }]. |
schedule | Array | Tijdschema: [{ "time": "20:00", "title": "Start show" }]. |
doorsOpenTime | String | Inlooptijd (formaat HH:MM). |
presaleInfo_source | String | Informatie over de voorverkoop (bijv. "Early Bird tot mei"). |
| Veld | Type | Beschrijving |
|---|---|---|
facebookUrl | URL | Link naar Facebook-pagina of event. |
instagramUrl | URL | Link naar Instagram-profiel. |
twitterUrl | URL | Link naar Twitter/X profiel. |
tiktokUrl | URL | Link naar TikTok profiel. |
youtubeUrl | URL | Link naar een trailer of kanaal. |
linkedinUrl | URL | Link voor business-events. |
websiteUrl | URL | Officiële event-website. |
trackingPixels | Object | ID's: facebook, google, tiktok, linkedin, snapchat. |
specialOffers_source | String | Beschrijving van aanbiedingen (bijv. "2-voor-1 drankjes"). |
| Veld | Type | Beschrijving |
|---|---|---|
ticketUrl | URL | Link naar de ticketshop (verschijnt als knop). |
externalTicketStats | Object | LIVE-sync: source, totalSold, totalCapacity. |
capacity | Number | Totale capaciteit van het event. |
priceNote_source | String | Tekstuele prijsinfo (bijv. "Vanaf 15€ voor scholieren"). |
| Veld | Type | Beschrijving |
|---|---|---|
imageDataUri | DataURI | Jouw hoofdafbeelding als Base64 (JPG/PNG). |
galleryImages | Array | Verdere impressies: [{ "url": "...", "caption": "..." }]. |
Scope: read — Ideaal voor het synchroniseren van jouw lokale voorraad met Viventii.
| Parameter | Functie |
|---|---|
limit | Beperkt het aantal (Standaard: 20) |
offset | Voor paginering (Pagina 1, 2, 3...) |
organizationId | Filtert op een specifieke organisatie |
Scope: read — Geeft het volledige record terug, inclusief alle AI-gegenereerde vertalingen en coördinaten.
Scope: write — Stuur alleen de velden op die daadwerkelijk zijn gewijzigd.
Scope: write — Verwijdert het event and alle media permanent van het CDN.
Scope: write — Regelt de zichtbaarheid en informeert klanten.
| Status | Effect |
|---|---|
active | Openbaar zichtbaar, tickets kunnen worden verkocht. |
cancelled | Event wordt gemarkeerd als "Geannuleerd". Webhook wordt geactiveerd. |
postponed | Gemarkeerd als "Uitgesteld". |
draft | Alleen voor jou zichtbaar. Standaard voor test-events. |
Scope: write — Het belangrijkste onderdeel voor het "Live-gevoel" op Viventii.
Scope: write — Draag jouw kopersgegevens over naar Viventii voor de toegang.
Scope: write — Als je eigen scanner-apps of NFC-terminals gebruikt.
Scope: read — Ideaal voor offline-scanners of rapportages.
Scope: read — Voor live-dashboards op de evenementlocatie.
Scope: read — Combineert alle verkoopgegevens uit verschillende bronnen.
Scope: write — Beheer ticket-contingenten per kanaal of categorie.
Webhooks zijn automatische meldingen die Viventii naar jouw systeem stuurt.
| Event | Wanneer wordt het geactiveerd? |
|---|---|
event.created | Nieuw event aangemaakt |
event.updated | Event-gegevens gewijzigd |
event.status_changed | Annulering, uitstel, publicatie |
event.ticket_sold | Ticket via Viventii verkocht |
event.attendee_added | Nieuwe deelnemer toegevoegd |
Scope: read — Haalt alle Stripe-facturen van jouw Viventii-account op.
Scope: read — Exporteert e-mailhashes voor Custom Audiences (Facebook, Google, etc.).
Heb je vragen over de integratie? Ons tech-team helpt je graag verder.
Veel succes met je integratie!