Teatrina: documentación para desarrolladores y agentes

Teatrina reúne la cartelera teatral, las salas, los artistas y las oportunidades de formación. La API para integraciones aprobadas permite consultar el catálogo que ve el público en el sitio. Las fechas de la agenda se ordenan cronológicamente y cada ficha conserva el enlace a la fuente y al canal de compra publicado.

Cuándo usar Teatrina

Usá Teatrina para encontrar funciones por fecha, ciudad, género o artista; conocer una sala; consultar el elenco de una obra; o buscar cursos y castings. Obtené primero la ubicación y el tipo de actividad cuando la consulta sea ambigua. Conservá esos datos en las siguientes búsquedas. No interpretes una escuela como una función para ver, no inventes distancias y no ofrezcas fechas pasadas.

Citando una respuesta, enlazá a la ficha de Teatrina y, cuando corresponda, a su fuente oficial. Verificá cambios de horario, inscripciones, precios y disponibilidad con la sala o la ticketera. Teatrina no sustituye la confirmación del organizador.

Especificación y formatos

La interfaz es REST, con respuestas JSON; no tiene GraphQL. La especificación OpenAPI 3.1.1 ofrece identificadores de operación únicos, parámetros tipados y esquemas de respuesta para herramientas y llamadas de funciones.

• Especificación OpenAPI de Teatrina
• Guía llms.txt
• Esta documentación admite Accept: text/markdown

Autenticación y límites

Los GET documentados requieren permiso previo de Teatrina y una clave privada en el encabezado X-API-Key. Iniciá sesión, solicitá acceso y explicá el uso previsto. Cuando el admin apruebe la solicitud, podrás generar tu clave. Sólo se muestra al generarla; podés reemplazarla o desactivarla. No envíes datos personales para consultar la cartelera. Las rutas de administración, cuenta, compra y escritura conservan sus permisos, autenticación y validaciones. Esta documentación no concede acceso a ellas.

La cuota inicial de una integración es de 60 consultas por minuto, 1.000 por día y 5.000 por semana, ajustable por el admin. Los períodos son UTC y la semana comienza el lunes. Una clave reemplazada conserva el consumo. Cada respuesta indica los saldos en X-Quota-minute-Remaining, X-Quota-day-Remaining y X-Quota-week-Remaining. También se aplica el límite general por IP. Cacheá las respuestas, evitá consultas simultáneas innecesarias y respetá HTTP 429 y Retry-After. Usá page y pageSize para paginar: la mayoría de los listados acepta hasta 100 elementos por página. Una respuesta de agenda lleva fechas ISO 8601 y timeZone de la sala.

Solicitar acceso y administrar tu clave

Las páginas públicas, el sitemap y el contenido Markdown siguen disponibles para visitas y buscadores. La clave de integración no otorga acceso a datos personales ni a operaciones privadas.

Ejemplo: próximas funciones en Berazategui

curl -sS 'https://teatrina.com/api/integrations/v1/agenda?city=Berazategui&days=30&pageSize=20' -H 'X-API-Key: TU_CLAVE_PRIVADA'
curl -sS -H 'Accept: text/markdown' https://teatrina.com/

Operaciones disponibles

• GET /api/integrations/v1/agenda — Funciones futuras ordenadas cronológicamente. Sólo obras publicadas y salas activas; confirmar novedades en la fuente oficial.
• GET /api/integrations/v1/agenda/ciudades — Localidades con funciones futuras y cantidad de resultados.
• GET /api/integrations/v1/agenda/generos — Géneros con funciones futuras y cantidad de resultados.
• GET /api/integrations/v1/shows — Listado público de obras. No expone datos administrativos ni información de cuentas privadas.
• GET /api/integrations/v1/shows/{slug} — Ficha pública de obras por slug o identificador admitido por el catálogo.
• GET /api/integrations/v1/venues — Listado público de salas y teatros. No expone datos administrativos ni información de cuentas privadas.
• GET /api/integrations/v1/venues/{slug} — Ficha pública de salas y teatros por slug o identificador admitido por el catálogo.
• GET /api/integrations/v1/artists — Listado público de artistas. No expone datos administrativos ni información de cuentas privadas.
• GET /api/integrations/v1/artists/{slug} — Ficha pública de artistas por slug o identificador admitido por el catálogo.
• GET /api/integrations/v1/courses — Listado público de cursos y talleres. No expone datos administrativos ni información de cuentas privadas.
• GET /api/integrations/v1/courses/{slug} — Ficha pública de cursos y talleres por slug o identificador admitido por el catálogo.
• GET /api/integrations/v1/castings — Listado público de castings. No expone datos administrativos ni información de cuentas privadas.
• GET /api/integrations/v1/castings/{slug} — Ficha pública de castings por slug o identificador admitido por el catálogo.
• GET /api/integrations/v1/news — Listado público de noticias. No expone datos administrativos ni información de cuentas privadas.
• GET /api/integrations/v1/news/{slug} — Ficha pública de noticias por slug o identificador admitido por el catálogo.
• GET /api/integrations/v1/videos — Listado público de videos. No expone datos administrativos ni información de cuentas privadas.
• GET /api/integrations/v1/videos/{slug} — Ficha pública de videos por slug o identificador admitido por el catálogo.
• GET /api/integrations/v1/genres — Géneros del catálogo escénico y musical.

Errores y recuperación

Los errores conservan el estado HTTP y devuelven success: false, message y error con code, message y hint. HTTP 400 indica parámetros inválidos; 401/403, acceso restringido; 404, una ruta o ficha inexistente; 429, límite de uso; 500/503, una falla temporal. No trates un 403 o un 503 como prueba de que una obra terminó. Un resultado vacío sólo describe la búsqueda realizada.

Contacto y condiciones

Para corregir una ficha o consultar condiciones de integración, contactá a Teatrina. Consultá la política de privacidad y los términos de uso.