API de Datos de la tarjeta

Descubra tarjetas integradas del catálogo publicado de este entorno, combinado con el inventario del proveedor. La actualización y verificación del esquema se realizan en segundo plano; esta ruta nunca llama al bucket edge. Cada entrada lista su copia actual, su nivel y los diseños permitidos para ese nivel, y cada versión principal servida.

Los JSON Schema autónomos de la versión mayor vigente para los params de colocación y los documentos de datos de tarjeta, el esquema del feed, el nivel, los diseños permitidos y un ejemplo de colocación. Los params marcados como dynamic provienen del documento de datos cuando una colocación asocia una clave data.

Un parámetro de tipo cadena puede incluir {screen.name}, {screen.timezone} y {screen.field.NAME}, y un parámetro location puede ser la cadena {screen.location}; el backend los expande para cada pantalla. Reemplace los valores de contenido de ejemplo antes de publicar. Los identificadores desconocidos responden card_not_found (404).

Un UID global de tarjeta, o un segmento de tipo de catálogo obsoleto. Este último añade encabezados de Deprecación y Advertencia que apuntan a /api/card-types.

If-Match compara opcionalmente la revisión de metadatos de la tarjeta (no su revisión de datos); la omisión actualiza la revisión actual. Idempotency-Key vincula el método, UID, parámetros y If-Match por 24 horas. Un reintento reproduce el resultado grabado, incluyendo 204 tras eliminación; entrada cambiada devuelve idempotency_mismatch. If-Match obsoleto devuelve revision_conflict (412).

Las claves están limitadas al UID de la tarjeta.

If-Match compara opcionalmente la revisión de metadatos de la tarjeta (no su revisión de datos); la omisión actualiza la revisión actual. Idempotency-Key vincula el método, UID, parámetros y If-Match por 24 horas. Un reintento reproduce el resultado grabado, incluyendo 204 tras eliminación; entrada cambiada devuelve idempotency_mismatch. If-Match obsoleto devuelve revision_conflict (412).

Las claves están limitadas al UID de la tarjeta.

Lista los webhooks entrantes de la tarjeta, los más antiguos primero (máximo 20). Los secretos nunca se devuelven aquí.

Crea un webhook que escribe el documento de datos de esta tarjeta: un sistema externo envía un cuerpo JSON o de formulario a su url (POST /api/cards/{id}/kv-webhooks/{webhook_id}/write).

Sin mapeo, el objeto enviado es el documento; una plantilla de mapeo lo construye a partir del cuerpo y se comprueba al guardar. signing true exige además un encabezado ScreenRig-Signature. verify hace que la firma propia de un proveedor (GitHub, Stripe, Shopify, Slack, Linear, Vercel, Asana o cualquier remitente HMAC) autentique un envío en lugar del secreto, que sigue funcionando a su lado; no puede combinarse con signing, y su secreto se sella y nunca se devuelve, solo una pista. handshake nombra un handshake de proveedor al que responde la url (Microsoft Graph, monday.com, Trello o Azure Event Grid; verify slack y asana responden al suyo).

La respuesta es el único lugar donde aparecen el secreto y el secreto de firma (junto con rotate-secret y la actualización que activa la firma): guárdelos de inmediato en el sistema remitente. Una tarjeta tiene como máximo 20 webhooks (kv_webhook_limit_reached). Añade kv_webhook.created.

Un reintento exacto con la misma Idempotency-Key devuelve la misma respuesta, incluidos los secretos, durante veinticuatro horas.

Cambia description, mapping (null lo elimina), enabled, signing, verify (null lo elimina; sin secreto conserva el almacenado cuando el proveedor es el mismo) y handshake (null lo elimina). Activar signing responde el nuevo signing_secret una sola vez; false lo desactiva. Un webhook desactivado responde a cada envío como a un secreto incorrecto. Añade kv_webhook.updated.

Elimina el webhook. Su URL deja de funcionar de inmediato; la tarjeta conserva su documento. Añade kv_webhook.deleted.

Reemplaza el secreto del webhook y devuelve el nuevo una sola vez; con signing true reemplaza en su lugar el secreto de firma. El anterior deja de funcionar de inmediato. Añade kv_webhook.secret_rotated.

El registro de entregas del webhook, las más recientes primero, como máximo 100, conservado siete días.

Cada envío que nombró este webhook es una fila con su hora, resultado (written, unchanged, refused, invalid o handshake), motivo (credentials, signature, signature_missing, signature_invalid, timestamp_missing, timestamp_stale, secret_pending, handshake_invalid, disabled, body, mapping, card_data_invalid, rate_limited, payment_required, internal), un breve detalle como la ruta de datos de tarjeta que falló, el estado de la respuesta, el tamaño del cuerpo y el número de partes de archivo que llevaba un envío multipart (ignoradas).

