Viventii
Buscar eventosRelease Radar
Iniciar sesiónRegistrarse
Viventii
Viventii Logo

Descubre eventos locales, conciertos, talleres y más con Viventii.

Descubrir

Ver todas las ciudades

Categorías

Fiestas y ClubbingMúsica y FestivalesFerias y MercadillosCompras y MercadosBares y RestaurantesFamilia y NiñosVer todas las categorías

Empresa

Empleo y carreraFAQSoporte y contactoPromociones y ofertas

Descubre la vida nocturna o planifica tus propios momentos destacados. Ya sea un gran concierto o una acogedora noche de juegos con amigos, Viventii lo une todo.

Aviso legalPolítica de privacidadCondiciones de usoPolítica de cookiesFuentes de datos y licencias

© ... Viventii UG (haftungsbeschränkt). Todos los derechos reservados.

ExplorarMapaRadarEntradas
ExplorarMapaRadarEntradas

Documentación para Desarrolladores

Referencia completa para la API de Organizadores de Viventii.

Descargar especificación OpenAPI

API de Viventii – Documentación Completa (A-Z)

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

🚀 0. Inicio Rápido: Generador de Código Interactivo

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.


🔐 1. Autenticación y Claves de API

¿Qué es una clave de API?

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

¿Cómo obtener una clave de API?

  1. Abre tu Dashboard de Viventii
  2. Ve a Perfil → Developer
  3. Haz clic en "Crear Clave de API"
  4. Elige un Nombre y Permisos (Scopes)
  5. La clave se mostrará una sola vez – ¡guárdala de forma segura de inmediato!

Scopes (Permisos)

ScopeDerechos¿Cuándo usarlo?
readLeer datosIdeal para widgets, estadísticas o sistemas de respaldo.
writeCrear y cambiar datosNecesario para la sincronización con CMS (WordPress/Shopify) y apps de entrada.
adminAcceso totalSolo para herramientas internas o sistemas de gestión de equipos.

Flujo de Autenticación

  1. Solicitud: Tu servidor envía una solicitud HTTP a Viventii.
  2. Encabezado: Añades el encabezado Authorization: Bearer sk_live_....
  3. Validación: Viventii verifica la clave y tus permisos (Scopes).
  4. Identificación: Viventii asigna la solicitud a tu organización.
  5. Respuesta: Recibes los datos (200 OK) o un mensaje de error (401 Unauthorized).

Mejores Prácticas de Seguridad

  • Nunca uses en el frontend: Una clave de API pertenece al backend (Node.js, PHP, Python). Nunca debe aparecer en el código JavaScript de un sitio web (¡peligro de robo!).
  • Principio de Dos Claves: Usa claves separadas para diferentes sistemas (por ejemplo, una clave para WordPress, otra para la app de escaneo). Si un sistema se ve comprometido, solo necesitas revocar una clave.
  • Rotación: Renueva tus claves cada 6-12 meses.

Alternativo: Token de ID de Firebase

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!


🧪 2. Modo Sandbox (Prueba vs. Live)

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.

Comparación: Live vs. Prueba

CaracterísticaModo Live (sk_live_...)Modo Prueba (sk_test_...)
VisibilidadPúblico en ViventiiSolo para ti (Borrador/Privado)
BrandingTítulo normalObtiene automáticamente [TEST] en el título
WebhooksWebhooks realesWebhooks de prueba (para desarrollo)
ValidezLegalmente vinculanteDatos puramente simulados

Flujo de Trabajo Ideal para Desarrolladores

  1. Clave de Prueba: Crea una clave de prueba (isTest: true) en el Dashboard.
  2. Desarrollo: Integra la API y envía eventos de prueba a Viventii.
  3. Validación: Verifica en el Dashboard bajo "Eventos de Prueba" si todos los campos llegan correctamente.
  4. Salida a Producción: Crea una clave real tan pronto como tus pruebas sean exitosas.
  5. Cambio: Cambia la variable de entorno de tu servidor a la clave real.

💡 Las claves reales no pueden leer/escribir eventos de prueba y viceversa.


📝 3. Eventos – Crear (POST /events)

Scope: write

¿Cuándo necesitas este endpoint?

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.

El Proceso de Sincronización (Universal Sync)

Viventii utiliza un principio de "Upsert" (Actualizar o Insertar). No necesitas almacenar IDs de Viventii en tu base de datos.

  • Paso 1: Tu sistema envía POST /events con un sourceId (por ejemplo, tu ID de publicación de WordPress).
  • Paso 2: Viventii verifica: "¿Ya conozco este sourceId de este organizador?"
    • No: Se crea un nuevo evento.
    • Sí: El evento existente se actualiza con los nuevos datos.
  • Paso 3 (Segundo plano):
    • 📍 Geocodificación: La dirección se convierte en coordenadas para el mapa.
    • 🌐 Traducción por IA: Los textos se traducen automáticamente a 6 idiomas.
    • 🔗 SEO: Se genera un enlace amigable (slug).
    • 🖼️ Flujo de Activos: Tu imagen se optimiza y se carga en el CDN.
  • Paso 4: Recibes la confirmación (action: "created" o "updated").

