Viventii
Events SuchenRelease-Radar
AnmeldenRegistrieren
Viventii
Viventii Logo

Entdecke lokale Events, Konzerte, Workshops und mehr mit Viventii.

Entdecken

Alle Städte ansehen

Kategorien

Partys & ClubbingMusik & FestivalsMessen & JahrmärkteShopping & MärkteBars & RestaurantsFamilie & KinderAlle Kategorien ansehen

Unternehmen

Jobs & KarriereFAQSupport & KontaktAktionen & Angebote

Entdecke das Nachtleben oder plane deine eigenen privaten Highlights. Ob großes Konzert oder gemütlicher Spieleabend mit Freunden – Viventii bringt alles zusammen.

ImpressumDatenschutzrichtlinieNutzungsbedingungenCookie-RichtlinieDatenquellen & Lizenzen

© ... Viventii UG (haftungsbeschränkt). Alle Rechte vorbehalten.

EntdeckenKarteRadarTickets
EntdeckenKarteRadarTickets

Entwickler-Dokumentation

Vollständige Referenz für die Viventii-Organizer-API.

OpenAPI-Spezifikation herunterladen

Viventii API – Vollständige Dokumentation (A-Z)

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

🚀 0. Schnellstart: Interactive Code-Generator

🚀
Interaktiver Code-Generator
Generiere sofort einsatzbereiten Code für deine Integration.

Gapless Sync

