Referencia completa para la API de Organizadores de Viventii.
Esta documentación describe cada función, cada endpoint y cada posibilidad de integración de la API de Viventii – sin atajos.
Base URL: https://viventii.com/api/v1/organizer
Usa nuestra herramienta interactiva para generar código listo para usar en tu sistema. Solo introduce tu clave de API y un nombre para tu sistema – nuestro Universal Sync se encarga del resto automáticamente.
Una clave de API es una clave secreta que permite que tu sistema actúe en nombre de tu cuenta de Viventii. Formato: sk_live_a1b2c3d4e5f6...
| Scope | Derechos | ¿Cuándo usarlo? |
|---|---|---|
read | Leer datos | Ideal para widgets, estadísticas o sistemas de respaldo. |
write | Crear y cambiar datos | Necesario para la sincronización con CMS (WordPress/Shopify) y apps de entrada. |
admin | Acceso total | Solo para herramientas internas o sistemas de gestión de equipos. |
Authorization: Bearer sk_live_....200 OK) o un mensaje de error (401 Unauthorized).Las aplicaciones móviles (iOS/Android) pueden enviar un Token de ID de Firebase del usuario conectado en lugar de una clave de API. Viventii reconoce al usuario automáticamente y otorga los derechos correspondientes.
⚠️ ¡La clave se muestra solo UNA VEZ!
Viventii separa estrictamente los datos de prueba de los datos reales en vivo. Esto evita que los eventos de prueba se vuelvan visibles accidentalmente para los clientes.
| Característica | Modo Live (sk_live_...) | Modo Prueba (sk_test_...) |
|---|---|---|
| Visibilidad | Público en Viventii | Solo para ti (Borrador/Privado) |
| Branding | Título normal | Obtiene automáticamente [TEST] en el título |
| Webhooks | Webhooks reales | Webhooks de prueba (para desarrollo) |
| Validez | Legalmente vinculante | Datos puramente simulados |
isTest: true) en el Dashboard.💡 Las claves reales no pueden leer/escribir eventos de prueba y viceversa.
Scope: write
Cada vez que se crea un nuevo evento en tu sistema de origen (CMS, sitio web, base de datos). Este es el punto de partida para la sincronización automática.
Viventii utiliza un principio de "Upsert" (Actualizar o Insertar). No necesitas almacenar IDs de Viventii en tu base de datos.
POST /events con un sourceId (por ejemplo, tu ID de publicación de WordPress).sourceId de este organizador?"
action: "created" o "updated").| Campo | Significado | Consejo Pro |
|---|---|---|
sourceId | TU ID | El ID de tu sistema de origen (ej. wp-123). ¡Crucial para la sincronización automática! |
name_source | Título | Usa el título original de tu sistema. |
description_source | Descripción | Se permite HTML básico (p, br, strong). |
externalTicketStats | Ventas en Vivo | ¡Envía cifras de ventas actuales (Vendidas/Capacidad) directamente! |
imageDataUri | Imagen de Título | Envía la imagen principal como una cadena Base64. |
galleryImages | Galería de Imágenes | Un array de objetos (URL o Base64) para imágenes adicionales. |
seriesId | Tour/Serie | Usa el mismo ID para todos los eventos de una gira. |
capacity | Capacidad | Importante para el cálculo de "Casi Agotado". |
La API de Viventii utiliza un esquema de destino estático. Esto significa: Los nombres de los campos (claves) que nos envías (por ejemplo, name_source) deben llamarse siempre exactamente como se describe en esta documentación.
¿Cómo funciona el mapeo? Tu sistema (por ejemplo, WordPress) tiene sus propios nombres de campos. Debes "traducir" estos a nuestros nombres en tu código:
| Tu campo (Ejemplo) | Campo de Destino de Viventii |
|---|---|
$post->post_title | name_source |
$meta['location'] | location |
$event['start'] | date / time |
¿Dónde se realiza el mapeo?
El mapeo se realiza en tu sistema (por ejemplo, en un cronjob, un script de sincronización o un middleware). Antes de enviar la solicitud POST a Viventii, asignas tus variables locales a las claves de Viventii.
Si usas WordPress, el mapeo suele ocurrir en el functions.php de tu tema o en un plugin dedicado. Un patrón probado es el uso del hook save_post.
El Principio del Puente (Importante para entender) Muchos preguntan: '¿Cómo sabe Viventii qué campo en mi sistema significa qué?'
La respuesta: Viventii no lo sabe. Viventii es un receptor pasivo (el destino). Tu sistema es el emisor activo (la fuente).
// Ejemplo para 'traducción' en WordPress functions.php: add_action('save_post', function($post_id) { // Paso A: Obtener tus datos internos $mi_titulo_interno = get_the_title($post_id); $mi_direccion_interna = get_post_meta($post_id, 'wp_field_address', true); // Paso B: Mapeo (Asignas tu valor a nuestra clave) $payload = [ 'name_source' => $mi_titulo_interno, // Traducción: WP-Title -> Viventii-Key 'location' => $mi_direccion_interna, // Traducción: WP-Meta -> Viventii-Key 'sourceId' => 'wp-' . $post_id ]; // Paso C: Enviar a Viventii wp_remote_post('https://api.viventii.com/v1/organizer/events', ['body' => json_encode($payload)]); }, 10, 1);
Actualmente estamos trabajando en Viventii Connect, un plugin especializado para WordPress.
Si deseas probar la versión beta, ¡contacta con nuestro soporte!
Para aprovechar todo el potencial de la IA de Viventii, envía tantos detalles como sea posible. La IA utiliza estos hechos para escribir automáticamente descripciones optimizadas para SEO en 6 idiomas.
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
sourceId | String | ✅ | Tu ID. Evita duplicados durante la sincronización automática (ej. wp-123). |
source_system | String | No | Nombre de tu sistema (ej. "Webshop 1"). |
name_source | String | ✅ | Título original de tu evento. |
description_source | String | ✅ | Descripción original (HTML permitido). |
date | String | ✅ | Fecha en formato YYYY-MM-DD. |
time | String | ✅ | Hora de inicio en formato HH:MM. |
slug | String | No | Tu permalink personalizado (Viventii genera uno si está vacío). |
seriesId | String | No | ID de una serie de eventos o gira. |
organizationId | String | No | ID de tu organizador/recinto (para grupos). |
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
location | String | ✅ | Nombre del recinto (ej. "Olympiastadion"). |
street | String | ✅ | Calle y número de casa. |
city | String | ✅ | Ciudad. |
zip | String | No | Código postal. |
country | String | No | País (predeterminado: DE). |
lat / lng | Number | No | Coordenadas manuales (se usa geocodificación automática si está vacío). |
| Campo | Tipo | Descripción |
|---|---|---|
isWheelchairAccessible | Boolean | ¿El lugar es accesible para sillas de ruedas? |
hasAccessibleRestrooms | Boolean | ¿Hay baños accesibles? |
allowsServiceAnimals | Boolean | ¿Se admiten animales de servicio? |
hasSignLanguage | Boolean | ¿El evento se interpreta en lengua de signos? |
hasAutomaticDoors | Boolean | ¿Hay puertas/entradas automáticas? |
accessibilityNotes_source | String | Detalles textuales sobre la accesibilidad (ej. "Rampa en la entrada trasera"). |
| Campo | Tipo | Descripción |
|---|---|---|
venueTypes | Array | Tipos: restaurant, cafe, bakery, ice_cream, cocktail_bar, wine_bar, beer_garden, pub, club, bistro, food_truck, fast_food, fine_dining_restaurant. |
cuisineTypes | Array | Cocinas: 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 | Opciones: vegetarian, vegan, gluten_free, lactose_free, halal, kosher, organic, low_carb. |
serviceOptions | Array | Servicio: 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 | Pagos: cash, credit_card, debit_card, mobile_payment, voucher. |
reservationUrl | URL | Enlace directo al sistema de reservas del restaurante. |
priceRange | Enum | Rango de precios: budget (€), moderate (€€), upscale (€€€), fine_dining (€€€€). |
| Campo | Tipo | Descripción |
|---|---|---|
publicTransportInfo_source | String | Detalles sobre la llegada en autobús/tren. |
parkingInfo_source | String | ¿Dónde aparcar? (Garaje, aparcamiento, costes). |
isWeatherDependent | Boolean | ¿El evento solo se realiza con buen tiempo? |
weatherNotes_source | String | ¿Qué pasa si llueve? (Cubierto, opción interior). |
| Campo | Tipo | Descripción |
|---|---|---|
lineup | Array | Lista de actos: [{ "name": "Artista A", "role": "Principal" }]. |
schedule | Array | Horario: [{ "time": "20:00", "title": "Inicio del espectáculo" }]. |
doorsOpenTime | String | Hora de apertura de puertas (formato HH:MM). |
presaleInfo_source | String | Info de preventa (ej. "Early Bird hasta mayo"). |
| Campo | Tipo | Descripción |
|---|---|---|
facebookUrl | URL | Enlace a la página o evento de Facebook. |
instagramUrl | URL | Enlace al perfil de Instagram. |
twitterUrl | URL | Enlace al perfil de Twitter/X. |
tiktokUrl | URL | Enlace al perfil de TikTok. |
youtubeUrl | URL | Enlace a un tráiler o canal. |
linkedinUrl | URL | Enlace para eventos de negocios. |
websiteUrl | URL | Sitio web oficial del evento. |
trackingPixels | Object | IDs: facebook, google, tiktok, linkedin, snapchat. |
specialOffers_source | String | Descripción de ofertas (ej. "Bebidas 2 por 1"). |
| Campo | Tipo | Descripción |
|---|---|---|
ticketUrl | URL | Enlace a la tienda de entradas (aparece como un botón). |
externalTicketStats | Object | Sincronización LIVE: source, totalSold, totalCapacity. |
capacity | Number | Capacidad total del evento. |
priceNote_source | String | Información textual de precios (ej. "Desde 15€ para estudiantes"). |
| Campo | Tipo | Descripción |
|---|---|---|
imageDataUri | DataURI | Tu imagen principal como Base64 (JPG/PNG). |
galleryImages | Array | Más impresiones: [{ "url": "...", "caption": "..." }]. |
Scope: read — Ideal para sincronizar tu inventario local con Viventii.
| Parámetro | Función |
|---|---|
limit | Limita el número de resultados (Estándar: 20) |
offset | Para paginación (Página 1, 2, 3...) |
organizationId | Filtra por una organización específica |
Scope: read — Devuelve el registro completo, incluyendo todas las traducciones generadas por IA y coordenadas.
Scope: write — Solo envía los campos que realmente han cambiado.
Scope: write — Elimina el evento y todos los medios permanentemente del CDN.
Scope: write — Controla la visibilidad e informa a los clientes.
| Estado | Efecto |
|---|---|
active | Visible públicamente, se pueden vender entradas. |
cancelled | El evento se marca como "Cancelado". Se activa el webhook. |
postponed | Marcado como "Pospuesto". |
draft | Visible solo para ti. Predeterminado para eventos de prueba. |
Scope: write — La parte más importante para el "sentimiento en vivo" en Viventii.
Scope: write — Transfiere tus datos de compradores a Viventii para la entrada.
Scope: write — Si usas aplicaciones de escaneo personalizadas o terminales NFC.
Scope: read — Ideal para escáneres offline o informes.
Scope: read — Para tableros en vivo en el lugar del evento.
Scope: read — Combina todos los datos de ventas de diferentes fuentes.
Scope: write — Gestiona las asignaciones de entradas por canal o categoría.
Los webhooks son notificaciones automáticas que Viventii envía a tu sistema.
| Evento | ¿Cuándo se activa? |
|---|---|
event.created | Nuevo evento creado |
event.updated | Datos del evento cambiados |
event.status_changed | Cancelación, aplazamiento, publicación |
event.ticket_sold | Entrada vendida a través de Viventii |
event.attendee_added | Nuevo participante añadido |
Scope: read — Recupera todas las facturas de Stripe para tu cuenta de Viventii.
Scope: read — Exporta hashes de correo electrónico para Audiencias Personalizadas (Facebook, Google, etc.).
¿Preguntas sobre la integración? Nuestro equipo técnico estará encantado de ayudar.
¡Buena suerte con tu integración!