Integração Customizada

Quando usar

Use este guia quando o seu time precisa enviar dados para a Uncover por uma integração customizada, ou seja, quando os dados não estão disponíveis por uma conexão nativa da plataforma.

Na prática, esse fluxo é indicado quando você mantém os dados em sistemas próprios, pipelines internos, data lakes, data warehouses ou outras fontes que precisam ser disponibilizadas para a Uncover em um formato controlado.

O objetivo é disponibilizar os dados para que a Uncover consiga consumi-los a partir de views ou tabelas no BigQuery.

Como a integração funciona

A integração customizada via GCS conecta 3 partes:

Seu pipeline: gera e envia os arquivos de dados em formato Parquet.
Bucket GCS da Uncover: recebe os arquivos enviados pelo seu time.
BigQuery da Uncover: lê os arquivos do bucket e disponibiliza os dados em tabelas e views para uso na plataforma.

O destino final dos dados é o BigQuery. Depois que os arquivos chegam ao bucket, a Uncover cria uma external table para leitura dos arquivos e uma view para expor a versão mais recente dos dados.

Para consumo na plataforma, a recomendação é usar sempre a view final criada pela Uncover, e não a external table bruta.

Visão geral do fluxo

A integração customizada funciona em 6 etapas:

A Uncover confirma os pré-requisitos com você.
A Uncover provisiona a infraestrutura de recebimento de dados, incluindo bucket, permissões e automações.
A Uncover envia a chave de acesso ao contato técnico informado, seguindo um processo seguro.
Você configura o pipeline de envio recorrente, seguindo o padrão de pastas e arquivos.
A Uncover valida o primeiro envio e cria as tabelas e views no BigQuery.
Com as views prontas, a Uncover conclui a conexão na plataforma.

O que você precisa preparar

Antes de iniciar a configuração técnica, alinhe com a Uncover:

A lista de tabelas que serão enviadas.
O nome exato de cada tabela.
O contato técnico responsável, com nome, cargo, e-mail e telefone.
A frequência de envio dos dados.
Se o envio será sempre completo ou, em caso de inviabilidade, incremental.

Depois, garanta que o seu time consegue:

Gerar arquivos em Parquet.
Automatizar o envio recorrente dos arquivos.
Manter o schema consistente ao longo do tempo.
Autenticar no GCS usando uma Service Account Key (JSON) enviada pela Uncover.
Confirmar o primeiro envio para validação técnica.

Sempre que possível, envie a tabela completa em cada carga. O envio incremental só deve ser usado quando o envio completo não for viável e precisa ser alinhado previamente com a Uncover.

Como devem ser os dados recebidos

Formato dos arquivos

Os arquivos devem ser enviados em formato Parquet.

Esse formato é necessário para que a Uncover consiga criar external tables no BigQuery a partir dos arquivos armazenados no bucket.

Para evitar falhas de leitura:

Use sempre o mesmo formato de arquivo.
Evite enviar CSV, Excel, JSON ou outros formatos nesse fluxo.
Não compacte o arquivo Parquet antes do envio, a menos que isso tenha sido alinhado com a Uncover.

Estrutura de pastas e arquivos

Use este padrão de caminho:

gs://uncover-data-loading-{client_name}/{nome_da_tabela}/_updated_at={timestamp}/{arquivo}.parquet

Cada parte do caminho tem uma função:

{client_name}: identificador da conta, informado pela Uncover.
{nome_da_tabela}: nome exato da tabela. Esse nome vira o diretório da tabela no bucket.
_updated_at={timestamp}: versão do envio. Use um timestamp Unix inteiro, como 1756384304.
{arquivo}.parquet: nome do arquivo. Recomendamos incluir a data ou outro identificador que ajude o seu time a rastrear o envio.

Exemplo:

gs://uncover-data-loading-acme/vendas/_updated_at=1756384304/vendas-2026-04-14.parquet

Nesse exemplo:

acme é o identificador da conta.
vendas é o nome da tabela.
1756384304 é o timestamp Unix do envio.
vendas-2026-04-14.parquet é o arquivo enviado.

