# Publique e compartilhe

Publicar é a transferência do seu agente de IA para a plataforma mantida: o painel deixa de ser a saída de um agente e passa a ser algo em que sua equipe pode confiar — uma URL estável, governada pelos seus direitos de acesso, que continua respondendo depois que a sessão termina.

## Draft e main são branches reais do git[​](#draft-e-main-são-branches-reais-do-git "Link direto para Draft e main são branches reais do git")

Isto não é uma metáfora. Todo painel é um **repositório git**, mantido como um repositório bare em armazenamento de objetos. Suas edições — do seu agente, do assistente integrado ao app, do editor de código — são commits em um branch **draft**. Publicar faz o merge desse draft em **main**.

Três consequências que vale a pena planejar:

* **Você não pode escrever diretamente em `main`.** Escritas nele são recusadas; a única forma de o conteúdo chegar à versão ao vivo é uma publicação.
* **Toda publicação cria uma tag de versão.** A tag registra o estado em que `main` estava *antes* do merge — então `v1` é o que sua primeira publicação substituiu, `v2` é o que sua segunda publicação substituiu, e a versão atualmente ao vivo é `main`, sem tag até a próxima publicação.
* **Publicações concorrentes fazem merge em vez de se sobrescreverem.** Se `main` avançou enquanto seu draft estava aberto e os dois tocaram arquivos diferentes, as duas mudanças são aplicadas. Se tocaram o *mesmo* arquivo de forma incompatível, a publicação falha com `409 PUBLISH_MERGE_CONFLICT` e nomeia os caminhos em conflito. Ela não escolhe um vencedor silenciosamente.

Você pode ler esse histórico:

```
print(client.viz.list_tags(viz_id))

print(client.viz.get_commit_log(viz_id, "main", max_count=20))

print(client.viz.preview_publish(viz_id))   # diff between draft and main
```

```
console.log(await client.viz.listTags(vizId));

console.log(await client.viz.getCommitLog(vizId, 'main', { maxCount: 20 }));

console.log(await client.viz.previewPublish(vizId));
```

## Publique um painel[​](#publique-um-painel "Link direto para Publique um painel")

Seu agente pode fazer isso diretamente via [MCP](/pt-BR/guides/build-with-your-agent.md); no app é o botão **Publicar**; a partir de código é uma única chamada:

```
client.viz.publish(viz_id)
```

```
await client.viz.publish(vizId);
```

Publicar executa primeiro uma verificação de integridade sobre o último build do painel. Se o bundle está `FAILED` ou desatualizado, a publicação é recusada com um `409` em vez de promover algo que não renderiza — passe `force=true` para sobrepor isso deliberadamente.

