API de Dados do cartão

Descubra cartões integrados do catálogo publicado deste ambiente, mesclado com o catálogo do fornecedor. Atualizações e verificação de esquema ocorrem em segundo plano; esta rota nunca acessa o bucket edge. Cada entrada lista sua cópia atual, seu nível e os layouts permitidos para esse nível, além de todos os principais servidos.

Os JSON Schemas autocontidos da versão major atual para os params de posicionamento e os documentos de dados do card, o esquema do feed, o nível, os layouts permitidos e um posicionamento de exemplo. Os params marcados como dynamic vêm do documento de dados quando um posicionamento vincula uma chave de dados.

Um parâmetro string pode conter {screen.name}, {screen.timezone} e {screen.field.NAME}, e um parâmetro de localização pode ser a string {screen.location}; o backend os expande para cada tela. Substitua os valores de conteúdo de exemplo antes de publicar. IDs desconhecidos respondem com card_not_found (404).

Um UID global de cartão, ou um segmento de tipo de catálogo obsoleto. Este último adiciona cabeçalhos de Depreciação e Aviso apontando para /api/card-types.

If-Match compara opcionalmente a revisão dos metadados do cartão (não a revisão dos dados); omissão atualiza a revisão atual. Idempotency-Key vincula o método, UID, parâmetros e If-Match por 24 horas. Uma tentativa repete o resultado gravado, incluindo 204 após exclusão; entrada alterada retorna idempotency_mismatch. If-Match obsoleto retorna revision_conflict (412).

As chaves são limitadas ao UID do cartão.

If-Match compara opcionalmente a revisão dos metadados do cartão (não a revisão dos dados); omissão atualiza a revisão atual. Idempotency-Key vincula o método, UID, parâmetros e If-Match por 24 horas. Uma tentativa repete o resultado gravado, incluindo 204 após exclusão; entrada alterada retorna idempotency_mismatch. If-Match obsoleto retorna revision_conflict (412).

As chaves são limitadas ao UID do cartão.

Lista os webhooks de entrada do cartão, do mais antigo para o mais recente (no máximo 20). Os segredos nunca são retornados aqui.

Cria um webhook que grava o documento de dados deste cartão: um sistema externo envia um corpo JSON ou de formulário para a url dele (POST /api/cards/{id}/kv-webhooks/{webhook_id}/write).

Sem mapeamento, o objeto postado é o documento; um modelo de mapeamento o monta a partir do corpo e é verificado ao salvar. signing true também exige um cabeçalho ScreenRig-Signature. verify faz a assinatura própria de um fornecedor (GitHub, Stripe, Shopify, Slack, Linear, Vercel, Asana ou qualquer remetente HMAC) autenticar uma postagem no lugar do segredo, que continua funcionando ao lado; ele não pode ser combinado com signing, e o segredo dele é selado e nunca devolvido, só uma dica dele. handshake nomeia um handshake de fornecedor que a url responde (Microsoft Graph, monday.com, Trello ou Azure Event Grid; verify slack e asana respondem ao deles).

A resposta é o único lugar em que aparecem o segredo e o segredo de assinatura (junto com rotate-secret e a atualização que ativa a assinatura): guarde-os imediatamente no sistema remetente. Um cartão tem no máximo 20 webhooks (kv_webhook_limit_reached). Adiciona kv_webhook.created.

Uma nova tentativa idêntica com a mesma Idempotency-Key retorna a mesma resposta, incluindo os segredos, por vinte e quatro horas.

Altera description, mapping (null o remove), enabled, signing, verify (null o remove; sem segredo, mantém o armazenado quando o fornecedor é o mesmo) e handshake (null o remove). Ligar signing responde o novo signing_secret uma única vez; false o desliga. Um webhook desativado responde a cada postagem como a um segredo errado. Acrescenta kv_webhook.updated.

Exclui o webhook. A URL dele deixa de funcionar imediatamente; o cartão mantém o documento. Adiciona kv_webhook.deleted.

Substitui o segredo do webhook e retorna o novo uma única vez; com signing true, substitui o segredo de assinatura. O antigo deixa de funcionar imediatamente. Adiciona kv_webhook.secret_rotated.

O registro de entregas do webhook, das mais recentes para as mais antigas, no máximo 100, guardado por sete dias.

Cada postagem que nomeou este webhook é uma linha com a hora, o resultado (written, unchanged, refused, invalid ou handshake), o 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), um detalhe curto, como o caminho dos dados do cartão que falhou, o status da resposta, o tamanho do corpo e o número de partes de arquivo que uma postagem multipart trazia (ignoradas).