O nome do diretório da tabela precisa ser estável. Se o seu time enviar vendas em um dia e vendas_diarias em outro, a Uncover entenderá como tabelas diferentes.

Conteúdo e consistência do schema

Para evitar falhas e retrabalho:

Mantenha o mesmo schema ao longo do tempo, com os mesmos nomes e tipos de colunas.
Evite alterar o tipo de uma coluna já enviada, por exemplo, enviar uma coluna como número em um dia e como texto no outro.
Evite renomear colunas sem alinhamento prévio.
Evite remover colunas sem alinhamento prévio.
Combine previamente com a Uncover qualquer mudança estrutural no dado.

Mudanças de schema podem exigir ajustes nas tabelas, views ou na conexão da plataforma.

Envio completo e envio incremental

Envio completo

No modelo ideal, cada carga contém todos os dados de cada tabela enviada.

Nesse caso, a Uncover usa a partição mais recente, identificada pelo maior _updated_at, para expor a versão atual da tabela na view final.

Use esse modelo sempre que o volume de dados permitir.

Envio incremental

Quando não for viável enviar a tabela completa, o envio incremental pode ser combinado com a Uncover.

Nesse modelo:

Você faz uma primeira carga histórica com dados a partir de uma data acordada.
A partir do dia seguinte, você envia diariamente os dados do dia anterior.
Você informa uma coluna como chave de deduplicação.
Você informa uma coluna como chave de ordenação.
Para compor o dado completo, a Uncover considera todos os envios, ordena pela chave de ordenação e mantém a última ocorrência de cada chave de deduplicação.

O envio incremental é mais sensível a falhas. Use esse modelo apenas quando o envio completo não for viável e depois de alinhar as regras de deduplicação e ordenação com a Uncover.

Passo a passo

1. Confirmar pré-requisitos

A Uncover só inicia o envio de credenciais depois que estes pontos estão confirmados:

Contrato confirmado.
NDA assinado.
Contato técnico validado.
Nomes das tabelas confirmados.
Estrutura esperada dos dados alinhada.

Essas confirmações ajudam a garantir que a chave seja enviada para a pessoa correta e que a infraestrutura seja criada com os nomes e permissões adequados.

2. Receber a chave de acesso

A autenticação no bucket é feita por uma Service Account Key (JSON).

O envio da chave segue um processo seguro:

A chave é compactada em um arquivo .zip com senha forte.
O .zip é enviado por e-mail para o contato técnico responsável.
A senha é transmitida separadamente, via Gmail Confidential Mode.
A Uncover confirma o recebimento e solicita confirmação formal por e-mail.

A senha do .zip nunca deve ser enviada no mesmo canal do arquivo.

A chave permite listagem, escrita e deleção no bucket. Por segurança, ela não permite leitura. Isso significa que não é possível baixar dados previamente enviados.

3. Configurar o pipeline de envio

Depois de receber a chave, configure o pipeline do seu time para:

Gerar o arquivo Parquet.
Gravar o arquivo no diretório correto da tabela.
Incluir o _updated_at como timestamp Unix inteiro no caminho.
Enviar os arquivos para o bucket informado pela Uncover.
Executar o envio com a recorrência combinada.

Checklist rápido antes de enviar

O arquivo está em Parquet.
O diretório {nome_da_tabela} está correto.
O _updated_at é um timestamp Unix inteiro.
O schema está consistente com os envios anteriores.
O envio foi concluído sem erro no pipeline do seu time.

4. Fazer o primeiro upload de teste

Recomendamos que o primeiro envio seja tratado como um teste controlado.

Depois do upload, valide com a Uncover:

Se o arquivo chegou ao bucket.
Se o caminho segue o padrão esperado.
Se o arquivo está em Parquet.
Se o schema pode ser lido corretamente.
Se o nome da tabela está correto.

Se houver erro de path, formato ou schema, ajuste o pipeline e faça um novo envio.

5. Entender o que acontece depois do upload

Para cada tabela enviada, a Uncover cria:

raw__{nome_da_tabela}: external table que lê os arquivos Parquet no bucket.
{nome_da_tabela}: view que expõe a versão mais recente dos dados, com base no maior _updated_at.

