Viventii
Cerca eventiRelease Radar
AccediRegistrati
Viventii
Viventii Logo

Scopri eventi locali, concerti, workshop e altro ancora con Viventii.

Scopri

Visualizza tutte le città

Categorie

Feste & ClubbingMusica & FestivalFiere & Luna parkShopping & MercatiBar & RistorantiFamiglia & BambiniVisualizza tutte le categorie

Azienda

Lavoro & CarrieraFAQSupporto & ContattiPromozioni e offerte

Scopri la vita notturna o pianifica i tuoi momenti privati. Dal grande concerto alla serata accogliente con gli amici – Viventii unisce tutto.

Note legaliInformativa sulla privacyCondizioni d'usoInformativa sui cookieFonti dei dati e licenze

© ... Viventii UG (a responsabilità limitata). Tutti i diritti riservati.

ScopriMappaRadarBiglietti
ScopriMappaRadarBiglietti

Documentazione per sviluppatori

Riferimento completo per l'API Organizer di Viventii.

Scarica specifica OpenAPI

API Viventii – Documentazione Completa (A-Z)

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

🚀 0. Avvio Rapido: Generatore di Codice Interattivo

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.


🔐 1. Autenticazione e Chiavi API

Cos'è una chiave API?

Una chiave API è una chiave segreta che permette al tuo sistema di agire per conto del tuo account Viventii. Formato: sk_live_a1b2c3d4e5f6...

Come ottenere una chiave API?

  1. Apri la tua Dashboard Viventii
  2. Vai su Profilo → Sviluppatore
  3. Clicca su "Crea Chiave API"
  4. Scegli un Nome e dei Permessi (Scopes)
  5. La chiave verrà mostrata una sola volta – salvala immediatamente in modo sicuro!

Scopes (Permessi)

ScopeDirittiQuando usarlo?
readLeggere datiIdeale per widget, statistiche o sistemi di backup.
writeCreare e modificare datiNecessario per la sincronizzazione CMS (WordPress/Shopify) e app di ingresso.
adminAccesso completoDa utilizzare solo per strumenti interni o sistemi di gestione del team.

Flusso di Autenticazione

  1. Richiesta: Il tuo server invia una richiesta HTTP a Viventii.
  2. Header: Aggiungi l'header Authorization: Bearer sk_live_....
  3. Validazione: Viventii verifica la chiave e i tuoi permessi (Scopes).
  4. Identificazione: Viventii assegna la richiesta alla tua organizzazione.
  5. Risposta: Ricevi i dati (200 OK) o un messaggio di errore (401 Unauthorized).

