API de Revisões

As revisões do projeto (docs/reviews.md): alterações de playlist e de tela propostas sob acesso Propor, as escritas de campanha, pasta de telas e movimentação que alcançam uma tela protegida (tipo protected_change, docs/screen-scope.md) e, para uma rede de anúncios, os criativos enviados pelos compradores (tipo ad_creative).

Mais recentes primeiro, no máximo limit (padrão 50, no máximo 100) por página; passe next_cursor de volta como cursor com os mesmos filtros. state pending (padrão), decided (todos os outros estados) ou all; kind restringe a um tipo.

Uma sessão de dashboard lê todos os tipos; um token bearer lê os tipos que as suas capacidades cobrem (playlists para playlist_change, screens para screen_change e protected_change, advertising para ad_creative), e um tipo que ele não pode ler é uma página vazia. pending_count conta as revisões pendentes de todos os tipos que o chamador vê.

Um chamador limitado a telas vê apenas as revisões screen_change e protected_change cujo alcance inteiro está dentro do seu escopo (uma revisão que seleciona telas por tag nunca está) e as revisões playlist_change; as revisões ad_creative ficam ocultas para ele, e pending_count conta o que ele vê.

Uma revisão. Uma alteração de playlist adiciona preview: a playlist ao vivo e a proposta no formato armazenado (pages com resolved_media); live é null para uma criação. Um bearer que não pode ler o tipo da revisão (veja listReviews) recebe not_found, assim como um chamador limitado a telas para uma revisão cujo alcance não está dentro do seu escopo.

O projeto ao qual uma revisão pertence, para o link do e-mail: uma pessoa conectada que é membro desse projeto obtém seu id e nome e muda para ele (PUT /api/session/project) antes de ler a revisão. Qualquer outro recebe not_found. Funciona para qualquer projeto selecionado na sessão.

Aprova uma revisão pendente como pessoa que pode aprovar (proprietário do projeto ou membro com can_approve; senão approver_required). A flag é lida novamente dentro da transação da decisão, então uma pessoa cuja aprovação foi desativada no meio não decide nada (approver_required). Sessões shadow da equipe não podem decidir.

Uma atualização de playlist é aplicada com a revisão base como If-Match; quando a playlist ativa avança, a revisão fica obsoleta e a chamada responde review_stale.

Uma criação ou atualização cuja tag, pasta ou todos os seletores agora tocariam mídia que não resolviam quando proposta, que a revisão não nomeia e que a versão ao vivo ainda não toca, também se torna desatualizada (review_stale).

Uma mudança de tela reproduz sua solicitação armazenada (uma tag é resolvida agora): a chamada aplica telas por alguns segundos e o restante continua em segundo plano enquanto screen_change.result.applying é verdadeiro.

Uma mudança de tela aguardando uma revisão pendente da playlist responde review_blocked nomeando-a; uma cuja playlist não tem versão aprovada responde playlist_not_approved. include_dependents também aprova, em ordem, as mudanças de tela aguardando essa revisão da playlist. Eventos da mudança aplicada carregam a pessoa como ator e o agente proponente como agente.

A resposta traz avisos (PlaylistWarning): screen_fact_missing quando a mudança aprovada coloca páginas cujo src de iframe ou params de aplicativo leem um token de tela em telas que não o têm. Uma revisão decidida é review_not_pending; repetir a mesma decisão devolve a mesma resposta.

Uma revisão marcada como protegida (uma protected_change, ou uma screen_change que alcançou uma tela protegida) é decidida por um aprovador diferente do proponente e da pessoa responsável pelo agente proponente: caso contrário, second_approver_required (403), e também quando o proponente não pode ser rastreado até uma pessoa (docs/screen-scope.md).

Um aprovador limitado a telas decide apenas uma revisão cujo alcance inteiro está dentro do escopo (outside_screen_scope, 403). Uma protected_change é aplicada por esta requisição, como a pessoa que aprova, na versão em que foi proposta; uma campanha ou pasta que mudou ou foi removida desde então, ou telas que mudaram desde então, tornam a revisão desatualizada (review_stale, 409).

Um dependente que não pode ser aprovado informa os mesmos códigos em dependents[].problem.

Rejeita uma revisão pendente com um motivo que o proponente lê. Somente aprovador, como approveReview; um aprovador limitado a telas decide apenas uma revisão dentro do seu escopo (outside_screen_scope), e nenhuma pessoa limitada a telas decide uma revisão de criativo de anúncio. Nada muda na tela; uma criação de playlist rejeitada continua não aprovada.

Pede ao proponente alterações com uma nota que ele lê; o proponente propõe novamente. Somente aprovador, como approveReview. Para um criativo de anúncio, o comprador lê a nota no criativo. Um aprovador com escopo é limitado como em rejectReview.

Retira uma revisão pendente de playlist, tela ou protected_change. Um bearer retira apenas o que o seu próprio agente ou cliente de serviço propôs (forbidden caso contrário); uma pessoa retira como aprovador ou como a pessoa responsável pelo proponente; uma pessoa limitada a telas retira apenas uma revisão dentro do seu escopo (outside_screen_scope).

Uma criação de playlist retirada continua não aprovada.