Aktiviere "Alle Optionen wählen", um eine lückenlose Synchronisierung deiner Events inklusive aller Detail-Features sicherzustellen.
/**
 * 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.


🔐 1. Authentifizierung & API-Keys

Was ist ein API-Key?

Ein API-Key ist ein geheimer Schlüssel, der deinem System erlaubt, im Namen deines Viventii-Kontos zu handeln. Format: sk_live_a1b2c3d4e5f6...

Wie bekommt man einen API-Key?

  1. Öffne dein Viventii Dashboard
  2. Gehe zu Profil → Developer
  3. Klicke auf "API-Key erstellen"
  4. Wähle Name und Berechtigungen (Scopes)
  5. Der Schlüssel wird einmalig angezeigt – sofort sicher speichern!

Scopes (Berechtigungen)

ScopeRechteWann nutzen?
readDaten lesenIdeal für Widgets, Statistiken oder Backup-Systeme.
writeDaten erstellen & ändernNötig für CMS-Sync (WordPress/Shopify) und Einlass-Apps.
adminVoller ZugriffNur für interne Tools oder Team-Verwaltungssysteme nutzen.

Authentifizierungs-Flow

  1. Anfrage: Dein Server sendet einen HTTP-Request an Viventii.
  2. Header: Du fügst den Header Authorization: Bearer sk_live_... hinzu.
  3. Validierung: Viventii prüft den Schlüssel und deine Berechtigungen (Scopes).
  4. Identifikation: Viventii ordnet die Anfrage deiner Organisation zu.
  5. Antwort: Du erhältst die Daten (200 OK) oder eine Fehlermeldung (401 Unauthorized).

Sicherheits-Best-Practices

  • Niemals im Frontend nutzen: Ein API-Key gehört in das Backend (Node.js, PHP, Python). Er darf niemals im JavaScript-Code einer Website stehen (Gefahr des Diebstahls!).
  • Zwei-Schlüssel-Prinzip: Nutze separate Keys für verschiedene Systeme (z.B. ein Key für WordPress, einer für die Scanner-App). Wenn ein System kompromittiert wird, musst du nur einen Key sperren.
  • Rotation: Erneuere deine Keys alle 6-12 Monate.

Alternativ: Firebase ID Token

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!


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

Viventii trennt strikt zwischen Test-Daten und echten Live-Daten. So verhinderst du, dass Test-Events versehentlich für Kunden sichtbar werden.

Vergleich: Live vs. Test

FeatureLive-Modus (sk_live_...)Test-Modus (sk_test_...)
SichtbarkeitÖffentlich auf ViventiiNur für dich (Draft/Privat)
BrandingNormaler TitelBekommt automatisch [TEST] im Titel
WebhooksEchte WebhooksTest-Webhooks (für Entwicklung)
GültigkeitRechtlich verbindlichRein simulierte Daten

Best-Case Workflow für Entwickler

  1. Test-Key: Erstelle einen Test-Key (isTest: true) im Dashboard.
  2. Entwicklung: Integriere die API und sende Test-Events zu Viventii.
  3. Validierung: Prüfe im Dashboard unter "Test-Events", ob alle Felder korrekt ankommen.
  4. Live-Gang: Erstelle einen Live-Key, sobald deine Tests erfolgreich sind.
  5. Umstellung: Ändere die Umgebungsvariable deines Servers auf den Live-Key.

💡 Live-Keys können keine Test-Events lesen/schreiben und umgekehrt.


📝 3. Events – Erstellen (POST /events)

Scope: write

Wann brauchst du diesen Endpoint?

Jedes Mal, wenn in deinem Quellsystem (CMS, Website, Datenbank) ein neues Event angelegt wird. Dies ist der Startpunkt für den automatischen Sync.

Der Synchronisations-Prozess (Universal Sync)

Viventii nutzt ein "Upsert"-Prinzip (Update or Insert). Du musst keine Viventii-IDs in deiner Datenbank speichern.

  • Schritt 1: Dein System sendet POST /events mit einer sourceId (z.B. deine WordPress Post-ID).
  • Schritt 2: Viventii prüft: "Kenne ich diese sourceId von diesem Veranstalter bereits?"
    • Nein: Ein neues Event wird erstellt.
    • Ja: Das bestehende Event wird mit den neuen Daten aktualisiert.
  • Schritt 3 (Hintergrund):
    • 📍 Geocoding: Die Adresse wird in Koordinaten für die Karte umgewandelt.
    • 🌐 AI-Übersetzung: Die Texte werden automatisch in 6 Sprachen übersetzt.
    • 🔗 SEO: Ein sprechender Link (Slug) wird generiert.
    • 🖼️ Asset-Flow: Dein Bild wird optimiert und auf das CDN hochgeladen.
  • Schritt 4: Du erhältst die Bestätigung (action: "created" oder "updated").

Wichtige Felder & Details

FeldBedeutungPraxis-Tipp
sourceIdDEINE IDDie ID aus deinem Quellsystem (z.B. wp-123). Wichtig für Auto-Sync!
name_sourceDer TitelNutze hier den Original-Titel deines Systems.
description_sourceDie BeschreibungErlaubt einfaches HTML (p, br, strong).
externalTicketStatsLive-VerkäufeSende hier aktuelle Sales-Zahlen (Sold/Capacity) direkt mit!
imageDataUriDas TitelbildSende hier das Hauptbild als Base64-String.
galleryImagesBildergalerieEin Array von Objekten (URL oder Base64) für zusätzliche Bilder.
seriesIdTour/SerieNutze dieselbe ID für alle Events einer Tour.
capacityKapazitätWichtig für die "Fast ausverkauft" Berechnung.

🛠️ Field Mapping & Schema (WICHTIG)

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_titlename_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.

🔌 WordPress Spezial-Tipp

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).

  1. Deine Verantwortung: Du schreibst ein kleines Script (die Brücke), das Daten aus deiner Datenbank abfragt.
  2. Das Mapping: Du entscheidest in diesem Script, welcher Wert in welches Viventii-Feld fließt.
  3. Der Push: Dein Script 'drückt' (POST) die fertig übersetzten Daten an uns.
// 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);

🚀 Ausblick: Viventii Connect (No-Code)

Wir arbeiten aktuell an Viventii Connect, einem spezialisierten WordPress-Plugin.

  • Upload & Go: Kein Code-Editieren mehr nötig.
  • Visual Mapping: Du wählst in einer Liste einfach aus: 'Feld X aus meinem Theme' -> 'Feld Y in Viventii'.
  • Auto-Health: Das Plugin warnt dich, wenn ein Sync fehlschlägt.

Wenn du die Beta-Version testen möchtest, kontaktiere unseren Support!


📚 Die vollständige Feld-Referenz (60+ Felder)

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.

A. Kern-Metadaten (Infrastruktur)

FeldTypPflichtBeschreibung
sourceIdString✅Deine ID. Verhindert Duplikate beim Auto-Sync (z.B. wp-123).
source_systemStringNeinName deines Systems (z.B. "Webshop 1").
name_sourceString✅Der Originaltitel deines Events.
description_sourceString✅Die Originalbeschreibung (HTML erlaubt).
dateString✅Datum im Format YYYY-MM-DD.
timeString✅Startzeit im Format HH:MM.
slugStringNeinDein Wunsch-Permalink (Viventii generiert sonst einen).
seriesIdStringNeinID einer Event-Serie oder Tournee.
organizationIdStringNeinID deines Veranstalters/Locations (für Gruppen).

B. Location & Adresse

FeldTypPflichtBeschreibung
locationString✅Name des Veranstaltungsortes (z.B. "Olympiastadion").
streetString✅Straße und Hausnummer.
cityString✅Stadt.
zipStringNeinPostleitzahl.
countryStringNeinLand (Standard: DE).
lat / lngNumberNeinManuelle Koordinaten (sonst via Auto-Geocoding).

C. Barrierefreiheit (Accessibility)

FeldTypBeschreibung
isWheelchairAccessibleBooleanIst die Location rollstuhlgerecht?
hasAccessibleRestroomsBooleanGibt es barrierefreie WCs?
allowsServiceAnimalsBooleanSind Assistenzhunde willkommen?
hasSignLanguageBooleanWird das Event in Gebärdensprache übersetzt?
hasAutomaticDoorsBooleanGibt es elektrische Türen/Eingänge?
accessibilityNotes_sourceStringTextliche Details zur Barrierefreiheit (z.B. "Rampe am Hintereingang").

D. Gastronomie & Etablissements

FeldTypBeschreibung
venueTypesArrayTypen: restaurant, cafe, bakery, ice_cream, cocktail_bar, wine_bar, beer_garden, pub, club, bistro, food_truck, fast_food, fine_dining_restaurant.
cuisineTypesArrayKü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.
dietaryOptionsArrayOptionen: 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.
atmosphereTypesArrayAmbiente: casual, cozy, romantic, family_friendly, trendy, upscale_elegant, rustic, modern, traditional, lively, quiet, business.
paymentMethodsArrayZahlung: cash, credit_card, debit_card, mobile_payment, voucher.
reservationUrlURLDirektlink zum Buchungssystem des Restaurants.
priceRangeEnumPreisklasse: budget (€), moderate (€€), upscale (€€€), fine_dining (€€€€).

E. Logistik & Wetter

FeldTypBeschreibung
publicTransportInfo_sourceStringDetails zur Anreise mit Bus/Bahn.
parkingInfo_sourceStringWo kann man parken? (Tiefgarage, Parkplatz, Kosten).
isWeatherDependentBooleanFindet das Event nur bei Sonnenschein statt?
weatherNotes_sourceStringWas passiert bei Regen? (Überdacht, Indoor-Option).

F. Programm & Lineup

FeldTypBeschreibung
lineupArrayListe der Acts: [{ "name": "Artist A", "role": "Main" }].
scheduleArrayTimetable: [{ "time": "20:00", "title": "Showstart" }].
doorsOpenTimeStringEinlasszeit (Format HH:MM).
presaleInfo_sourceStringInfos zum Vorverkauf (z.B. "Early Bird bis Mai").

G. Marketing & Social Media

FeldTypBeschreibung
facebookUrlURLLink zur Facebook-Seite oder zum Event.
instagramUrlURLLink zum Instagram-Profil.
twitterUrlURLLink zum Twitter/X Profil.
tiktokUrlURLLink zum TikTok Profil.
youtubeUrlURLLink zu einem Trailer oder Channel.
linkedinUrlURLLink für Business-Events.
websiteUrlURLOffizielle Event-Website.
trackingPixelsObjectIDs: facebook, google, tiktok, linkedin, snapchat.
specialOffers_sourceStringBeschreibung von Angeboten (z.B. "2-für-1 Drinks").

H. Tickets & Statistiken

FeldTypBeschreibung
ticketUrlURLLink zum Ticketshop (erscheint als Button).
externalTicketStatsObjectLIVE-Sync: source, totalSold, totalCapacity.
capacityNumberGesamte Kapazität des Events.
priceNote_sourceStringTextliche Preisinfo (z.B. "Ab 15€ für Schüler").

I. Medien & Galerie

FeldTypBeschreibung
imageDataUriDataURIDein Hauptbild als Base64 (JPG/PNG).
galleryImagesArrayWeitere Impressionen: [{ "url": "...", "caption": "..." }].

📋 4. Events – Auflisten (GET /events)

Scope: read — Ideal zum Synchronisieren deines lokalen Bestands mit Viventii.

Filter-Möglichkeiten

ParameterFunktion
limitBegrenzt die Anzahl (Standard: 20)
offsetFür Paginierung (Seite 1, 2, 3...)
organizationIdFiltert nach einer bestimmten Organisation

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

Scope: read — Gibt den vollen Datensatz zurück, inklusive aller AI-generierten Übersetzungen und Koordinaten.


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

Scope: write — Nur die Felder senden, die sich wirklich geändert haben.


🗑️ 7. Event löschen (DELETE /events/:id)

Scope: write — Löscht das Event und alle Medien permanent vom CDN.


🔄 8. Event-Status ändern (POST /events/:id/status)

Scope: write — Steuert die Sichtbarkeit und informiert Kunden.

Status-Übersicht

StatusWirkung
activeÖffentlich sichtbar, Tickets können verkauft werden.
cancelledEvent wird als "Abgesagt" markiert. Webhook wird ausgelöst.
postponedMarkiert als "Verschoben".
draftNur für dich sichtbar. Standard für Test-Events.

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

Scope: write — Der wichtigste Part für das "Live-Gefühl" auf Viventii.


👥 10. Teilnehmerlisten sync (POST /events/:id/tickets/attendees)

Scope: write — Übertrage deine Käuferdaten zu Viventii für den Einlass.


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

Scope: write — Wenn du eigene Scanner-Apps oder NFC-Terminals nutzt.


📥 12. Gästeliste exportieren (GET /events/:id/tickets/export)

Scope: read — Ideal für Offline-Scanner oder Reports.


📊 13. Einlass-Statistiken Live (GET /events/:id/stats/entry)

Scope: read — Für Live-Dashboards am Veranstaltungsort.


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

Scope: read — Kombiniert alle Verkaufsdaten aus verschiedenen Quellen.


📦 15. Inventar & Kontingente (PATCH /events/:id/inventory)

Scope: write — Verwalte Ticket-Kontingente pro Kanal oder Kategorie.


🔗 16. Webhooks – Registrieren & Verwalten

Was sind Webhooks?

Webhooks sind automatische Benachrichtigungen, die Viventii an dein System sendet.

EventWann wird es ausgelöst?
event.createdNeues Event erstellt
event.updatedEvent-Daten geändert
event.status_changedAbsage, Verschiebung, Veröffentlichung
event.ticket_soldTicket über Viventii verkauft
event.attendee_addedNeuer Teilnehmer hinzugefügt

💳 17. Finance – Rechnungen & Abrechnung

Scope: read — Ruft alle Stripe-Rechnungen deines Viventii-Kontos ab.


📣 18. Audience Sync – Marketing-Zielgruppen

Scope: read — Exportiert E-Mail-Hashes für Custom Audiences (Facebook, Google, etc.).


🛠️ 19. Support & Hilfe

Hast du Fragen zur Integration? Unser Tech-Team hilft dir gerne weiter.

  • E-Mail: support@viventii.com
  • Web: Support & Kontakt

Viel Erfolg bei deiner Integration!