Informes y exportaciones

Resúmenes por carpeta y por etiqueta

fleet_health, uptime, publishing y alerts agrupan la flota por carpeta, pantalla o etiqueta en días UTC inclusivos. Una fila de carpeta cuenta cada pantalla que contiene y las de sus carpetas hijas, y la primera fila es el proyecto completo. Las etiquetas son la segunda agrupación: una pantalla cuenta en cada etiqueta que tiene.

GET /api/reports/{kind} genera un informe. from y to son días UTC (por defecto: los últimos 30 días); group_by es folder (por defecto), screen o tag; folder_id limita el informe a una carpeta y a todo lo que contiene, y con direct=true a la carpeta y sus carpetas hijas, o, agrupado por pantalla, a las pantallas que están directamente en ella; tag conserva las pantallas con esa etiqueta. Una fila de carpeta lleva id, parent_id y depth, para que un cliente dibuje el esquema a partir de las filas. La disponibilidad es el tiempo en línea sobre el tiempo registrado, y la cobertura registrada indica qué parte del periodo las pantallas informaron un estado.

La página Salud del panel presenta estos resúmenes según las carpetas de pantallas: cada carpeta se abre a sus subcarpetas y sus pantallas, y cada pantalla a su pestaña Salud.

CSV, XLSX y PDF

Cada ruta de informe acepta format=csv, xlsx o pdf y responde con un adjunto con las mismas filas: los informes nuevos, GET /api/uptime/daily, GET /api/screens/{id}/uptime, GET /api/screens/{id}/health/history, GET /api/health/trend, GET /api/alerts, GET /api/playback, GET /api/playback/plays, GET /api/playback/totals, GET /api/playback/completeness, los informes de entrega, llenado y gasto publicitarios y el informe de una campaña directa. Un informe paginado se escribe completo, hasta 50 000 filas; truncated indica cuándo solo contiene las primeras filas.

El archivo XLSX es una sola hoja con el título y el periodo sobre un encabezado fijo, los números como números y los totales en negrita. El PDF es un estado sobrio con el nombre screenRIG, el proyecto al que va dirigido, el título y el periodo, una tabla cuyo encabezado se repite en cada página, los totales y los números de página, listo para enviar. El CSV empieza con las etiquetas de las columnas y neutraliza una celda de texto que una hoja de cálculo ejecutaría como fórmula.

screenrig reports show fleet_health --group-by folder --format pdf --output fleet-health.pdf
screenrig reports show proof_of_play --advertiser "Acme Corp" --from 2026-10-01 --to 2026-10-31 --format pdf --output acme.pdf
screenrig project uptime --format xlsx --output uptime.xlsx
screenrig alerts list --state all --format csv --output alerts.csv

Prueba de reproducción para un patrocinador o un anunciante

proof_of_play suma las reproducciones de las campañas directas del proyecto. Una reproducción cuenta cuando la pantalla informa que el medio terminó en pantalla. Nombre una campaña con campaign_id, o todas las campañas de un patrocinador o anunciante con advertiser (su nombre exacto, sin distinguir mayúsculas). Cada fila es una campaña, un archivo multimedia y una pantalla con sus reproducciones, horas reproducidas, primer y último día y, cuando la pantalla tiene una estimación de audiencia, impresiones estimadas. El PDF es el estado de cuenta para enviar.

Programaciones de correo

Una suscripción a un informe indica un tipo de informe y sus filtros, una cadencia, un formato de archivo y los miembros del proyecto que lo reciben. POST /api/report-subscriptions crea una; una organización tiene como máximo 50 en todos sus proyectos (report_subscription_limit_reached).

Cada envío cubre el periodo anterior, en días UTC: el día anterior en un envío diario, los siete días anteriores en uno semanal y el mes completo anterior en uno mensual, según el calendario de la zona horaria de la programación. Los destinatarios son miembros del proyecto, comprobados de nuevo en cada envío: cualquier otra persona se rechaza al escribir la suscripción, y un miembro que se va, o cuya dirección no está verificada, deja de recibirlo. El adjunto pesa como máximo 8 MiB.

Un envío que falla se reintenta tras 15 minutos, 1 hora y 4 horas, y luego espera a la siguiente ocurrencia. La suscripción muestra last_status (delivered o failed), last_error, los días que cubrió el último envío y next_run_at. POST /api/report-subscriptions/{id}/send la envía ahora para el periodo que cubriría un envío ahora, sin mover su programación, y responde con la suscripción y el resultado de este envío.

screenrig reports subscriptions create --name "Monday fleet health" --kind fleet_health \
  --cadence weekly --weekday monday --hour 7 --timezone America/Los_Angeles \
  --format pdf --recipients ann@example.com,usr_ID
screenrig reports subscriptions list
screenrig reports subscriptions send rsub_ID

La página Informes del panel tiene las mismas programaciones en Programaciones de correo.

Exportar un proyecto completo

screenrig project export DIR escribe los datos del proyecto en un directorio en formatos abiertos. Revisa el resultado de cada sección antes de usar la copia para recuperar datos.

Conserva los archivos originales de las aplicaciones junto a las exportaciones para recuperar versiones, incluidas las fijadas por listas de reproducción antiguas. Las omisiones de contenido aparecen en la sección de archivos de aplicaciones y establecen data.complete:false con export_application_content_omitted, también con --no-media. Repetir la exportación actualiza los metadatos.

Los datos K/V de las aplicaciones se copian por completo tanto con --no-media como con --since. Si falla la lectura de la lista K/V o de un valor, la sección applications falla con export_section_failed y establece data.complete:false. Resuelve el error de lectura y vuelve a ejecutar la exportación para actualizar la copia.

Las credenciales nunca están en la copia: la clave de firma y la dirección de recepción de un webhook, la credencial de chat o de buscapersonas de una notificación y los secretos de una fuente de datos se dejan fuera (el archivo conserva el origen del receptor y los nombres de los secretos). Volver a ejecutarlo es seguro: los archivos JSON se reescriben completos, un archivo multimedia que ya está completo se conserva y una descarga parcial continúa desde los bytes que tiene. Cada archivo multimedia se comprueba con el SHA-256 que tiene el proyecto antes de conservarse. --no-media omite los archivos multimedia y --since DAY inicia los datos CSV y el registro de eventos en un día. Cada solicitud es una solicitud de API facturada, y las descargas de medios son tráfico de salida.