Référence complète pour l'API organisateur Viventii.
Cette documentation décrit chaque fonction, chaque endpoint et chaque possibilité d'intégration de l'API Viventii – sans raccourcis.
Base URL: https://viventii.com/api/v1/organizer
Utilisez notre outil interactif pour générer du code prêt à l'emploi pour votre système. Saisissez simplement votre clé API et un nom pour votre système – notre Universal Sync s'occupe du reste automatiquement.
Une clé API est une clé secrète qui permet à votre système d'agir au nom de votre compte Viventii. Format : sk_live_a1b2c3d4e5f6...
| Scope | Droits | Quand l'utiliser ? |
|---|---|---|
read | Lire les données | Idéal pour les widgets, les statistiques ou les systèmes de sauvegarde. |
write | Créer & modifier des données | Nécessaire pour la synchronisation CMS (WordPress/Shopify) et les applications d'entrée. |
admin | Accès complet | À utiliser uniquement pour les outils internes ou les systèmes de gestion d'équipe. |
Authorization: Bearer sk_live_....200 OK) ou un message d'erreur (401 Unauthorized).Les applications mobiles (iOS/Android) peuvent envoyer un Firebase ID Token de l'utilisateur connecté au lieu d'une clé API. Viventii reconnaît l'utilisateur automatiquement et accorde les droits appropriés.
⚠️ La clé n'est affichée qu'UNE SEULE FOIS !
Viventii sépare strictement les données de test des données réelles en direct. Cela évite que des événements de test ne deviennent accidentellement visibles pour les clients.
| Fonctionnalité | Mode Live (sk_live_...) | Mode Test (sk_test_...) |
|---|---|---|
| Visibilité | Public sur Viventii | Uniquement pour vous (Brouillon/Privé) |
| Branding | Titre normal | Reçoit automatiquement [TEST] dans le titre |
| Webhooks | Vrais webhooks | Webhooks de test (pour le développement) |
| Validité | Juridiquement contraignant | Données purement simulées |
isTest: true) dans le Tableau de bord.💡 Les clés live ne peuvent pas lire/écrire des événements de test et vice versa.
Scope : write
Chaque fois qu'un nouvel événement est créé dans votre système source (CMS, site web, base de données). C'est le point de départ de la synchronisation automatique.
Viventii utilise un principe d'"Upsert" (Update or Insert). Vous n'avez pas besoin de stocker les ID Viventii dans votre base de données.
POST /events avec un sourceId (par exemple, votre ID d'article WordPress).sourceId pour cet organisateur ?"
action: "created" ou "updated").| Champ | Signification | Conseil de Pro |
|---|---|---|
sourceId | VOTRE ID | L'ID de votre système source (ex. wp-123). Crucial pour l'auto-sync ! |
name_source | Titre | Utilisez le titre original de votre système. |
description_source | Description | HTML de base autorisé (p, br, strong). |
externalTicketStats | Ventes en direct | Envoyez directement les chiffres de vente actuels (Vendus/Capacité) ! |
imageDataUri | Image de titre | Envoyez l'image principale sous forme de chaîne Base64. |
galleryImages | Galerie d'images | Un tableau d'objets (URL ou Base64) pour des images supplémentaires. |
seriesId | Tournée/Série | Utilisez le même ID pour tous les événements d'une tournée. |
capacity | Capacité | Important pour le calcul "Presque complet". |
L'API Viventii utilise un schéma cible statique. Cela signifie : les noms de champs (clés) que vous nous envoyez (ex. name_source) doivent toujours être nommés exactement comme décrit dans cette documentation.
Comment fonctionne le mapping ? Votre système (ex. WordPress) possède ses propres noms de champs. Vous devez les "traduire" en nos noms dans votre code :
| Votre champ (Exemple) | Champ cible Viventii |
|---|---|
$post->post_title | name_source |
$meta['location'] | location |
$event['start'] | date / time |
Où se fait le mapping ?
Le mapping se fait dans votre système (par exemple dans un cronjob, un script de synchronisation ou un middleware). Avant d'envoyer la requête POST à Viventii, vous affectez vos variables locales aux clés Viventii.
Si vous utilisez WordPress, le mapping a généralement lieu dans le fichier functions.php de votre thème ou dans un plugin dédié. Un modèle éprouvé consiste à utiliser le hook save_post.
Le Principe du Pont (Important pour comprendre) Beaucoup demandent : 'Comment Viventii sait-il quel champ de mon système signifie quoi ?'
La réponse : Viventii ne le sait pas. Viventii est un récepteur passif (la cible). Votre système est l'émetteur actif (la source).
// Exemple de 'traduction' dans le fichier functions.php de WordPress : add_action('save_post', function($post_id) { // Étape A : Récupérer vos données internes $mon_titre_interne = get_the_title($post_id); $mon_adresse_interne = get_post_meta($post_id, 'wp_field_address', true); // Étape B : Mapping (Vous affectez votre valeur à notre clé) $payload = [ 'name_source' => $mon_titre_interne, // Traduction : Titre WP -> Clé Viventii 'location' => $mon_adresse_interne, // Traduction : Meta WP -> Clé Viventii 'sourceId' => 'wp-' . $post_id ]; // Étape C : Envoyer à Viventii wp_remote_post('https://api.viventii.com/v1/organizer/events', ['body' => json_encode($payload)]); }, 10, 1);
Nous travaillons actuellement sur Viventii Connect, un plugin WordPress spécialisé.
Si vous souhaitez tester la version bêta, contactez notre support !
Pour exploiter tout le potentiel de l'IA Viventii, envoyez autant de détails que possible. L'IA utilise ces faits pour rédiger automatiquement des descriptions optimisées pour le SEO en 6 langues.
| Champ | Type | Obligatoire | Description |
|---|---|---|---|
sourceId | String | ✅ | Votre ID. Empêche les doublons lors de l'auto-sync (ex. wp-123). |
source_system | String | Non | Nom de votre système (ex. "Webshop 1"). |
name_source | String | ✅ | Titre original de votre événement. |
description_source | String | ✅ | Description originale (HTML autorisé). |
date | String | ✅ | Date au format YYYY-MM-DD. |
time | String | ✅ | Heure de début au format HH:MM. |
slug | String | Non | Votre permalien personnalisé (Viventii en génère un si vide). |
seriesId | String | Non | ID d'une série d'événements ou d'une tournée. |
organizationId | String | Non | ID de votre organisateur/lieu (pour les groupes). |
| Champ | Type | Obligatoire | Description |
|---|---|---|---|
location | String | ✅ | Nom du lieu (ex. "Olympiastadion"). |
street | String | ✅ | Rue et numéro. |
city | String | ✅ | Ville. |
zip | String | Non | Code postal. |
country | String | Non | Pays (par défaut : DE). |
lat / lng | Number | Non | Coordonnées manuelles (sinon via auto-géocodage). |
| Champ | Type | Description |
|---|---|---|
isWheelchairAccessible | Boolean | Le lieu est-il accessible aux fauteuils roulants ? |
hasAccessibleRestrooms | Boolean | Y a-t-il des toilettes accessibles ? |
allowsServiceAnimals | Boolean | Les animaux d'assistance sont-ils les bienvenus ? |
hasSignLanguage | Boolean | L'événement est-il interprété en langue des signes ? |
hasAutomaticDoors | Boolean | Y a-t-il des portes/entrées automatiques ? |
accessibilityNotes_source | String | Détails textuels sur l'accessibilité (ex. "Rampe à l'entrée arrière"). |
| Champ | Type | Description |
|---|---|---|
venueTypes | Array | Types : restaurant, cafe, bakery, ice_cream, cocktail_bar, wine_bar, beer_garden, pub, club, bistro, food_truck, fast_food, fine_dining_restaurant. |
cuisineTypes | Array | Cuisines : 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 | Options : 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 | Ambiance : casual, cozy, romantic, family_friendly, trendy, upscale_elegant, rustic, modern, traditional, lively, quiet, business. |
paymentMethods | Array | Paiement : cash, credit_card, debit_card, mobile_payment, voucher. |
reservationUrl | URL | Lien direct vers le système de réservation du restaurant. |
priceRange | Enum | Gamme de prix : budget (€), moderate (€€), upscale (€€€), fine_dining (€€€€). |
| Champ | Type | Description |
|---|---|---|
publicTransportInfo_source | String | Détails sur l'accès en bus/train. |
parkingInfo_source | String | Où se garer ? (Parking souterrain, parking, tarifs). |
isWeatherDependent | Boolean | L'événement n'a-t-il lieu que par beau temps ? |
weatherNotes_source | String | Que se passe-t-il en cas de pluie ? (Couvert, option intérieure). |
| Champ | Type | Description |
|---|---|---|
lineup | Array | Liste des artistes : [{ "name": "Artiste A", "role": "Principal" }]. |
schedule | Array | Emploi du temps : [{ "time": "20:00", "title": "Début du spectacle" }]. |
doorsOpenTime | String | Heure d'ouverture des portes (format HH:MM). |
presaleInfo_source | String | Infos sur la prévente (ex. "Early Bird jusqu'en mai"). |
| Champ | Type | Description |
|---|---|---|
facebookUrl | URL | Lien vers la page ou l'événement Facebook. |
instagramUrl | URL | Lien vers le profil Instagram. |
twitterUrl | URL | Lien vers le profil Twitter/X. |
tiktokUrl | URL | Lien vers le profil TikTok. |
youtubeUrl | URL | Lien vers un trailer ou une chaîne. |
linkedinUrl | URL | Lien pour les événements professionnels. |
websiteUrl | URL | Site web officiel de l'événement. |
trackingPixels | Object | ID : facebook, google, tiktok, linkedin, snapchat. |
specialOffers_source | String | Description des offres (ex. "2-pour-1 sur les boissons"). |
| Champ | Type | Description |
|---|---|---|
ticketUrl | URL | Lien vers la billetterie (apparaît sous forme de bouton). |
externalTicketStats | Object | Sync LIVE : source, totalSold, totalCapacity. |
capacity | Number | Capacité totale de l'événement. |
priceNote_source | String | Info tarifaire textuelle (ex. "À partir de 15€ pour les étudiants"). |
| Champ | Type | Description |
|---|---|---|
imageDataUri | DataURI | Votre image principale en Base64 (JPG/PNG). |
galleryImages | Array | Autres impressions : [{ "url": "...", "caption": "..." }]. |
Scope : read — Idéal pour synchroniser votre inventaire local avec Viventii.
| Paramètre | Fonction |
|---|---|
limit | Limite le nombre de résultats (Standard : 20) |
offset | Pour la pagination (Page 1, 2, 3...) |
organizationId | Filtre par une organisation spécifique |
Scope : read — Renvoie l'enregistrement complet, incluant toutes les traductions générées par l'IA et les coordonnées.
Scope : write — Envoyez uniquement les champs qui ont réellement changé.
Scope : write — Supprime l'événement et tous les médias de façon permanente du CDN.
Scope : write — Contrôle la visibilité et informe les clients.
| Statut | Effet |
|---|---|
active | Visible publiquement, les billets peuvent être vendus. |
cancelled | L'événement est marqué comme "Annulé". Le webhook est déclenché. |
postponed | Marké comme "Reporté". |
draft | Visible uniquement par vous. Par défaut pour les événements de test. |
Scope : write — La partie la plus importante pour le "Live Feeling" sur Viventii.
Scope : write — Transférez vos données d'acheteurs vers Viventii pour l'entrée.
Scope : write — Si vous utilisez vos propres applications de scanner ou terminaux NFC.
Scope : read — Idéal pour les scanners hors ligne ou les rapports.
Scope : read — Pour les tableaux de bord en direct sur le lieu de l'événement.
Scope : read — Combine toutes les données de vente provenant de différentes sources.
Scope : write — Gérez les contingents de billets par canal ou catégorie.
Les webhooks sont des notifications automatiques que Viventii envoie à votre système.
| Événement | Quand est-il déclenché ? |
|---|---|
event.created | Nouvel événement créé |
event.updated | Données de l'événement modifiées |
event.status_changed | Annulation, report, publication |
event.ticket_sold | Billet vendu via Viventii |
event.attendee_added | Nouveau participant ajouté |
Scope : read — Récupère toutes les factures Stripe de votre compte Viventii.
Scope : read — Exporte les hachages d'e-mails pour les Custom Audiences (Facebook, Google, etc.).
Vous avez des questions sur l'intégration ? Notre équipe technique se fera un plaisir de vous aider.
Bonne chance pour votre intégration !