Documentaçãode primeiros passos

Arquitetura em três camadas

O caOS separa a origem dos dados do uso que se faz deles. Entender essa separação evita a maior parte das dúvidas de configuração.

Sequência de configuração

A configuração tem uma ordem obrigatória. Cada etapa depende de a anterior estar concluída, e pular uma delas pode produzir um estado silencioso, em que a plataforma não exibe mensagem de erro, mas o dado não circula. Recomendamos seguir rigorosamente esses passos.

• Conectar a plataforma de anúncios por OAuth.
• Adicionar as contas que pertencem a este workspace.
• Etiquetar cada conta com ao menos uma tag.
• Sincronizar as contas com os produtos contratados.
• Configurar o produto: extração no Xtractor, fluxo de mensagens no Pacer, ou plano de mídia no Heimdall.

Entrar na plataforma

Informe o e-mail cadastrado e a plataforma envia um código de seis dígitos, válido por tempo limitado e para uma única autenticação. A sessão permanece ativa no navegador, de modo que o código não é solicitado a cada acesso.

Como não existe senha, também não existe recuperação de senha. Um código que não chega costuma estar na caixa de spam ou retido por filtro corporativo.

Workspace e usuários

Cada workspace representa o ambiente de trabalho da operação, identificado no topo do menu lateral. Em workspaces de time, esses recursos ficam automaticamente disponíveis para todos os membros convidados. Nele, as mesmas contas, tags e fluxos podem ser acessados sem necessidade de reconectar plataformas ou credenciais por usuário. O acesso pode ser concedido como editor ou leitor para membros específicos.

Nos workspaces de time existe uma exceção, tratada na seção do Pacer: o número de WhatsApp usado como remetente é pessoal e não é compartilhado entre os membros do workspace.

Xtractor

Dentro da plataforma, a seção Planos e limites mostra o plano atual e os limites efetivamente aplicados pelo sistema. É a referência a consultar em caso de dúvida.

Pacer

A cobrança é por fluxo de mensagem. Cada fluxo cobre uma conta por plataforma, com até três fluxos simultâneos. A periodicidade é escolhida por fluxo, entre diária, semanal, quinzenal, mensal ou expressão personalizada, no horário que você definir, respeitado o teto de um disparo por dia. O plano Enterprise remove o limite de fluxos e inclui SLA e suporte prioritário.

Heimdall

O Heimdall é um produto exclusivo do plano Enterprise. Por atuar diretamente na contenção de gastos com ações automáticas de pausa nas APIs das plataformas, a ativação exige provisionamento de ambiente dedicado, governança de permissões e onboarding conduzido pela engenharia do caOS.

Percorra a configuração completa

A tela abaixo reproduz a página de Fontes e responde como a real. Percorra as quatro etapas na ordem, ou tente sincronizar antes de aplicar a tag para observar o comportamento descrito adiante.

Conectores disponíveis

A tela de conectores apresenta as integrações liberadas, entre elas Meta Ads, Google Ads, TikTok Ads, Pinterest Ads, Kwai Ads, LinkedIn Ads, Google Analytics, Google BigQuery e Google Sheets. Conectores em desenvolvimento aparecem sinalizados e não podem ser selecionados.

Selecionar um conector abre o fluxo de autorização da própria plataforma de anúncios. O caOS recebe um token de acesso delegado e nunca vê nem guarda a sua senha. Esse token fica cifrado, como descrito em Conectores. A autorização pode ser revogada a qualquer momento, tanto pela plataforma de origem quanto pela aba Credenciais, onde a revogação é permitida ao titular da credencial e aos administradores do workspace.

Aplicar tags

Menu lateral · Fontes · coluna TAGS

Crie a primeira tag em Nova tag e aplique-a pelo botão de adição na linha de cada conta. Uma conta aceita múltiplas tags, e o painel superior exibe o contador COM TAG, que indica quantas contas estão aptas à sincronização.

Modelo de objetos

Montar uma conexão

O formulário abaixo reproduz o construtor de conexões. A etapa de modo de sincronização só é exibida após a seleção do destino, porque as opções disponíveis dependem do tipo de destino escolhido (Google Sheets ou BigQuery).

O modo de sincronização combina duas decisões técnicas: o que buscar na origem (carga completa ou apenas alterações recentes) e como gravar no destino (substituir o bloco, empilhar novas linhas ou atualizar registros existentes removendo duplicatas).

