Riferimento completo per l'API Organizer di Viventii.
Questa documentazione descrive ogni funzione, ogni endpoint e ogni possibilità di integrazione dell'API Viventii – senza scorciatoie.
Base URL: https://viventii.com/api/v1/organizer
Usa il nostro strumento interattivo per generare codice pronto all'uso per il tuo sistema. Inserisci semplicemente la tua chiave API e un nome per il tuo sistema – il nostro Universal Sync si occuperà di tutto il resto automaticamente.
Una chiave API è una chiave segreta che permette al tuo sistema di agire per conto del tuo account Viventii. Formato: sk_live_a1b2c3d4e5f6...
| Scope | Diritti | Quando usarlo? |
|---|---|---|
read | Leggere dati | Ideale per widget, statistiche o sistemi di backup. |
write | Creare e modificare dati | Necessario per la sincronizzazione CMS (WordPress/Shopify) e app di ingresso. |
admin | Accesso completo | Da utilizzare solo per strumenti interni o sistemi di gestione del team. |
Authorization: Bearer sk_live_....200 OK) o un messaggio di errore (401 Unauthorized).Le app mobili (iOS/Android) possono inviare un Firebase ID Token dell'utente connesso invece di una chiave API. Viventii riconosce l'utente automaticamente e concede i diritti appropriati.
⚠️ La chiave viene mostrata solo UNA VOLTA!
Viventii separa rigorosamente i dati di test dai dati reali live. Questo evita che gli eventi di test diventino accidentalmente visibili ai clienti.
| Caratteristica | Modalità Live (sk_live_...) | Modalità Test (sk_test_...) |
|---|---|---|
| Visibilità | Pubblico su Viventii | Solo per te (Draft/Privato) |
| Branding | Titolo normale | Riceve automaticamente [TEST] nel titolo |
| Webhooks | Webhook reali | Webhook di test (per lo sviluppo) |
| Validità | Legalmente vincolante | Dati puramente simulati |
isTest: true) nella Dashboard.💡 Le chiavi live non possono leggere/scrivere eventi di test e viceversa.
Scope: write
Ogni volta che nel tuo sistema sorgente (CMS, sito web, database) viene creato un nuovo evento. Questo è il punto di partenza per la sincronizzazione automatica.
Viventii utilizza un principio di "Upsert" (Update or Insert). Non è necessario memorizzare gli ID Viventii nel tuo database.
POST /events con un sourceId (ad esempio, l'ID del post di WordPress).sourceId per questo organizzatore?"
action: "created" o "updated").| Campo | Significato | Consiglio Pro |
|---|---|---|
sourceId | IL TUO ID | L'ID del tuo sistema sorgente (es. wp-123). Fondamentale per l'auto-sync! |
name_source | Titolo | Usa il titolo originale del tuo sistema. |
description_source | Descrizione | HTML di base consentito (p, br, strong). |
externalTicketStats | Vendite Live | Invia direttamente i dati di vendita attuali (Venduti/Capacità)! |
imageDataUri | Immagine di Copertina | Invia l'immagine principale come stringa Base64. |
galleryImages | Galleria Immagini | Un array di oggetti (URL o Base64) per immagini aggiuntive. |
seriesId | Tour/Serie | Usa lo stesso ID per tutti gli eventi di un tour. |
capacity | Capacità | Importante per il calcolo "Quasi Esaurito". |
L'API Viventii utilizza uno schema di destinazione statico. Ciò significa: i nomi dei campi (chiavi) che ci invii (es. name_source) devono essere sempre nominati esattamente come descritto in questa documentazione.
Come funziona il mapping? Il tuo sistema (es. WordPress) ha i propri nomi di campo. Devi "tradurre" questi nomi nei nostri nel tuo codice:
| Tuo Campo (Esempio) | Campo di Destinazione Viventii |
|---|---|
$post->post_title | name_source |
$meta['location'] | location |
$event['start'] | date / time |
Dove avviene il mapping?
Il mapping avviene nel tuo sistema (ad esempio in un cronjob, uno script di sincronizzazione o un middleware). Prima di inviare la richiesta POST a Viventii, assegni le tue variabili locali alle chiavi di Viventii.
Se usi WordPress, il mapping avviene solitamente nel file functions.php del tuo tema o in un plugin dedicato. Un modello collaudato è l'uso dell hook save_post.
Il Principio del Ponte (Importante per capire) Molti chiedono: 'Come fa Viventii a sapere cosa significa un determinato campo nel mio sistema?'
La risposta: Viventii non lo sa. Viventii è un ricevitore passivo (la destinazione). Il tuo sistema è il mittente attivo (la sorgente).
// Esempio per la 'traduzione' in WordPress functions.php: add_action('save_post', function($post_id) { // Passo A: Recupera i tuoi dati interni $mio_titolo_interno = get_the_title($post_id); $mio_indirizzo_interno = get_post_meta($post_id, 'wp_field_address', true); // Passo B: Mapping (Assegni il tuo valore alla nostra chiave) $payload = [ 'name_source' => $mio_titolo_interno, // Traduzione: WP-Title -> Viventii-Key 'location' => $mio_indirizzo_interno, // Traduzione: WP-Meta -> Viventii-Key 'sourceId' => 'wp-' . $post_id ]; // Passo C: Inviad a Viventii wp_remote_post('https://api.viventii.com/v1/organizer/events', ['body' => json_encode($payload)]); }, 10, 1);
Stiamo lavorando a Viventii Connect, un plugin specializzato per WordPress.
Se vuoi testare la versione beta, contatta il nostro supporto!
Per sfruttare appieno il potenziale dell'IA di Viventii, invia più dettagli possibili. L'IA utilizza questi fatti per scrivere automaticamente descrizioni ottimizzate per la SEO in 6 lingue.
| Campo | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
sourceId | String | ✅ | Il tuo ID. Previene i duplicati durante l'auto-sync (es. wp-123). |
source_system | String | No | Nome del tuo sistema (es. "Webshop 1"). |
name_source | String | ✅ | Titolo originale del tuo evento. |
description_source | String | ✅ | Descrizione originale (HTML consentito). |
date | String | ✅ | Data nel formato YYYY-MM-DD. |
time | String | ✅ | Ora di inizio nel formato HH:MM. |
slug | String | No | Il tuo permalink personalizzato (Viventii ne genera uno se vuoto). |
seriesId | String | No | ID di una serie di eventi o di un tour. |
organizationId | String | No | ID del tuo organizzatore/location (per i gruppi). |
| Campo | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
location | String | ✅ | Nome del luogo (es. "Olympiastadion"). |
street | String | ✅ | Via e numero civico. |
city | String | ✅ | Città. |
zip | String | No | Codice postale. |
country | String | No | Paese (predefinito: DE). |
lat / lng | Number | No | Coordinate manuali (altrimenti via auto-geocodifica). |
| Campo | Tipo | Descrizione |
|---|---|---|
isWheelchairAccessible | Boolean | Il luogo è accessibile alle sedie a rotelle? |
hasAccessibleRestrooms | Boolean | Ci sono servizi igienici accessibili? |
allowsServiceAnimals | Boolean | Gli animali da assistenza sono i benvenuti? |
hasSignLanguage | Boolean | L'evento è tradotto nella lingua dei segni? |
hasAutomaticDoors | Boolean | Ci sono porte/ingressi automatici? |
accessibilityNotes_source | String | Dettagli testuali sull'accessibilità (es. "Rampa all'ingresso poster"). |
| Campo | Tipo | Descrizione |
|---|---|---|
venueTypes | Array | Tipi: restaurant, cafe, bakery, ice_cream, cocktail_bar, wine_bar, beer_garden, pub, club, bistro, food_truck, fast_food, fine_dining_restaurant. |
cuisineTypes | Array | Cucine: 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 | Opzioni: vegetarian, vegan, gluten_free, lactose_free, halal, kosher, organic, low_carb. |
serviceOptions | Array | Servizio: 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 | Pagamento: cash, credit_card, debit_card, mobile_payment, voucher. |
reservationUrl | URL | Link diretto al sistema di prenotazione del ristorante. |
priceRange | Enum | Fascia di prezzo: budget (€), moderate (€€), upscale (€€€), fine_dining (€€€€). |
| Campo | Tipo | Descrizione |
|---|---|---|
publicTransportInfo_source | String | Dettagli sull'arrivo con i mezzi pubblici. |
parkingInfo_source | String | Dove parcheggiare? (Garage, parcheggio, costi). |
isWeatherDependent | Boolean | L'evento si svolge solo con il bel tempo? |
weatherNotes_source | String | Cosa succede in caso di pioggia? (Coperto, opzione indoor). |
| Campo | Tipo | Descrizione |
|---|---|---|
lineup | Array | Elenco degli atti: [{ "name": "Artista A", "role": "Principale" }]. |
schedule | Array | Cronoprogramma: [{ "time": "20:00", "title": "Inizio spettacolo" }]. |
doorsOpenTime | String | Orario di apertura porte (formato HH:MM). |
presaleInfo_source | String | Info prevendita (es. "Early Bird fino a maggio"). |
| Campo | Tipo | Descrizione |
|---|---|---|
facebookUrl | URL | Link alla pagina o all'evento Facebook. |
instagramUrl | URL | Link al profilo Instagram. |
twitterUrl | URL | Link al profilo Twitter/X. |
tiktokUrl | URL | Link al profilo TikTok. |
youtubeUrl | URL | Link a un trailer o canale. |
linkedinUrl | URL | Link per eventi di business. |
websiteUrl | URL | Sito web ufficiale dell'evento. |
trackingPixels | Object | ID: facebook, google, tiktok, linkedin, snapchat. |
specialOffers_source | String | Descrizione delle offerte (es. "Prendi 2 paghi 1 sulle bevande"). |
| Campo | Tipo | Descrizione |
|---|---|---|
ticketUrl | URL | Link alla biglietteria (appare come un pulsante). |
externalTicketStats | Object | Sincronizzazione LIVE: source, totalSold, totalCapacity. |
capacity | Number | Capacità totale dell'evento. |
priceNote_source | String | Informazioni testuali sul prezzo (es. "Da 15€ per studenti"). |
| Campo | Tipo | Descrizione |
|---|---|---|
imageDataUri | DataURI | La tua immagine principale in Base64 (JPG/PNG). |
galleryImages | Array | Altre impressioni: [{ "url": "...", "caption": "..." }]. |
Scope: read — Ideale per sincronizzare il tuo inventario locale con Viventii.
| Parametro | Funzione |
|---|---|
limit | Limita il numero di risultati (Standard: 20) |
offset | Per la paginazione (Pagina 1, 2, 3...) |
organizationId | Filtra per un'organizzazione specifica |
Scope: read — Restituisce il record completo, incluse tutte le traduzioni generate dall'IA e le coordinate.
Scope: write — Invia solo i campi che sono effettivamente cambiati.
Scope: write — Elimina l'evento e tutti i media in modo permanente dal CDN.
Scope: write — Controlla la visibilità e informa i clienti.
| Stato | Effetto |
|---|---|
active | Visibile pubblicamente, i biglietti possono essere venduti. |
cancelled | L'evento è contrassegnato come "Annullato". Viene attivato il webhook. |
postponed | Contrassegnato come "Posticipato". |
draft | Visibile solo a te. Predefinito per gli eventi di test. |
Scope: write — La parte più importante per il "Live Feeling" su Viventii.
Scope: write — Trasferisci i dati degli acquirenti a Viventii per l'ingresso.
Scope: write — Se utilizzi le tue app scanner o terminali NFC.
Scope: read — Ideale per scanner offline o report.
Scope: read — Per dashboard live nel luogo dell'evento.
Scope: read — Combina tutti i dati di vendita provenienti da fonti diverse.
Scope: write — Gestisci le allocazioni dei biglietti per canale o categoria.
I webhook sono notifiche automatiche che Viventii invia al tuo sistema.
| Evento | Quando viene attivato? |
|---|---|
event.created | Nuovo evento creato |
event.updated | Dati dell'evento modificati |
event.status_changed | Annullamento, posticipo, pubblicazione |
event.ticket_sold | Biglietto venduto tramite Viventii |
event.attendee_added | Nuovo partecipante aggiunto |
Scope: read — Recupera tutte le fatture Stripe per il tuo account Viventii.
Scope: read — Esporta gli hash delle email per le Custom Audience (Facebook, Google, ecc.).
Hai domande sull'integrazione? Il nostro team tecnico sarà lieto di aiutarti.
Buona fortuna con la tua integrazione!