Exemplo:

Diretório enviado	External table criada	View para consumo
`vendas`	`raw__vendas`	`vendas`
`clientes`	`raw__clientes`	`clientes`

Use sempre a view ({nome_da_tabela}) para consumir o dado mais recente. A external table raw__{nome_da_tabela} é uma camada técnica de leitura dos arquivos no bucket.

6. Concluir a conexão na plataforma Uncover

Com as views prontas no BigQuery, a Uncover conclui a conexão na plataforma usando o conector de BigQuery.

Nessa etapa, a Uncover pode solicitar validações adicionais, como:

confirmação de quais views devem ser consumidas,
validação de acesso,
conferência de campos esperados,
confirmação de que os dados mais recentes estão aparecendo corretamente.

Prazos

Os prazos abaixo são uma referência para planejamento. Eles começam a contar depois que os pré-requisitos estiverem confirmados: contrato, NDA, contato técnico, nomes das tabelas e estrutura esperada dos dados.

Os prazos podem variar conforme o volume de dados, a complexidade do schema, a disponibilidade do contato técnico e a necessidade de ajustes no primeiro envio.

Prazos por etapa

Etapa	O que precisa estar pronto	Prazo de referência
Envio da chave de acesso	Contrato, NDA, contato técnico, bucket e nomes das tabelas confirmados	De 1 a 3 dias úteis, conforme a prioridade da solicitação
Primeiro upload de teste	Pipeline configurado para gerar e enviar 1 arquivo Parquet no padrão combinado	Depende do prazo interno do seu time
Validação do primeiro envio	Arquivo enviado no bucket, com path, formato e schema corretos	Até 1 dia útil após o primeiro envio, se não houver ajustes no formato
Criação de tabelas e views no BigQuery	Primeiro envio validado e nomes de tabela confirmados	Até 1 dia útil após o envio validado
Conexão na plataforma Uncover	Views prontas e escopo de consumo confirmado	Até 1 dia útil após as views estarem prontas

O prazo mais variável costuma ser o primeiro upload de teste, porque depende da configuração do pipeline pelo seu time técnico.

Problemas comuns

Os problemas mais comuns são:

O arquivo não está em Parquet.
O path não segue o padrão do bucket.
O _updated_at não é um timestamp Unix inteiro.
O schema mudou sem alinhamento prévio.
O primeiro envio não contém dados suficientes para validar a estrutura.
Ter nome de campo igual nome da tabela (no caso nome da tabela vai ser o nome da pasta onde estão os arquivos).
Nome de campo não segue a regra de nomenclatura do BQ:
- Deve conter apenas letras, números e sublinhados (underscore).
- Começar com uma letra ou sublinhado.
- Ter no máximo 300 caracteres.
- Nomes duplicados na mesma tabela, mesmo com diferença de maiúsculas e minúsculas.

Segurança

A chave enviada é uma Service Account Key (JSON) com permissões restritas ao bucket.

A chave permite listagem, escrita e deleção.
A chave não permite leitura.
A chave é exclusiva para envio de dados ao bucket informado pela Uncover.
Não use a mesma chave em outros contextos.
Não compartilhe a chave fora do time responsável pelo pipeline.

Você não consegue baixar arquivos previamente enviados usando essa chave. Essa restrição reduz o risco de exposição de dados já carregados no bucket.

Rotação de chaves

A rotação é obrigatória a cada 90 dias corridos, contados a partir da emissão da chave.

O fluxo é:

D-14: a Uncover avisa sobre a renovação e agenda o envio da nova chave.
D-0: a nova chave é enviada seguindo o mesmo protocolo seguro.
Após a confirmação de que a nova chave está funcionando, a chave anterior é revogada.

Revogação imediata

A chave pode ser revogada antes da rotação em situações como:

encerramento de contrato,
solicitação formal,
suspeita de vazamento ou comprometimento,
mudança de bucket,
mudança de tecnologia,
necessidade de substituição emergencial da credencial.

Ainda com dúvidas? Nossa equipe está pronta para ajudar! Fale conosco pelo suporte ou envie um e-mail para support@uncover.co