Conta Azul — conector

Estado: Preview — comportamento pode mudar; sem SLA. Métricas de nuvem (custo faturado, latência): NÃO MEDIDO.

Leia antes: ../conectores.md (mapa de estados) e fichas.md (índice das fichas).

⚠️ Aviso — Preview bloqueado para configuração#

Este conector existe em Preview, mas a configuração/execução está bloqueada hoje:

O conector Conta Azul está em Preview e bloqueado para configuração: a persistência da rotação do refresh token (OAuth) ainda não foi liberada. Sem ela a conexão pararia na primeira renovação.

O que é#

Extrai vendas, produtos, serviços e clientes da API do Conta Azul e carrega na camada Bronze.

Modos de ingestão suportados:

• Nós buscamos — Nós buscamos os dados na sua fonte.

Para que serve#

Trazer os dados de Conta Azul para o seu datalake e disponibilizá-los às camadas Bronze/Silver/Gold, aos modelos de BI e ao wizard de perguntas em linguagem natural.

Quando usar / quando não usar#

Use quando você precisa consolidar esta fonte no datalake de forma agendada, com isolamento por workspace.

Lembre-se de que, em Preview, a liberação geral depende de credencial real e de uma execução controlada, validada manualmente pela nossa equipe.

Plano e permissões#

• Plano: núcleo do produto (conectores fazem parte de todos os planos; o limite é o número de fontes do plano).
• Acesso: exige workspace ativo — com a assinatura em atraso, suspensa ou cancelada, a execução fica bloqueada.
• Desligamento: a execução de ingestão pode ser desligada temporariamente (manutenção ou incidente). Quando isso acontece, a tela informa que o recurso está indisponível no momento.

Pré-requisitos#

• Uma conta Conta Azul com acesso aos dados que você quer ingerir.
• Crie um aplicativo em developers.contaazul.com, autorize-o na sua conta Conta Azul (fluxo OAuth) e informe o Client ID, o Client Secret e o refresh token gerados. Os segredos são cifrados (AES-256-GCM) e nunca são exibidos de novo. Se a autorização expirar, basta reconectar — a fonte e o histórico são preservados.

Credenciais#

Forma de autenticação: OAuth 2.0 (client id/secret + refresh token). Todos os segredos são cifrados (AES-256-GCM) e nunca são exibidos de novo. Se a autorização expirar, basta reconectar — a fonte e o histórico são preservados.

Campos sensíveis. Eles são cifrados (AES-256-GCM) e nunca ficam no config da conexão, na definição do pipeline, no export ou na DAG. Por padrão o valor cifrado fica no banco; mover a credencial desta conexão para o cofre externo de credenciais é uma escolha explícita, feita por conexão depois de salvar — ver ../../administracao/credenciais-e-rotacao.md.

• Client Secret (clientSecret)
• Refresh token (refreshToken) — Emitido no fluxo de autorização OAuth do aplicativo. Se expirar ou for revogado, reconecte a conta — não é preciso recriar a fonte.

Segredos nunca são reexibidos e passam pela redação em todo erro/log (token cru, URL-encoded e em JSON).

Campos do formulário#

Passo a passo#

1. No menu ETL/ELT → Conexões, use Nova conexão.
2. Escolha Conta Azul no catálogo.
3. Preencha os campos do formulário (veja a tabela acima).
4. Use Testar conexão. O resultado vem separado por Rede (alcance do servidor), Autenticação (usuário e senha) e Leitura (listar tabelas) — cada um com OK, Falhou, Não se aplica ou Não testado.
5. Use Salvar conexão. Salvar NÃO inicia ingestão nenhuma.
6. No cartão da conexão, use Montar extração (ou vá em ETL/ELT → Pipelines e use Novo pipeline). O pipeline aponta para a conexão salva — a credencial não é copiada.
7. Na revisão, Publicar (agenda desligada) cria a versão 1 sem executar nada. Depois, Ativar agenda e Executar agora são ações separadas.

No estado atual (Preview bloqueado), salvar/executar é recusado — fale com o suporte para participar do Preview.

Exemplo — teste de conexão#

Configuração de exemplo (todos os valores são fictícios; segredos aparecem mascarados):

# Exemplo sintético (valores fictícios — não são credenciais reais)
clientId = exemplo-client-id-ficticio
clientSecret = •••••• (cifrado — nunca exibido)
refreshToken = •••••• (cifrado — nunca exibido)

Resultado esperado#

O teste pode descrever a fonte, mas salvar/executar é recusado com o motivo do bloqueio (Preview).

Limites e custos#

• Paginação: teto duro por execução (default 10.000 páginas / 5.000.000 linhas); guarda anti-loop.
• Carga SaaS: default batchSize 5.000, maxRows 200.000 por recurso.
• Volume estimado: ~0.5 GB/mês (estimativa de catálogo, não medição).
• Custo: a extração em si não é cobrada pela plataforma; a carga Bronze consome carga no datalake (cobrável). Custo faturado real de nuvem = NÃO MEDIDO.

Segurança#

• Escopo por workspace: cada cliente lê e escreve só no seu próprio datalake (<prefixo>_bronze / _silver / _gold); nunca há vazamento entre workspaces.
• Segredos cifrados: material sensível é cifrado com AES-256-GCM antes de ser gravado. O cofre externo de credenciais é opcional e ligado por conexão; sem ele, o valor cifrado fica no banco. Trocar o valor aqui NÃO revoga a credencial na origem.
• Redaction: todo erro/log passa pela redação de segredos (cru, URL-encoded e em JSON).
• Produção não finge: um caminho que cairia em mock aciona a guarda de produção (falha explícita em vez de simular sucesso).

Erros comuns#

• Autorização expirada/revogada — reconecte a fonte (a fonte e o histórico são preservados; não recrie a fonte).
• Recurso não encontrado — confira o identificador do recurso (planilha/conta/objeto) e as permissões concedidas.
• Limite de requisições (quota) — a extração respeita Retry-After e retenta; picos podem atrasar a execução.

Diagnóstico#

• Use Testar conexão para isolar problemas de credencial/rede antes de agendar.
• Acompanhe as execuções na observabilidade por conector (taxa de erro, p50/p95, freshness).
• Uma mudança de esquema na origem é sinalizada pelo schema drift (coluna nova = info; coluna removida/tipo mudado = atenção).

Relacionados#

• ../conectores.md — catálogo de conectores por estado
• ../ingestao-incremental-backfill.md — full, incremental por watermark, backfill e checkpoint
• ../pipeline-medalhao.md — camadas Bronze/Silver/Gold e qualidade
• ../agendamento-retry-dlq.md — agendamento, retry/backoff e DLQ
• ../custo-limites-seguranca.md — custo, tetos e segurança por workspace

Última revisão: 2026-09-08. Ficha gerada automaticamente do catálogo de conectores do produto.