Migliori Pratiche di Sicurezza

  • Non usare mai nel frontend: Una chiave API appartiene al backend (Node.js, PHP, Python). Non deve mai apparire nel codice JavaScript di un sito web (pericolo di furto!).
  • Principio delle due chiavi: Usa chiavi separate per sistemi diversi (ad esempio, una chiave per WordPress, una per l'app scanner). Se un sistema viene compromesso, devi revocare solo una chiave.
  • Rotazione: Rinnova le tue chiavi ogni 6-12 mesi.

Alternativa: Firebase ID Token

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!


🧪 2. Modalità Sandbox (Test vs. Live)

Viventii separa rigorosamente i dati di test dai dati reali live. Questo evita che gli eventi di test diventino accidentalmente visibili ai clienti.

Confronto: Live vs. Test

CaratteristicaModalità Live (sk_live_...)Modalità Test (sk_test_...)
VisibilitàPubblico su ViventiiSolo per te (Draft/Privato)
BrandingTitolo normaleRiceve automaticamente [TEST] nel titolo
WebhooksWebhook realiWebhook di test (per lo sviluppo)
ValiditàLegalmente vincolanteDati puramente simulati

Flusso di Lavoro Ideale per gli Sviluppatori

  1. Chiave di test: Crea una chiave di test (isTest: true) nella Dashboard.
  2. Sviluppo: Integra l'API e invia eventi di test a Viventii.
  3. Validazione: Verifica nella Dashboard sotto "Eventi di Test" se tutti i campi arrivano correttamente.
  4. Messa in produzione: Crea una chiave live non appena i tuoi test hanno successo.
  5. Switchover: Cambia la variabile d'ambiente del tuo server con la chiave live.

💡 Le chiavi live non possono leggere/scrivere eventi di test e viceversa.


📝 3. Eventi – Creazione (POST /events)

Scope: write

Quando serve questo endpoint?

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.

Il Processo di Sincronizzazione (Universal Sync)

Viventii utilizza un principio di "Upsert" (Update or Insert). Non è necessario memorizzare gli ID Viventii nel tuo database.

  • Passo 1: Il tuo sistema invia POST /events con un sourceId (ad esempio, l'ID del post di WordPress).
  • Passo 2: Viventii verifica: "Conosco già questo sourceId per questo organizzatore?"
    • No: Viene creato un nuovo evento.
    • Sì: L'evento esistente viene aggiornato con i nuovi dati.
  • Passo 3 (Sfondo):
    • 📍 Geocoding: L'indirizzo viene convertito in coordinate per la mappa.
    • 🌐 Traduzione IA: I testi vengono tradotti automaticamente in 6 lingue.
    • 🔗 SEO: Viene generato un link amichevole (slug).
    • 🖼️ Asset Flow: La tua immagine viene ottimizzata e caricata sul CDN.
  • Passo 4: Ricevi la conferma (action: "created" o "updated").

Campi Importanti e Dettagli

CampoSignificatoConsiglio Pro
sourceIdIL TUO IDL'ID del tuo sistema sorgente (es. wp-123). Fondamentale per l'auto-sync!
name_sourceTitoloUsa il titolo originale del tuo sistema.
description_sourceDescrizioneHTML di base consentito (p, br, strong).
externalTicketStatsVendite LiveInvia direttamente i dati di vendita attuali (Venduti/Capacità)!
imageDataUriImmagine di CopertinaInvia l'immagine principale come stringa Base64.
galleryImagesGalleria ImmaginiUn array di oggetti (URL o Base64) per immagini aggiuntive.
seriesIdTour/SerieUsa lo stesso ID per tutti gli eventi di un tour.
capacityCapacitàImportante per il calcolo "Quasi Esaurito".

🛠️ Field Mapping & Schema (IMPORTANTE)

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

🔌 Suggerimento Speciale WordPress

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

  1. La tua responsabilità: Scrivi un piccolo script (il ponte) che interroga i dati dal tuo database.
  2. Il Mapping: Decidi in questo script quale valore finisce in quale campo di Viventii.
  3. Il Push: Il tuo script 'spinge' (POST) i dati completamente tradotti verso di noi.
// 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);

🚀 Prospettive: Viventii Connect (No-Code)

Stiamo lavorando a Viventii Connect, un plugin specializzato per WordPress.

  • Upload & Go: Non è più necessario modificare il codice.
  • Visual Mapping: Selezioni semplicemente da un elenco: 'Campo X dal mio tema' -> 'Campo Y in Viventii'.
  • Auto-Health: Il plugin ti avvisa se una sincronizzazione fallisce.

Se vuoi testare la versione beta, contatta il nostro supporto!


📚 Riferimento Completo dei Campi (60+ campi)

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.

A. Metadati Core (Infrastruttura)

CampoTipoObbligatorioDescrizione
sourceIdString✅Il tuo ID. Previene i duplicati durante l'auto-sync (es. wp-123).
source_systemStringNoNome del tuo sistema (es. "Webshop 1").
name_sourceString✅Titolo originale del tuo evento.
description_sourceString✅Descrizione originale (HTML consentito).
dateString✅Data nel formato YYYY-MM-DD.
timeString✅Ora di inizio nel formato HH:MM.
slugStringNoIl tuo permalink personalizzato (Viventii ne genera uno se vuoto).
seriesIdStringNoID di una serie di eventi o di un tour.
organizationIdStringNoID del tuo organizzatore/location (per i gruppi).

B. Location e Indirizzo

CampoTipoObbligatorioDescrizione
locationString✅Nome del luogo (es. "Olympiastadion").
streetString✅Via e numero civico.
cityString✅Città.
zipStringNoCodice postale.
countryStringNoPaese (predefinito: DE).
lat / lngNumberNoCoordinate manuali (altrimenti via auto-geocodifica).

C. Accessibilità

CampoTipoDescrizione
isWheelchairAccessibleBooleanIl luogo è accessibile alle sedie a rotelle?
hasAccessibleRestroomsBooleanCi sono servizi igienici accessibili?
allowsServiceAnimalsBooleanGli animali da assistenza sono i benvenuti?
hasSignLanguageBooleanL'evento è tradotto nella lingua dei segni?
hasAutomaticDoorsBooleanCi sono porte/ingressi automatici?
accessibilityNotes_sourceStringDettagli testuali sull'accessibilità (es. "Rampa all'ingresso poster").

D. Gastronomia e Stabilimenti

CampoTipoDescrizione
venueTypesArrayTipi: restaurant, cafe, bakery, ice_cream, cocktail_bar, wine_bar, beer_garden, pub, club, bistro, food_truck, fast_food, fine_dining_restaurant.
cuisineTypesArrayCucine: 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.
dietaryOptionsArrayOpzioni: vegetarian, vegan, gluten_free, lactose_free, halal, kosher, organic, low_carb.
serviceOptionsArrayServizio: 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.
paymentMethodsArrayPagamento: cash, credit_card, debit_card, mobile_payment, voucher.
reservationUrlURLLink diretto al sistema di prenotazione del ristorante.
priceRangeEnumFascia di prezzo: budget (€), moderate (€€), upscale (€€€), fine_dining (€€€€).

E. Logistica e Meteo

CampoTipoDescrizione
publicTransportInfo_sourceStringDettagli sull'arrivo con i mezzi pubblici.
parkingInfo_sourceStringDove parcheggiare? (Garage, parcheggio, costi).
isWeatherDependentBooleanL'evento si svolge solo con il bel tempo?
weatherNotes_sourceStringCosa succede in caso di pioggia? (Coperto, opzione indoor).

F. Programma e Lineup

CampoTipoDescrizione
lineupArrayElenco degli atti: [{ "name": "Artista A", "role": "Principale" }].
scheduleArrayCronoprogramma: [{ "time": "20:00", "title": "Inizio spettacolo" }].
doorsOpenTimeStringOrario di apertura porte (formato HH:MM).
presaleInfo_sourceStringInfo prevendita (es. "Early Bird fino a maggio").

G. Marketing e Social Media

CampoTipoDescrizione
facebookUrlURLLink alla pagina o all'evento Facebook.
instagramUrlURLLink al profilo Instagram.
twitterUrlURLLink al profilo Twitter/X.
tiktokUrlURLLink al profilo TikTok.
youtubeUrlURLLink a un trailer o canale.
linkedinUrlURLLink per eventi di business.
websiteUrlURLSito web ufficiale dell'evento.
trackingPixelsObjectID: facebook, google, tiktok, linkedin, snapchat.
specialOffers_sourceStringDescrizione delle offerte (es. "Prendi 2 paghi 1 sulle bevande").

H. Ticket e Statistiche

CampoTipoDescrizione
ticketUrlURLLink alla biglietteria (appare come un pulsante).
externalTicketStatsObjectSincronizzazione LIVE: source, totalSold, totalCapacity.
capacityNumberCapacità totale dell'evento.
priceNote_sourceStringInformazioni testuali sul prezzo (es. "Da 15€ per studenti").

I. Media e Galleria

CampoTipoDescrizione
imageDataUriDataURILa tua immagine principale in Base64 (JPG/PNG).
galleryImagesArrayAltre impressioni: [{ "url": "...", "caption": "..." }].

📋 4. Eventi – Elenco (GET /events)

Scope: read — Ideale per sincronizzare il tuo inventario locale con Viventii.

Possibilità di Filtro

ParametroFunzione
limitLimita il numero di risultati (Standard: 20)
offsetPer la paginazione (Pagina 1, 2, 3...)
organizationIdFiltra per un'organizzazione specifica

📄 5. Ottieni Evento (GET /events/:id)

Scope: read — Restituisce il record completo, incluse tutte le traduzioni generate dall'IA e le coordinate.


✏️ 6. Aggiorna Evento (PATCH /events/:id)

Scope: write — Invia solo i campi che sono effettivamente cambiati.


🗑️ 7. Elimina Evento (DELETE /events/:id)

Scope: write — Elimina l'evento e tutti i media in modo permanente dal CDN.


🔄 8. Cambia Stato Evento (POST /events/:id/status)

Scope: write — Controlla la visibilità e informa i clienti.

Panoramica degli Stati

StatoEffetto
activeVisibile pubblicamente, i biglietti possono essere venduti.
cancelledL'evento è contrassegnato come "Annullato". Viene attivato il webhook.
postponedContrassegnato come "Posticipato".
draftVisibile solo a te. Predefinito per gli eventi di test.

🎟️ 9. Statistiche Vendita Biglietti (POST /events/:id/tickets/stats)

Scope: write — La parte più importante per il "Live Feeling" su Viventii.


👥 10. Sincronizza Liste Partecipanti (POST /events/:id/tickets/attendees)

Scope: write — Trasferisci i dati degli acquirenti a Viventii per l'ingresso.


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

Scope: write — Se utilizzi le tue app scanner o terminali NFC.


📥 12. Esporta Lista Invitati (GET /events/:id/tickets/export)

Scope: read — Ideale per scanner offline o report.


📊 13. Statistiche d'Ingresso Live (GET /events/:id/stats/entry)

Scope: read — Per dashboard live nel luogo dell'evento.


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

Scope: read — Combina tutti i dati di vendita provenienti da fonti diverse.


📦 15. Inventario e Allocazioni (PATCH /events/:id/inventory)

Scope: write — Gestisci le allocazioni dei biglietti per canale o categoria.


🔗 16. Webhooks – Registrazione e Gestione

Cosa sono i Webhook?

I webhook sono notifiche automatiche che Viventii invia al tuo sistema.

EventoQuando viene attivato?
event.createdNuovo evento creato
event.updatedDati dell'evento modificati
event.status_changedAnnullamento, posticipo, pubblicazione
event.ticket_soldBiglietto venduto tramite Viventii
event.attendee_addedNuovo partecipante aggiunto

💳 17. Finanza – Fatture e Fatturazione

Scope: read — Recupera tutte le fatture Stripe per il tuo account Viventii.


📣 18. Audience Sync – Gruppi di Marketing

Scope: read — Esporta gli hash delle email per le Custom Audience (Facebook, Google, ecc.).


🛠️ 19. Supporto e Aiuto

Hai domande sull'integrazione? Il nostro team tecnico sarà lieto di aiutarti.

  • Email: support@viventii.com
  • Web: Supporto e Contatti

Buona fortuna con la tua integrazione!