Selo de estado:
Preview(teto atual do produto) · Curso ACD-210 — Conectores e conexões · Aula 7 de 8 · Atualizado em 2026-10-05.
Objetivo#
Ao final desta aula você vai comparar auth (apiKey/token/A1/OAuth2) e limites dos seis conectores SaaS que aceitam cadastro hoje, e saber o que pedir ao cliente antes de abrir a tela.
Vídeo#
Identificador no manifesto: acd-210-07-saas-erp-marketing-crm · duração-alvo 9 min · tela do produto: /conexoes.
Roteiro de gravação (6 capítulos):
| # | Minutagem-alvo | Capítulo | Tela do produto |
|---|---|---|---|
| 1 | 0:00–0:50 | Abertura: título + selo. Os seis são Acesso limitado (Preview) e aceitam cadastro — como quase todo o catálogo hoje (aula 2). O que ainda falta neles é a liberação da extração ao vivo. | /conexoes/nova |
| 2 | 0:50–2:40 | ERP BR: Omie (App Key + App Secret) e Tiny (token da API v2). O que pedir ao cliente. | /sources/new |
| 3 | 2:40–4:20 | NF-e (SEFAZ): certificado A1 em base64 + senha, CNPJ, UF, ambiente. TLS mútuo. | /sources/new |
| 4 | 4:20–6:10 | Anúncios: Meta Ads (token ads_read, adAccountId, level, janela) e Google Ads (OAuth2 + developer token). | /sources/new |
| 5 | 6:10–7:30 | Salesforce: App Conectado, Consumer Key/Secret, refresh token, instanceUrl, objetos padrão. | /sources/new |
| 6 | 7:30–9:00 | O que o SDK comum garante de graça (paginação, checkpoint, retry, redaction); os limites publicados; o "faça você mesmo". | /conexoes |
Conteúdo#
Acesso limitado que
aceita cadastro
Omie, Tiny, NF-e, Meta Ads, Google Ads e Salesforce estão em Acesso limitado (maturidade Preview) e aceitam cadastro hoje — como quase todo o catálogo desde a onda 15. O que "Acesso limitado" autoriza, e quem tem a configuração recusada hoje, se lê na coluna Configuração do catálogo, nunca de memória: é a aula 2. Note também a porta: não existe assistente de conexão para SaaS — eles entram pelo fluxo de fontes do pipeline.
Quatro formas de autenticação, seis conectores
| Conector | Forma de auth | Campos não secretos | Campos secretos 🔒 |
|---|---|---|---|
| Omie ERP | apiKey: par App Key / App Secret | appKey | appSecret |
| Tiny ERP | token da API v2 | — | token |
| NF-e (SEFAZ) | certificado A1 (.pfx/PKCS#12) + senha, para TLS mútuo | cnpj, uf, ambiente (producao/homologacao) | certificadoPfxB64, senhaCertificado |
| Meta Ads | token de acesso de longa duração com ads_read | adAccountId (act_…), level, datePreset, apiVersion | accessToken |
| Google Ads | OAuth 2.0 + developer token | customerId, loginCustomerId (MCC), reportPreset, lookbackDays, clientId | developerToken, clientSecret, refreshToken |
| Salesforce | OAuth 2.0 (App Conectado) | instanceUrl, objects, loginUrl (sandbox) | clientSecret, refreshToken |
O que pedir ao cliente, em uma frase cada: no Omie, as chaves de integração do portal do desenvolvedor; no Tiny, o token da API v2 de Configurações → Token API; na NF-e, o certificado A1 convertido para base64 (base64 -i certificado.pfx) e a senha; no Meta Ads, um token de longa duração com ads_read e o ID da conta de anúncios; no Google Ads, o customer ID, o developer token e um refresh token com escopo adwords; no Salesforce, um App Conectado com escopos api e refresh_token, mais a URL da instância.
O que cada um traz para a Bronze
| Conector | O que é lido |
|---|---|
| Omie · Tiny | Tabelas de negócio: pedidos, produtos, estoque, financeiro |
| NF-e | NF-e distribuídas para o seu CNPJ pela SEFAZ (Distribuição DFe, Ambiente Nacional) |
| Meta Ads | Endpoint de Insights, uma linha por dia, em três tabelas Bronze: meta_ads_campanhas, meta_ads_conjuntos, meta_ads_anuncios |
| Google Ads | Relatórios de desempenho: campanha, grupo de anúncios ou palavra-chave |
| Salesforce | Objetos do CRM via SOQL; vazio = Account, Contact, Opportunity, Lead (aceita customizados __c) |
Duas condições que não dependem de você
Dois conectores dependem de aprovação do provedor, não do produto:
- Meta Ads depende de App Review da Meta (
ads_read) para uso amplo. - Google Ads depende do developer token subir de basic para standard. Enquanto ele não é aprovado, o produto recusa a ingestão em produção, com aviso claro — nunca finge sucesso.
O que o SDK comum garante de graça
Todo conector SaaS é um adaptador sobre o mesmo SDK: ele só escreve testar/descobrir/extrair, e o resto vem da fábrica.
| Peça | Garantia |
|---|---|
| Paginação | Generator com teto duro e guarda anti-loop (cursor que não avança encerra) |
| Checkpoint | Lê antes de extrair, grava a cada lote e limpa ao concluir — a execução seguinte recomeça do zero |
| Retry | Backoff exponencial com jitter determinístico, respeitando Retry-After; retenta só 429/5xx e erro de rede |
| Redaction | Todo erro e log passa pela redação de segredos (cru, URL-encoded e em JSON) — nenhum erro sai com token |
| Métricas | Uma linha de telemetria por operação (linhas/bytes/ms/ok); telemetria nunca derruba a extração |
A mesma bateria de contrato roda contra todos os adaptadores, provando que erro lançado é sempre redigido, métrica sempre emitida e checkpoint retoma sem duplicar nem perder linha.
Os limites que estão publicados — e o que não está
Esta é a parte que mais surpreende em proposta comercial: não existe número de requisições por minuto publicado por conector. O que a ficha publica é:
- Paginação: teto duro por execução, default 10.000 páginas / 5.000.000 linhas, com guarda anti-loop.
- Carga SaaS: default
batchSize5.000 emaxRows200.000 por recurso. - Quota do provedor: tratada por comportamento, não por número — a extração respeita
Retry-Aftere retenta; picos podem atrasar a execução. - Janelas de data (anúncios): Meta Ads com
datePresetemlast_7d·last_14d·last_30d(padrão) ·last_90d·this_month·last_month; Google Ads comlookbackDays(padrão 30). - Custo: chamada à API do provedor = R$ 0 na plataforma; a carga Bronze consome load job do BigQuery (cobrável). Custo faturado real em nuvem = NÃO MEDIDO.
No workspace Aurora Varejo
A Comércio Aurora quer pedidos do ERP e gasto de mídia no mesmo datamart. Maria cadastra o Omie com App Key e App Secret de treino: o secret é cifrado e não volta à tela. Depois o Meta Ads, com adAccountId = act_000000000000000 (sintético), level = campaign e datePreset = last_30d. Perguntada pelo cliente "quantas chamadas por minuto vocês fazem?", ela responde com o que é verificável: a ficha publica o teto de 10.000 páginas / 5.000.000 linhas por execução e batchSize 5.000 / maxRows 200.000 por recurso, e a extração respeita Retry-After quando o provedor limita — número de requisições por minuto não é publicado. Honestidade com números no lugar de promessa sem lastro.
Erros comuns
| Sintoma | Causa provável | O que fazer |
|---|---|---|
| Autorização expirada/revogada | Token ou refresh token sem validade | Reconecte a fonte — a fonte e o histórico são preservados; não recrie |
| Recurso não encontrado | Identificador errado (conta, planilha, objeto) | Confira o identificador e os escopos concedidos no provedor |
| Limite de requisições (quota) | Pico no provedor | A extração respeita Retry-After e retenta; a execução pode atrasar |
| ERP/Fiscal recusa | App Key/Secret, token ou certificado errados | Valide a credencial no painel do ERP; na NF-e, confira o .pfx e a senha |
| Meta Ads / Google Ads não autoriza | App Review ou developer token pendentes | Aguarde a aprovação; em produção o Google Ads recusa até o token subir |
| Descoberta não lista o esperado | Escopo insuficiente | Conceda o escopo de leitura necessário no provedor |
| Erro parece conter token | Nunca deveria | Segredos são redigidos; se um token apareceu em log/URL, rotacione e trate como incidente Crítico |
Preview, e o que isto não faz
Os seis estão em Preview: comportamento pode mudar, sem SLA, e a liberação geral depende de credencial real e de execução controlada validada manualmente — é o gate humano da aula 2. Esta aula cobre estes seis; para qualquer outro conector, o que vale é a condição publicada na página dele, lida na hora. E nenhum destes conectores escreve de volta na origem: o fluxo é só de leitura para a Bronze.
Faça você mesmo#
No workspace de treino Aurora Varejo, como dono, com identificadores sintéticos. Não use credencial real de cliente.
- Abra a ficha do Omie e vá à seção Limites e custos. Transcreva os três números publicados: teto de páginas, teto de linhas e os defaults de
batchSize/maxRows. - Na mesma ficha, ache em Erros comuns a linha de limite de requisições (quota) e transcreva o comportamento declarado (
Retry-After+ retentativa). Escreva, em uma frase, por que isso não é um "rate limit por minuto" — a ficha não publica esse número. - Monte uma tabela de uma coluna por conector, com a forma de auth de cada um dos seis: Omie, Tiny, NF-e, Meta Ads, Google Ads, Salesforce. Confira contra as fichas de Tiny, NF-e, Meta Ads, Google Ads e Salesforce.
- Em
/conexoes, use Nova conexão, busque Omie ERP e confirme que o cartão é clicável (Acesso limitado que aceita cadastro). Depois ache, no mesmo catálogo, um cartão sem link e transcreva o motivo que a tela dá — é o contraste que importa, e quem está em cada lado muda com o tempo. - Siga a porta indicada pelo cartão e preencha
appKeycom um valor de treino; confirme que o campo App Secret é do tipo segredo e que a tela diz que ele não será reexibido. Cancele sem salvar. - Repita a leitura de campos para NF-e: confirme que
cnpj,ufeambientesão não secretos e que certificado e senha são secretos. Anote o comando de conversão do.pfxpara base64 que a ficha publica. - Para o Google Ads, escreva a condição que não depende de você (developer token aprovado) e o que o produto faz enquanto ela não é atendida.
Você terminou quando você tem os limites do Omie transcritos da ficha (incluindo a constatação de que o número de requisições por minuto não é publicado), a tabela das quatro formas de auth cobrindo os seis conectores, e a condição de provedor dos dois conectores de anúncios identificada.
Checagem rápida#
Três perguntas no final da aula, corrigidas no servidor. A aula só conta como concluída depois da checagem.
Documentação relacionada#
- data/conectores/omie
- data/conectores/tiny
- data/conectores/nfe
- data/conectores/meta_ads
- data/conectores/google_ads
- data/conectores/salesforce
- data/conectores — o SDK comum e a certificação
Capacidades ensinadas#
C09.1 · C10.1 — o selo exibido na aula é sempre o estado mais conservador entre as capacidades citadas; nada aqui é "GA".