São seis combinações possíveis, configuradas por tabela e não pela conexão inteira. O padrão recomendado é a carga completa com acréscimo deduplicado: essa opção atualiza dados alterados retroativamente pelas chaves primárias e preserva o histórico de relatórios passados.

Criar a fonte de extração

Xtractor · aba Fontes · Nova fonte

O formulário é sequencial e as etapas seguintes são exibidas conforme a anterior é preenchida. Selecione a plataforma, a conta de anúncio e um identificador interno. Plataformas sem credencial ativa aparecem como sem conexão e redirecionam ao fluxo de conexão, retornando ao formulário sem perda do preenchimento.

Em seguida, selecione as tabelas do catálogo. Para relatórios de performance, a tabela de insights concentra investimento, impressões, cliques e conversões. Defina por fim a data inicial da extração; a data final pode permanecer em aberto, caso em que a extração acompanha o período corrente. Ao salvar, a plataforma valida a combinação de campos junto à API de origem.

Criar o destino

Xtractor · aba Destinos · Novo destino

Selecione a plataforma de destino e informe um identificador. Em seguida, autorize a conta Google que terá permissão de escrita e selecione a planilha, pelo seletor do Google ou colando o endereço do documento. O acesso concedido é restrito ao documento selecionado. A gravação é feita por tabela: cada tabela da fonte corresponde a uma aba da planilha.

1. Conectar um número remetente

Pacer · aba Integração WhatsApp · Conectar número

A autenticação é feita por leitura de QR Code, no mesmo modelo do WhatsApp Web. O número é vinculado ao usuário que o autenticou e somente ele pode utilizá-lo como remetente. A restrição impede que um membro do workspace dispare mensagens pelo WhatsApp de outro. Enquanto não houver número próprio conectado, os fluxos podem ser configurados, mas não ativados.

A plataforma monitora a sessão e notifica o proprietário do número caso a vinculação caia, situação em que os disparos são interrompidos até a reconexão.

2. Compor a mensagem

Pacer · aba Fluxos · etapa Template

O editor valida cada tag enquanto você escreve. Tags reconhecidas são destacadas e substituídas pelo valor no envio; tags não reconhecidas são transmitidas como texto literal ao destinatário. Experimente abaixo na simulação inserir uma métrica existente, como por exemplo {{ctr}} e depois digitar uma inexistente.

3. Validar e programar

Pacer · Preview e Disparo

Gerar preview renderiza a mensagem com valores ilustrativos, sem consultar as plataformas e sem enviar nada. Enviar teste executa um disparo imediato com dados reais, permitindo validar conteúdo e destino antes da programação.

Concluída a validação, selecione o número remetente, o destino, que pode ser um contato ou um grupo, e a periodicidade. A ativação em Disparo ativo requer um número remetente próprio selecionado.

O que o Heimdall exige para funcionar

Diferente dos produtos de relatório, proteger orçamento exige uma meta de referência. O Heimdall precisa das contas conectadas em Fontes, das tags aplicadas e do seu plano de mídia adicionado ao Template Operacional: a planilha fornecida no onboarding onde você define a verba planejada de cada conta para o mês.

Três modos de atuação

Você define o nível de autonomia do Heimdall sobre a operação, podendo aplicar um comportamento padrão para o workspace ou personalizar o modo por conta de anúncio:

• Alerta (Simples): o Heimdall apenas notifica a equipe e não realiza nenhuma pausa nas campanhas.
• Gradual (Médio): notifica o time a cada ciclo de verificação. Se a divergência persistir por três avisos seguidos na mesma ocorrência, ele executa a pausa automática.
• Contenção Ativa (Full): executa a pausa imediata assim que a campanha ultrapassa o limite de tolerância configurado.

Margem de tolerância flexível. O gatilho de disparo pode ser configurado por conta ou campanha em valor monetário, porcentagem sobre o orçamento planejado, ou ambos.

Alertas e escopo de atuação

As notificações são enviadas por e-mail e WhatsApp, detalhando a conta, a meta planejada, o ritmo atual e a projeção de entrega. Para os modos Gradual e Contenção Ativa, o canal via WhatsApp é o padrão recomendado para garantir respostas imediatas.

Quando o limite é ultrapassado no modo com pausa ativa, o Heimdall pausa os elementos ativos daquela conta diretamente na API da plataforma de origem. Trata-se de uma trava de contenção para evitar prejuízos orçamentários.