A publicação então faz o merge, cria a tag e inicia um build. **O status só se torna `PUBLISHED` quando esse build tem sucesso**; se falhar, o painel cai em `ERROR` e `main` é revertido. Então `publish()` retornar não é o mesmo fato que "o painel está ao vivo" — leia `publishStatus` de volta antes de dizer a alguém que o link funciona. (Mesma regra de [atualização retornando `202`](/pt-BR/guides/keep-your-data-fresh.md#refresh-a-dataset-now): a chamada terminar e o trabalho terminar são duas coisas diferentes.)

## Quem pode abrir — três modos, não dois[​](#quem-pode-abrir--três-modos-não-dois "Link direto para Quem pode abrir — três modos, não dois")

Publicar decide *que* o painel está ao vivo. Um campo separado, `viewMode`, decide *quem* pode abri-lo. Confundir os dois é o erro mais comum aqui.

| `viewMode`  | Quem pode abrir                                                                                                                                                                                         |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `public`    | Qualquer pessoa com o link. Nenhuma conta necessária.                                                                                                                                                   |
| `protected` | Somente um visualizador para quem seu backend gerou um token de incorporação — com filtros por linha específicos para cada visualizador. Veja [Incorporação](/pt-BR/api/embedding-the-share-iframe.md). |
| `private`   | Ninguém fora da sua conta. Publicado, mas inacessível a partir da superfície pública.                                                                                                                   |

O link de um painel publicado se parece com:

```
https://cloud.vibedasher.com/v/<slug>
```

Essa URL só serve conteúdo quando o painel está **ao mesmo tempo** publicado **e** `public`. Um painel `protected` na mesma URL precisa de um token anexado.

### Tornar-se público é controlado separadamente, e um agente não pode fazer isso sozinho[​](#going-public-is-gated-separately-and-an-agent-cannot-do-it-alone "Link direto para Tornar-se público é controlado separadamente, e um agente não pode fazer isso sozinho")

Tornar os dados da empresa legíveis pelo mundo todo é a única coisa irreversível em todo esse fluxo, então ela tem seu próprio controle em vez de andar junto com `publish`. Duas chaves, ambas na conta, ambas verificadas no servidor em toda rota que pode escrever `viewMode`:

* **`allowForPublicViz`** — uma chave de desligamento geral da conta. Desligue-a e nada na conta pode ser tornado público, por ninguém, por nenhuma rota.
* **`apiKeysMayPublish`** — **o padrão é `false`.** Mesmo quando o compartilhamento público é permitido, um chamador autenticado com uma **chave de API** pode não ser quem vira um painel para público. Um admin precisa ativar isso, e só pode fazê-lo a partir de uma sessão de navegador — `PUT /v1/account` recusa defini-la a partir de uma chave de API, então a chave não pode se autoativar.

Essa segunda é o ponto principal. Em qualquer outro lugar desta plataforma, uma chave de API age como o usuário que a criou, com o papel completo desse usuário (veja [Quem pode ver o quê](/pt-BR/guides/who-can-see-what.md)). Publicar na internet aberta é a exceção deliberada: seu agente pode construir o painel, publicá-lo e compartilhá-lo dentro da sua conta, mas por padrão não pode ser a coisa que o torna público. Um humano em um navegador precisa ter dito sim uma vez, no nível da conta.

## O código é congelado; os dados não são[​](#o-código-é-congelado-os-dados-não-são "Link direto para O código é congelado; os dados não são")

Essa é a propriedade que torna um painel publicado algo que vale a pena hospedar, em vez de exportar.

**O código do painel é congelado em um snapshot no momento da publicação.** O bundle é construído uma vez e servido a partir de armazenamento. Seu draft continua evoluindo de forma independente e não vaza para a versão ao vivo até que você publique novamente.

**Os dados são lidos ao vivo no momento da visualização.** Todo gráfico em um painel publicado consulta o conteúdo atual dos seus conjuntos de dados quando alguém o abre. Uma atualização que chega às 3h aparece no painel publicado às 9h, sem nada reconstruído e sem ninguém acompanhando. Essa é exatamente a razão pela qual a metade dos dados vive na plataforma — veja [Mantenha seus dados atualizados](/pt-BR/guides/keep-your-data-fresh.md).

## Despublique e republique[​](#despublique-e-republique "Link direto para Despublique e republique")

`DELETE /v1/viz/{id}/publish` derruba o painel: o status volta para `NOT_PUBLISHED` e o bundle ao vivo é removido. Seu draft permanece intocado.

* **O slug é mantido e continua reservado**, então republicar reutiliza a mesma URL.
* **Links antigos falham de forma inconsistente.** A página do visualizador responde `404`, a API pública responde `403`, e os endpoints de dados em cache respondem `404`. Se você está tratando isso programaticamente, não baseie sua lógica apenas no código de status.
* **Renomear o slug quebra permanentemente todo link existente.** Não há redirecionamento de um slug antigo para um novo. Escolha o slug antes de circular a URL.

## Incorpore-o[​](#incorpore-o "Link direto para Incorpore-o")

Painéis publicados renderizam através de um iframe incorporável que você pode colocar em qualquer app, página de documentação ou site — público, ou controlado por visualizador com filtros por linha. Veja **[Incorporando um painel](/pt-BR/api/embedding-the-share-iframe.md)**.