Vollständige Referenz für die Viventii-Organizer-API.
Diese Dokumentation beschreibt jede Funktion, jeden Endpoint und jede Integrationsmöglichkeit der Viventii API – ohne Abkürzungen.
Base URL: https://viventii.com/api/v1/organizer
Gapless Sync
/**
* Viventii Universal API Sync (Automatic Create/Update)
* Where do I copy this? Into your theme's functions.php.
*/
add_action('save_post_event', function($post_id, $post, $update) {
if (wp_is_post_revision($post_id) || $post->post_status !== 'publish') return;
$api_key = 'sk_live_...';
$url = 'https://viventii.com/api/v1/organizer/events';
$payload = [
'sourceId' => 'wp-post-' . $post_id, // Your local ID
'name_source' => $post->post_title, // WP-Title -> Viventii
'description_source' => wp_strip_all_tags($post->post_content), // WP-Content -> Viventii
'location' => get_post_meta($post_id, '_venue_name', true), // <-- YOUR METAKEY HERE
'street' => get_post_meta($post_id, '_venue_street', true),// <-- YOUR METAKEY HERE
'city' => get_post_meta($post_id, '_venue_city', true), // <-- YOUR METAKEY HERE
'date' => get_post_meta($post_id, '_event_date', true), // YYYY-MM-DD
'time' => get_post_meta($post_id, '_event_time', true), // HH:MM
'source_system' => 'Viventii Integration',
];
wp_remote_request($url, [
'method' => 'POST',
'headers' => [
'Authorization' => 'Bearer ' . $api_key,
'Content-Type' => 'application/json'
],
'body' => json_encode(array_filter($payload, function($v) { return !is_null($v); })),
]);
}, 10, 3);Nutze unser interaktives Tool, um sofort einsatzbereiten Code für dein System zu generieren. Gib einfach deinen API-Key und einen Namen für dein System ein – den Rest erledigt unser Universal Sync automatisch.
Ein API-Key ist ein geheimer Schlüssel, der deinem System erlaubt, im Namen deines Viventii-Kontos zu handeln. Format: sk_live_a1b2c3d4e5f6...
| Scope | Rechte | Wann nutzen? |
|---|---|---|
read | Daten lesen | Ideal für Widgets, Statistiken oder Backup-Systeme. |
write | Daten erstellen & ändern | Nötig für CMS-Sync (WordPress/Shopify) und Einlass-Apps. |
admin | Voller Zugriff | Nur für interne Tools oder Team-Verwaltungssysteme nutzen. |
Authorization: Bearer sk_live_... hinzu.200 OK) oder eine Fehlermeldung (401 Unauthorized).Mobile Apps (iOS/Android) können statt eines API-Keys ein Firebase ID Token des angemeldeten Nutzers senden. Viventii erkennt den Nutzer automatisch und gewährt die passenden Rechte.
⚠️ Der Key wird nur EINMAL angezeigt!
Viventii trennt strikt zwischen Test-Daten und echten Live-Daten. So verhinderst du, dass Test-Events versehentlich für Kunden sichtbar werden.
| Feature | Live-Modus (sk_live_...) | Test-Modus (sk_test_...) |
|---|---|---|
| Sichtbarkeit | Öffentlich auf Viventii | Nur für dich (Draft/Privat) |
| Branding | Normaler Titel | Bekommt automatisch [TEST] im Titel |
| Webhooks | Echte Webhooks | Test-Webhooks (für Entwicklung) |
| Gültigkeit | Rechtlich verbindlich | Rein simulierte Daten |
isTest: true) im Dashboard.💡 Live-Keys können keine Test-Events lesen/schreiben und umgekehrt.
Scope: write
Jedes Mal, wenn in deinem Quellsystem (CMS, Website, Datenbank) ein neues Event angelegt wird. Dies ist der Startpunkt für den automatischen Sync.
Viventii nutzt ein "Upsert"-Prinzip (Update or Insert). Du musst keine Viventii-IDs in deiner Datenbank speichern.
POST /events mit einer sourceId (z.B. deine WordPress Post-ID).sourceId von diesem Veranstalter bereits?"
action: "created" oder "updated").| Feld | Bedeutung | Praxis-Tipp |
|---|---|---|
sourceId | DEINE ID | Die ID aus deinem Quellsystem (z.B. wp-123). Wichtig für Auto-Sync! |
name_source | Der Titel | Nutze hier den Original-Titel deines Systems. |
description_source | Die Beschreibung | Erlaubt einfaches HTML (p, br, strong). |
externalTicketStats | Live-Verkäufe | Sende hier aktuelle Sales-Zahlen (Sold/Capacity) direkt mit! |
imageDataUri | Das Titelbild | Sende hier das Hauptbild als Base64-String. |
galleryImages | Bildergalerie | Ein Array von Objekten (URL oder Base64) für zusätzliche Bilder. |
seriesId | Tour/Serie | Nutze dieselbe ID für alle Events einer Tour. |
capacity | Kapazität | Wichtig für die "Fast ausverkauft" Berechnung. |
Die Viventii-API nutzt ein statisches Ziel-Schema. Das bedeutet: Die Feldnamen (Keys), die du an uns sendest (z.B. name_source), müssen immer exakt so benannt sein, wie in dieser Dokumentation beschrieben.
Wie funktioniert das Mapping? Dein System (z.B. WordPress) hat eigene Feldnamen. Du musst diese in deinem Code auf unsere Namen "übersetzen":
| Dein Feld (Beispiel) | Viventii Ziel-Feld |
|---|---|
$post->post_title | name_source |
$meta['location'] | location |
$event['start'] | date / time |
Wo findet das Mapping statt?
Das Mapping findet in deinem System statt (z.B. in einem Cronjob, einem Sync-Script oder einer Middleware). Bevor du den POST-Request an Viventii abschickst, weist du deine lokalen Variablen den Viventii-Keys zu.
Wenn du WordPress nutzt, findet das Mapping meistens in der functions.php deines Themes oder in einem eigenen Plugin statt. Ein bewährtes Muster ist die Nutzung des save_post Hooks:
Das Brücken-Prinzip (Wichtig zum Verständnis) Viele fragen: 'Woher weiß Viventii, welches Feld in meinem System was bedeutet?'
Die Antwort: Viventii weiß es nicht. Viventii ist ein passiver Empfänger (das Ziel). Dein System ist der aktive Absender (die Quelle).
// Beispiel für die 'Übersetzung' in der WordPress functions.php: add_action('save_post', function($post_id) { // Schritt A: Deine internen Daten holen $mein_interner_titel = get_the_title($post_id); $meine_interne_adresse = get_post_meta($post_id, 'wp_field_address', true); // Schritt B: Mapping (Du weist deinen Wert unserm Key zu) $payload = [ 'name_source' => $mein_interner_titel, // Übersetzung: WP-Titel -> Viventii-Key 'location' => $meine_interne_adresse, // Übersetzung: WP-Meta -> Viventii-Key 'sourceId' => 'wp-' . $post_id ]; // Schritt C: Versenden an Viventii wp_remote_post('https://api.viventii.com/v1/organizer/events', ['body' => json_encode($payload)]); }, 10, 1);
Wir arbeiten aktuell an Viventii Connect, einem spezialisierten WordPress-Plugin.
Wenn du die Beta-Version testen möchtest, kontaktiere unseren Support!
Um das volle Potenzial der Viventii-KI auszuschöpfen, sende so viele Details wie möglich. Die KI nutzt diese Fakten, um automatisch SEO-optimierte Beschreibungen in 6 Sprachen zu schreiben.
| Feld | Typ | Pflicht | Beschreibung |
|---|---|---|---|
sourceId | String | ✅ | Deine ID. Verhindert Duplikate beim Auto-Sync (z.B. wp-123). |
source_system | String | Nein | Name deines Systems (z.B. "Webshop 1"). |
name_source | String | ✅ | Der Originaltitel deines Events. |
description_source | String | ✅ | Die Originalbeschreibung (HTML erlaubt). |
date | String | ✅ | Datum im Format YYYY-MM-DD. |
time | String | ✅ | Startzeit im Format HH:MM. |
slug | String | Nein | Dein Wunsch-Permalink (Viventii generiert sonst einen). |
seriesId | String | Nein | ID einer Event-Serie oder Tournee. |
organizationId | String | Nein | ID deines Veranstalters/Locations (für Gruppen). |
| Feld | Typ | Pflicht | Beschreibung |
|---|---|---|---|
location | String | ✅ | Name des Veranstaltungsortes (z.B. "Olympiastadion"). |
street | String | ✅ | Straße und Hausnummer. |
city | String | ✅ | Stadt. |
zip | String | Nein | Postleitzahl. |
country | String | Nein | Land (Standard: DE). |
lat / lng | Number | Nein | Manuelle Koordinaten (sonst via Auto-Geocoding). |
| Feld | Typ | Beschreibung |
|---|---|---|
isWheelchairAccessible | Boolean | Ist die Location rollstuhlgerecht? |
hasAccessibleRestrooms | Boolean | Gibt es barrierefreie WCs? |
allowsServiceAnimals | Boolean | Sind Assistenzhunde willkommen? |
hasSignLanguage | Boolean | Wird das Event in Gebärdensprache übersetzt? |
hasAutomaticDoors | Boolean | Gibt es elektrische Türen/Eingänge? |
accessibilityNotes_source | String | Textliche Details zur Barrierefreiheit (z.B. "Rampe am Hintereingang"). |
| Feld | Typ | Beschreibung |
|---|---|---|
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 | Küchen: 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 | Optionen: 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 | Ambiente: casual, cozy, romantic, family_friendly, trendy, upscale_elegant, rustic, modern, traditional, lively, quiet, business. |
paymentMethods | Array | Zahlung: cash, credit_card, debit_card, mobile_payment, voucher. |
reservationUrl | URL | Direktlink zum Buchungssystem des Restaurants. |
priceRange | Enum | Preisklasse: budget (€), moderate (€€), upscale (€€€), fine_dining (€€€€). |
| Feld | Typ | Beschreibung |
|---|---|---|
publicTransportInfo_source | String | Details zur Anreise mit Bus/Bahn. |
parkingInfo_source | String | Wo kann man parken? (Tiefgarage, Parkplatz, Kosten). |
isWeatherDependent | Boolean | Findet das Event nur bei Sonnenschein statt? |
weatherNotes_source | String | Was passiert bei Regen? (Überdacht, Indoor-Option). |
| Feld | Typ | Beschreibung |
|---|---|---|
lineup | Array | Liste der Acts: [{ "name": "Artist A", "role": "Main" }]. |
schedule | Array | Timetable: [{ "time": "20:00", "title": "Showstart" }]. |
doorsOpenTime | String | Einlasszeit (Format HH:MM). |
presaleInfo_source | String | Infos zum Vorverkauf (z.B. "Early Bird bis Mai"). |
| Feld | Typ | Beschreibung |
|---|---|---|
facebookUrl | URL | Link zur Facebook-Seite oder zum Event. |
instagramUrl | URL | Link zum Instagram-Profil. |
twitterUrl | URL | Link zum Twitter/X Profil. |
tiktokUrl | URL | Link zum TikTok Profil. |
youtubeUrl | URL | Link zu einem Trailer oder Channel. |
linkedinUrl | URL | Link für Business-Events. |
websiteUrl | URL | Offizielle Event-Website. |
trackingPixels | Object | IDs: facebook, google, tiktok, linkedin, snapchat. |
specialOffers_source | String | Beschreibung von Angeboten (z.B. "2-für-1 Drinks"). |
| Feld | Typ | Beschreibung |
|---|---|---|
ticketUrl | URL | Link zum Ticketshop (erscheint als Button). |
externalTicketStats | Object | LIVE-Sync: source, totalSold, totalCapacity. |
capacity | Number | Gesamte Kapazität des Events. |
priceNote_source | String | Textliche Preisinfo (z.B. "Ab 15€ für Schüler"). |
| Feld | Typ | Beschreibung |
|---|---|---|
imageDataUri | DataURI | Dein Hauptbild als Base64 (JPG/PNG). |
galleryImages | Array | Weitere Impressionen: [{ "url": "...", "caption": "..." }]. |
Scope: read — Ideal zum Synchronisieren deines lokalen Bestands mit Viventii.
| Parameter | Funktion |
|---|---|
limit | Begrenzt die Anzahl (Standard: 20) |
offset | Für Paginierung (Seite 1, 2, 3...) |
organizationId | Filtert nach einer bestimmten Organisation |
Scope: read — Gibt den vollen Datensatz zurück, inklusive aller AI-generierten Übersetzungen und Koordinaten.
Scope: write — Nur die Felder senden, die sich wirklich geändert haben.
Scope: write — Löscht das Event und alle Medien permanent vom CDN.
Scope: write — Steuert die Sichtbarkeit und informiert Kunden.
| Status | Wirkung |
|---|---|
active | Öffentlich sichtbar, Tickets können verkauft werden. |
cancelled | Event wird als "Abgesagt" markiert. Webhook wird ausgelöst. |
postponed | Markiert als "Verschoben". |
draft | Nur für dich sichtbar. Standard für Test-Events. |
Scope: write — Der wichtigste Part für das "Live-Gefühl" auf Viventii.
Scope: write — Übertrage deine Käuferdaten zu Viventii für den Einlass.
Scope: write — Wenn du eigene Scanner-Apps oder NFC-Terminals nutzt.
Scope: read — Ideal für Offline-Scanner oder Reports.
Scope: read — Für Live-Dashboards am Veranstaltungsort.
Scope: read — Kombiniert alle Verkaufsdaten aus verschiedenen Quellen.
Scope: write — Verwalte Ticket-Kontingente pro Kanal oder Kategorie.
Webhooks sind automatische Benachrichtigungen, die Viventii an dein System sendet.
| Event | Wann wird es ausgelöst? |
|---|---|
event.created | Neues Event erstellt |
event.updated | Event-Daten geändert |
event.status_changed | Absage, Verschiebung, Veröffentlichung |
event.ticket_sold | Ticket über Viventii verkauft |
event.attendee_added | Neuer Teilnehmer hinzugefügt |
Scope: read — Ruft alle Stripe-Rechnungen deines Viventii-Kontos ab.
Scope: read — Exportiert E-Mail-Hashes für Custom Audiences (Facebook, Google, etc.).
Hast du Fragen zur Integration? Unser Tech-Team hilft dir gerne weiter.
Viel Erfolg bei deiner Integration!