No se almacena ningún cuerpo, encabezado ni credencial. Aquí es donde un proyecto ve por qué un envío recibió el 404 que comparten todos los rechazos.

La URL a la que un sistema externo envía el documento de datos de una tarjeta. Se autentica con el secreto propio del webhook en el encabezado Authorization: Bearer <secret>, o HTTP Basic con el ID del webhook como nombre de usuario.

Cuando el webhook se creó con verify, una firma válida en el encabezado propio de ese proveedor (vea WebhookVerifyWrite) autentica el envío en lugar del secreto, que sigue funcionando a su lado.

Cuando el webhook firma, también se exige ScreenRig-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>" under the signing secret>, y t debe estar a menos de cinco minutos del reloj del servidor.

Una tarjeta o webhook desconocido, un secreto o una firma incorrectos o ausentes, una marca de tiempo obsoleta, un webhook desactivado y cada GET reciben el mismo 404 not_found; el proyecto ve el motivo en el registro de entregas.

Un webhook configurado para un handshake de proveedor lo responde primero, antes de pedir ninguna credencial, a una solicitud que es ese handshake: el desafío url_verification de Slack (firmado, respondido con el desafío), el validationToken de Microsoft Graph (devuelto como text/plain), el X-Hook-Secret de Asana (devuelto y guardado sellado como secreto de firma de sus eventos), el challenge de monday.com, el SubscriptionValidationEvent de Azure Event Grid (respondido con su validationResponse) y la comprobación HEAD de Trello (la operación head de esta url).

Un handshake no escribe datos de tarjeta, nunca se factura y no gasta presupuesto de velocidad, y se registra en el registro de entregas con el resultado handshake.

El cuerpo, de como máximo 1 MiB, es JSON, application/x-www-form-urlencoded (un nombre repetido es una matriz) o multipart/form-data (cada campo de texto es body.<field>, un nombre repetido es una matriz, y las partes de archivo se ignoran y se cuentan en el registro de entregas). Sin mapeo, el objeto es el documento; con uno, la plantilla lo construye a partir de body y query.

El documento se comprueba como datos de la tarjeta (card_data_invalid nombra la ruta), y uno igual al documento actual no se escribe (estado unchanged). Un envío aceptado es una solicitud de API facturada y añade los eventos de datos de tarjeta. Idempotency-Key (de 8 a 200 caracteres) deduplica los reintentos de un remitente durante veinticuatro horas.

Como máximo 120 envíos por minuto por webhook; cada uno cuenta también para las tasas de escritura de la organización y de la tarjeta (PUT /api/card-data/{key}).

La comprobación que hace Trello de un webhook nuevo. Responde 200 sin cuerpo para un webhook cuyo handshake es trello, y el único 404 not_found para cualquier otro webhook, dirección y solicitud, así que una vista previa de enlace no aprende nada. No escribe nada, nunca se factura y no gasta presupuesto de velocidad; la comprobación respondida figura en el registro de entregas con el resultado handshake.

Cada GET responde el 404 y no lee nada.

Enumera los documentos de datos de tarjeta del proyecto, como máximo 200 en orden ascendente por clave. next_cursor es la última clave devuelta; pásela como after para la siguiente página, null cuando no haya más. Los documentos de datos de tarjeta contienen las propiedades dinámicas de las ubicaciones de tarjetas (secciones de menú, elementos de ticker, mosaicos KPI); la clave de datos de la ubicación nombra una.

Devuelve el documento y su revisión. ETag es la revisión, para If-Match en la siguiente escritura.

Crea o reemplaza un documento de datos de tarjeta. Cuando las ubicaciones de tarjetas en las playlists del proyecto vinculan la clave, el documento debe contener solo las propiedades dinámicas de cada tarjeta vinculada y validar contra ellas; de lo contrario, la escritura se rechaza con card_data_invalid nombrando la tarjeta y la ruta de la propiedad, y no cambia nada. Una clave sin ubicaciones vinculadas acepta cualquier objeto JSON.

Cada cadena que comienza con media: es una referencia de medios, media:<id>, para que una tarjeta dibuje (una foto); en cualquier clave debe nombrar una imagen lista y aprobada en este proyecto, como máximo 256 medios distintos por documento, o la escritura se rechaza con card_media_invalid nombrando la ruta de propiedad y media_id.

Las pantallas cuyo contenido lee la clave pueden luego obtener esos medios desde GET /media/{media_id}. Las pantallas que muestran una ubicación que lee la clave reciben screen.card_data_changed y la vuelven a obtener en su lugar; el registro del proyecto registra kv.updated con un recurso card_data_entry, que nunca llega a un Player.

Los límites, cuotas, mediciones, revisiones y la idempotencia son responsabilidad de la tienda K/V de la aplicación.