Campos Importantes y Detalles

CampoSignificadoConsejo Pro
sourceIdTU IDEl ID de tu sistema de origen (ej. wp-123). ¡Crucial para la sincronización automática!
name_sourceTítuloUsa el título original de tu sistema.
description_sourceDescripciónSe permite HTML básico (p, br, strong).
externalTicketStatsVentas en Vivo¡Envía cifras de ventas actuales (Vendidas/Capacidad) directamente!
imageDataUriImagen de TítuloEnvía la imagen principal como una cadena Base64.
galleryImagesGalería de ImágenesUn array de objetos (URL o Base64) para imágenes adicionales.
seriesIdTour/SerieUsa el mismo ID para todos los eventos de una gira.
capacityCapacidadImportante para el cálculo de "Casi Agotado".

🛠️ Mapeo de Campos y Esquema (IMPORTANTE)

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

🔌 Consejo Especial de WordPress

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

  1. Tu Responsabilidad: Escribes un pequeño script (el puente) que consulta datos de tu base de datos.
  2. El Mapeo: Decides en este script qué valor fluye hacia qué campo de Viventii.
  3. El Push: Tu script 'empuja' (POST) los datos completamente traducidos hacia nosotros.
// 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);

🚀 Perspectiva: Viventii Connect (No-Code)

Actualmente estamos trabajando en Viventii Connect, un plugin especializado para WordPress.

  • Upload & Go: Ya no es necesario editar código.
  • Mapeo Visual: Simplemente seleccionas en una lista: 'Campo X de mi tema' -> 'Campo Y en Viventii'.
  • Auto-Health: El plugin te advierte si una sincronización falla.

Si deseas probar la versión beta, ¡contacta con nuestro soporte!


📚 Referencia Completa de Campos (60+ campos)

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.

A. Metadatos del Núcleo (Infraestructura)

CampoTipoObligatorioDescripción
sourceIdString✅Tu ID. Evita duplicados durante la sincronización automática (ej. wp-123).
source_systemStringNoNombre de tu sistema (ej. "Webshop 1").
name_sourceString✅Título original de tu evento.
description_sourceString✅Descripción original (HTML permitido).
dateString✅Fecha en formato YYYY-MM-DD.
timeString✅Hora de inicio en formato HH:MM.
slugStringNoTu permalink personalizado (Viventii genera uno si está vacío).
seriesIdStringNoID de una serie de eventos o gira.
organizationIdStringNoID de tu organizador/recinto (para grupos).

B. Ubicación y Dirección

CampoTipoObligatorioDescripción
locationString✅Nombre del recinto (ej. "Olympiastadion").
streetString✅Calle y número de casa.
cityString✅Ciudad.
zipStringNoCódigo postal.
countryStringNoPaís (predeterminado: DE).
lat / lngNumberNoCoordenadas manuales (se usa geocodificación automática si está vacío).

C. Accesibilidad

CampoTipoDescripción
isWheelchairAccessibleBoolean¿El lugar es accesible para sillas de ruedas?
hasAccessibleRestroomsBoolean¿Hay baños accesibles?
allowsServiceAnimalsBoolean¿Se admiten animales de servicio?
hasSignLanguageBoolean¿El evento se interpreta en lengua de signos?
hasAutomaticDoorsBoolean¿Hay puertas/entradas automáticas?
accessibilityNotes_sourceStringDetalles textuales sobre la accesibilidad (ej. "Rampa en la entrada trasera").

D. Gastronomía y Establecimientos

CampoTipoDescripción
venueTypesArrayTipos: restaurant, cafe, bakery, ice_cream, cocktail_bar, wine_bar, beer_garden, pub, club, bistro, food_truck, fast_food, fine_dining_restaurant.
cuisineTypesArrayCocinas: 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.
dietaryOptionsArrayOpciones: vegetarian, vegan, gluten_free, lactose_free, halal, kosher, organic, low_carb.
serviceOptionsArrayServicio: 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.
paymentMethodsArrayPagos: cash, credit_card, debit_card, mobile_payment, voucher.
reservationUrlURLEnlace directo al sistema de reservas del restaurante.
priceRangeEnumRango de precios: budget (€), moderate (€€), upscale (€€€), fine_dining (€€€€).

E. Logística y Clima

CampoTipoDescripción
publicTransportInfo_sourceStringDetalles sobre la llegada en autobús/tren.
parkingInfo_sourceString¿Dónde aparcar? (Garaje, aparcamiento, costes).
isWeatherDependentBoolean¿El evento solo se realiza con buen tiempo?
weatherNotes_sourceString¿Qué pasa si llueve? (Cubierto, opción interior).