Nenhum corpo, cabeçalho ou credencial é armazenado. É aqui que um projeto vê por que uma postagem recebeu o 404 que toda recusa compartilha.

A URL para a qual um sistema externo envia o documento de dados de um cartão. Ela se autentica com o segredo próprio do webhook no cabeçalho Authorization: Bearer <secret>, ou HTTP Basic com o ID do webhook como nome de usuário.

Quando o webhook foi criado com verify, uma assinatura válida no cabeçalho próprio desse fornecedor (veja WebhookVerifyWrite) autentica a postagem no lugar do segredo, que continua funcionando ao lado.

Quando o webhook assina, também é exigido ScreenRig-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>" under the signing secret>, e t deve estar a no máximo cinco minutos do relógio do servidor.

Um cartão ou webhook desconhecido, um segredo ou uma assinatura errados ou ausentes, um carimbo de data e hora vencido, um webhook desativado e todo GET recebem o mesmo 404 not_found; o projeto vê o motivo no registro de entregas.

Um webhook configurado para um handshake de fornecedor o responde primeiro, antes de qualquer credencial ser pedida, a uma solicitação que é esse handshake: o desafio url_verification do Slack (assinado, respondido com o desafio), o validationToken do Microsoft Graph (devolvido como text/plain), o X-Hook-Secret do Asana (devolvido e guardado selado como o segredo de assinatura dos eventos dele), o challenge do monday.com, o SubscriptionValidationEvent do Azure Event Grid (respondido com o validationResponse dele) e a verificação HEAD do Trello (a operação head desta url).

Um handshake não grava dados de cartão, nunca é cobrado e não gasta orçamento de taxa, e é registrado no registro de entregas com o resultado handshake.

O corpo, de no máximo 1 MiB, é JSON, application/x-www-form-urlencoded (um nome repetido é um array) ou multipart/form-data (cada campo de texto é body.<field>, um nome repetido é um array, e as partes de arquivo são ignoradas e contadas no registro de entregas). Sem mapeamento, o objeto é o documento; com um, o modelo o monta a partir de body e query.

O documento é verificado como os dados do cartão (card_data_invalid nomeia o caminho), e um igual ao documento atual não é gravado (status unchanged). Uma postagem aceita é uma requisição de API cobrada e acrescenta os eventos de dados do cartão. Idempotency-Key (8 a 200 caracteres) deduplica as novas tentativas de um remetente por vinte e quatro horas.

No máximo 120 postagens por minuto por webhook; cada uma também conta para as taxas de gravação da organização e do cartão (PUT /api/card-data/{key}).

A verificação que o Trello faz de um novo webhook. Ela responde 200 sem corpo para um webhook cujo handshake é trello, e o único 404 not_found para qualquer outro webhook, endereço e solicitação, então um visualizador de links não descobre nada. Ela não grava nada, nunca é cobrada e não gasta orçamento de taxa; a verificação respondida fica no registro de entregas com o resultado handshake.

Todo GET responde o 404 e não lê nada.

Lista os documentos de dados de cartão do projeto, no máximo 200 em ordem crescente pela chave. next_cursor é a última chave retornada; passe-a como after para a próxima página, null quando não houver mais. Documentos de dados de cartão contêm as propriedades dinâmicas das colocações de cartão (seções de menu, itens de ticker, blocos de KPI); a chave de dados da colocação nomeia um.

Retorna o documento e sua revisão. O ETag é a revisão, para If-Match na próxima gravação.

Cria ou substitui um documento de dados de cartão. Quando colocações de cartão nas playlists do projeto vinculam a chave, o documento deve conter apenas as propriedades dinâmicas de cada cartão vinculado e validar contra elas; caso contrário, a gravação é recusada com card_data_invalid nomeando o cartão e o caminho da propriedade, e nada muda. Uma chave sem colocações vinculadas aceita qualquer objeto JSON.

Cada string que começa com media: é uma referência de mídia, media:<id>, para um cartão desenhar (uma foto); em qualquer chave deve nomear uma imagem pronta e aprovada neste projeto, no máximo 256 mídias distintas por documento, ou a gravação é recusada com card_media_invalid nomeando o caminho da propriedade e media_id.

Telas cujo conteúdo lê a chave podem então buscar esses mídias via GET /media/{media_id}. Telas exibindo um posicionamento que lê a chave recebem screen.card_data_changed e buscam novamente no local; o log do projeto registra kv.updated com um recurso card_data_entry, que nunca chega a um Player.

Limites, cotas, medição, revisões e idempotência são do armazenamento K/V da aplicação.