Las escrituras de agentes y webhooks también tienen límite de frecuencia, por organización según el plan (Standard y Plus 60 por minuto, Education y Premium 600, Enterprise 3,000) y 60 por minuto por clave en todos los planes; una escritura que supera un límite se rechaza con rate_limited y Retry-After, y no se mide.

Elimina un documento de datos de tarjeta. Una tarjeta vinculada a la clave se oculta en pantalla hasta que se escriba un documento nuevamente.

Lee un documento compartido de feed de terceros: el mismo documento que una tarjeta incorporada con los mismos parámetros lee (docs/feeds.md).

Los parámetros de consulta se normalizan en la clave de feed de la tarjeta, nombrada por el encabezado ScreenRig-Feed-Key: weather, airquality y alerts toman lat y lon (redondeados a una celda de 0,25 grados); earthquakes lat, lon, radius_km (10 a 20000, 500 por defecto), min_magnitude (0 a 9, 2,5 por defecto) y hours (1 a 168, 24 por defecto); cyclones basins (separados por comas at, ep, cp, wp; todos por defecto) y opcionalmente lat, lon y radius_km (las tormentas cercanas a ese lugar); tides station (un ID de estación de predicción de mareas de NOAA, como 9414290) o lat y lon (la estación más cercana en un radio de 100 km, o si no invalid_request); launches ningún parámetro (los próximos lanzamientos en todo el mundo); rates base (una moneda de referencia del BCE, EUR por defecto); crypto symbols (ID de CoinGecko o símbolos, separados por comas, como máximo 20) y currency (usd por defecto); headlines url (una URL RSS o Atom http o https); cap (screenrig.cap/v1) las alertas CAP que corresponden a una pantalla: url (repetible, hasta 5 URL de alertas CAP o de índices ATOM/RSS), public (lee también los feeds públicos que cubren lat y lon; por defecto sin url), lat y lon, geocode (códigos de zona NAME:VALUE repetibles), min_severity, max_severity, min_urgency, min_certainty, event, exclude_event, sender, status (Actual por defecto), scope (Public por defecto), language (repetible, por orden de preferencia) y area_unknown (hide o show); drugalerts (screenrig.drugalerts/v1) los informes de retiradas recientes de un país: country (us, ca o gb, obligatorio) y category (drug, por defecto, o food); respiratory (screenrig.respiratory/v1) la actividad semanal de gripe, COVID-19 y VRS de un lugar: country (us o gb, obligatorio) y region (un estado, territorio o DC de EE. UU. por nombre o código postal, o Inglaterra o una región de la UKHSA; el país si está vacío); almanac (screenrig.almanac/v1) las celebraciones, los acontecimientos de On This Day, el sol y la luna de una fecha para la tarjeta today: country (un código ISO 3166-1 alfa-2, para sus festivos), language (una edición de On This Day: ar, bs, cs, de, en, es, fr, it, pt, ru, sv, tr, uk o zh; en por defecto), opcionalmente lat y lon (redondeados a una celda de 0,1 grados, para el sol) y date (un día fijo; por defecto los días en torno a hoy); outdoorsafety (screenrig.outdoorsafety/v1) el calor para la tarjeta outdoor-safety, una estimación de la temperatura de bulbo húmedo y globo, a partir de lat y lon (la celda de 0,25 grados del tiempo); no informa de rayos; departures (screenrig.departures/v1) las próximas salidas de una a cuatro paradas de un proveedor de datos abiertos: provider (tfl, entur o digitransit) y stops (ID separados por comas, como máximo 4: ID StopPoint de TfL, ID de lugar de parada o andén NSR de Entur, gtfsIds de Digitransit), fusionados en un solo tablero por orden de salida y consultados cada minuto; bikeshare (screenrig.bikeshare/v1) las estaciones de bicicletas compartidas GBFS más cercanas a lat y lon (redondeados a una celda de 0,001 grados, unos 100 m), cada una con su distancia a esa celda, a partir de system (un ID de sistema listado) o, sin él, del sistema listado más cercano que cubre el lugar (invalid_request en system donde ninguno lo cubre).

La solicitud nunca llama al proveedor. 200 es el documento (esquema, fetchedAt, atribución y los campos de la familia, como define el contrato de tarjetas); su ETag es el sha256 de los bytes y If-None-Match responde 304; Cache-Control max-age corre hasta la próxima búsqueda programada. 202 significa que aún no hay documento: se registró la demanda de lectura y el trabajador de alimentación obtiene la clave en aproximadamente un minuto (Retry-After).

Una lectura de API mantiene una clave obtenida durante 24 horas. Una organización registra como máximo 50 claves nuevas al día en todos sus proyectos (rate_limited después de eso). Una familia sin fuente en esta implementación responde not_found.