F. Programa y Lineup

CampoTipoDescripción
lineupArrayLista de actos: [{ "name": "Artista A", "role": "Principal" }].
scheduleArrayHorario: [{ "time": "20:00", "title": "Inicio del espectáculo" }].
doorsOpenTimeStringHora de apertura de puertas (formato HH:MM).
presaleInfo_sourceStringInfo de preventa (ej. "Early Bird hasta mayo").

G. Marketing y Redes Sociales

CampoTipoDescripción
facebookUrlURLEnlace a la página o evento de Facebook.
instagramUrlURLEnlace al perfil de Instagram.
twitterUrlURLEnlace al perfil de Twitter/X.
tiktokUrlURLEnlace al perfil de TikTok.
youtubeUrlURLEnlace a un tráiler o canal.
linkedinUrlURLEnlace para eventos de negocios.
websiteUrlURLSitio web oficial del evento.
trackingPixelsObjectIDs: facebook, google, tiktok, linkedin, snapchat.
specialOffers_sourceStringDescripción de ofertas (ej. "Bebidas 2 por 1").

H. Entradas y Estadísticas

CampoTipoDescripción
ticketUrlURLEnlace a la tienda de entradas (aparece como un botón).
externalTicketStatsObjectSincronización LIVE: source, totalSold, totalCapacity.
capacityNumberCapacidad total del evento.
priceNote_sourceStringInformación textual de precios (ej. "Desde 15€ para estudiantes").

I. Medios y Galería

CampoTipoDescripción
imageDataUriDataURITu imagen principal como Base64 (JPG/PNG).
galleryImagesArrayMás impresiones: [{ "url": "...", "caption": "..." }].

📋 4. Eventos – Listar (GET /events)

Scope: read — Ideal para sincronizar tu inventario local con Viventii.

Opciones de Filtro

ParámetroFunción
limitLimita el número de resultados (Estándar: 20)
offsetPara paginación (Página 1, 2, 3...)
organizationIdFiltra por una organización específica

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

Scope: read — Devuelve el registro completo, incluyendo todas las traducciones generadas por IA y coordenadas.


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

Scope: write — Solo envía los campos que realmente han cambiado.


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

Scope: write — Elimina el evento y todos los medios permanentemente del CDN.


🔄 8. Cambiar Estado del Evento (POST /events/:id/status)

Scope: write — Controla la visibilidad e informa a los clientes.

Resumen de Estados

EstadoEfecto
activeVisible públicamente, se pueden vender entradas.
cancelledEl evento se marca como "Cancelado". Se activa el webhook.
postponedMarcado como "Pospuesto".
draftVisible solo para ti. Predeterminado para eventos de prueba.

🎟️ 9. Estadísticas de Ventas (POST /events/:id/tickets/stats)

Scope: write — La parte más importante para el "sentimiento en vivo" en Viventii.


👥 10. Sincronizar Listas de Asistentes (POST /events/:id/tickets/attendees)

Scope: write — Transfiere tus datos de compradores a Viventii para la entrada.


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

Scope: write — Si usas aplicaciones de escaneo personalizadas o terminales NFC.


📥 12. Exportar Lista de Invitados (GET /events/:id/tickets/export)

Scope: read — Ideal para escáneres offline o informes.


📊 13. Estadísticas de Entrada en Vivo (GET /events/:id/stats/entry)

Scope: read — Para tableros en vivo en el lugar del evento.


📈 14. Vista de Entradas Unificada (GET /events/:id/tickets)

Scope: read — Combina todos los datos de ventas de diferentes fuentes.


📦 15. Inventario y Asignaciones (PATCH /events/:id/inventory)

Scope: write — Gestiona las asignaciones de entradas por canal o categoría.


🔗 16. Webhooks – Registro y Gestión

¿Qué son los Webhooks?

Los webhooks son notificaciones automáticas que Viventii envía a tu sistema.

Evento¿Cuándo se activa?
event.createdNuevo evento creado
event.updatedDatos del evento cambiados
event.status_changedCancelación, aplazamiento, publicación
event.ticket_soldEntrada vendida a través de Viventii
event.attendee_addedNuevo participante añadido

💳 17. Finanzas – Facturas y Facturación

Scope: read — Recupera todas las facturas de Stripe para tu cuenta de Viventii.


📣 18. Sincronización de Audiencia – Grupos de Marketing

Scope: read — Exporta hashes de correo electrónico para Audiencias Personalizadas (Facebook, Google, etc.).


🛠️ 19. Soporte y Ayuda

¿Preguntas sobre la integración? Nuestro equipo técnico estará encantado de ayudar.

  • Correo electrónico: support@viventii.com
  • Web: Soporte y Contacto

¡Buena suerte con tu integración!