As gravações de agentes e webhooks também têm limite de taxa, por organização conforme o plano (Standard e Plus 60 por minuto, Education e Premium 600, Enterprise 3.000) e 60 por minuto por chave em todos os planos; uma gravação acima do limite é recusada com rate_limited e Retry-After, e não é medida.

Exclui um documento de dados do cartão. Um cartão vinculado à chave fica oculto na tela até que um documento seja escrito novamente.

Lê um documento de feed compartilhado de terceiros: o mesmo documento que um cartão embutido com os mesmos parâmetros lê (docs/feeds.md).

Os parâmetros de consulta são normalizados na chave de feed do cartão, nomeada pelo cabeçalho ScreenRig-Feed-Key: weather, airquality e alerts recebem lat e lon (arredondados para uma célula de 0,25 grau); earthquakes lat, lon, radius_km (10 a 20000, 500 por padrão), min_magnitude (0 a 9, 2,5 por padrão) e hours (1 a 168, 24 por padrão); cyclones basins (separados por vírgula at, ep, cp, wp; todos por padrão) e opcionalmente lat, lon e radius_km (as tempestades perto desse lugar); tides station (um ID de estação de previsão de marés da NOAA, como 9414290) ou lat e lon (a estação mais próxima em 100 km, senão invalid_request); launches nenhum parâmetro (os próximos lançamentos no mundo todo); rates base (uma moeda de referência do BCE, EUR por padrão); crypto symbols (IDs da CoinGecko ou tickers, separados por vírgula, no máximo 20) e currency (usd por padrão); headlines url (uma URL RSS ou Atom http ou https); cap (screenrig.cap/v1) os alertas CAP que correspondem a uma tela: url (repetível, até 5 URLs de alerta CAP ou de índice ATOM/RSS), public (lê também os feeds públicos que cobrem lat e lon; o padrão quando não há url), lat e lon, geocode (códigos de área NAME:VALUE repetíveis), min_severity, max_severity, min_urgency, min_certainty, event, exclude_event, sender, status (Actual por padrão), scope (Public por padrão), language (repetível, em ordem de preferência) e area_unknown (hide ou show); drugalerts (screenrig.drugalerts/v1) os relatórios de recall recentes de um país: country (us, ca ou gb, obrigatório) e category (drug, o padrão, ou food); respiratory (screenrig.respiratory/v1) a atividade semanal de gripe, COVID-19 e VSR de um lugar: country (us ou gb, obrigatório) e region (um estado, território ou DC dos EUA por nome ou código postal, ou a Inglaterra ou uma região da UKHSA; o país quando vazio); almanac (screenrig.almanac/v1) as datas comemorativas, os eventos de On This Day, o sol e a lua de uma data para o cartão today: country (um código ISO 3166-1 alfa-2, para os feriados dele), language (uma edição de On This Day: ar, bs, cs, de, en, es, fr, it, pt, ru, sv, tr, uk ou zh; en por padrão), opcionalmente lat e lon (arredondados para uma célula de 0,1 grau, para o sol) e date (um dia fixo; por padrão os dias em torno de hoje); outdoorsafety (screenrig.outdoorsafety/v1) o calor para o cartão outdoor-safety, uma estimativa da temperatura de bulbo úmido e globo, a partir de lat e lon (a célula de 0,25 grau do clima); ele não informa raios; departures (screenrig.departures/v1) as próximas partidas em uma a quatro paradas de um provedor de dados abertos: provider (tfl, entur ou digitransit) e stops (IDs separados por vírgula, no máximo 4: IDs StopPoint da TfL, IDs de local de parada ou plataforma NSR da Entur, gtfsIds da Digitransit), reunidos em um único painel na ordem de partida e consultados a cada minuto; bikeshare (screenrig.bikeshare/v1) as estações de bicicletas compartilhadas GBFS mais próximas de lat e lon (arredondados para uma célula de 0,001 grau, cerca de 100 m), cada uma com a distância até essa célula, a partir de system (um ID de sistema listado) ou, sem ele, do sistema listado mais próximo que cobre o lugar (invalid_request em system onde nenhum cobre).

A solicitação nunca chama o provedor. 200 é o documento (esquema, fetchedAt, atribuição e os campos da família, conforme definido pelo contrato dos cards); seu ETag é o sha256 dos bytes e If-None-Match responde 304; Cache-Control max-age vai até a próxima busca agendada. 202 significa que ainda não há documento: a demanda registrada de leitura, e o feed worker busca a chave em cerca de um minuto (Retry-After).

Uma leitura de API mantém uma chave buscada por 24 horas. Uma organização registra no máximo 50 novas chaves por dia em todos os seus projetos (rate_limited além disso). Uma família sem fonte nesta implantação responde not_found.