Skip to main content
O conector LinkedIn Ads lê, pela API de Marketing do LinkedIn, as contas de anúncio em que o membro que autorizou o acesso tem papel. Ele traz o cadastro de contas, grupos de campanha, campanhas e criativos, e as métricas diárias por campanha e por criativo.

​
Capacidades

  • Lê todas as contas de anúncio em que o membro que gerou o refresh token tem papel, em qualquer status.
  • Traz ao Data Catalog o cadastro de cada conta: grupos de campanha, campanhas e criativos. Os removidos, arquivados e cancelados entram com o status deles, porque o LinkedIn os mantém enquanto têm dado de desempenho.
  • Traz, por dia e por campanha ou por criativo, impressões, cliques, cliques na página de destino, engajamentos, conversões no site (total, após clique e após visualização), leads do One Click Lead Gen, custo e valor das conversões.
  • Instala 8 tabelas clean prontas, com dinheiro em decimal exato, datas em UTC e totais diários por grupo de campanha e por conta.
  • Alimenta o Memory com os nós AdAccount, AdCampaignGroup, AdCampaign e Ad, ligados na hierarquia da conta, e com o início de cada campanha como evento de linha do tempo. Os rótulos AdAccount, AdCampaign e Ad são os mesmos do Google Ads, e a propriedade source (linkedin_ads) diz de qual plataforma é cada nó. Não há fusão com nós de outros conectores. Os nós só entram no grafo depois que a ontologia unificada é aplicada.

​
Recursos disponíveis

Todo recurso nasce desligado no Data Catalog. Você escolhe quais carregar depois de conectar. As onze métricas são impressions, clicks, landing_page_clicks, total_engagements, external_website_conversions, external_website_post_click_conversions, external_website_post_view_conversions, one_click_leads, cost_in_local_currency, cost_in_usd e conversion_value_in_local_currency.
As 8 tabelas clean do LinkedIn Ads são instaladas quando você cria o conector, fora do contexto. Ligue no Data Catalog as que você quer usar. Cada uma passa a ser atualizada depois de cada sincronização. São elas: linkedin_ads_accounts, linkedin_ads_campaign_groups, linkedin_ads_campaigns, linkedin_ads_creatives, linkedin_ads_campaign_daily, linkedin_ads_creative_daily, linkedin_ads_campaign_group_daily e linkedin_ads_account_daily.

​
Como ler os dados

  • date é o dia em UTC, como a API do LinkedIn entrega. O conector não converte para o fuso da conta.
  • Toda linha traz account_id e currency, a moeda da conta (código ISO 4217). cost_in_local_currency e conversion_value_in_local_currency estão nessa moeda, e o conector não converte entre moedas. cost_in_usd é o custo em dólares que o próprio LinkedIn calcula, a coluna para somar contas de moedas diferentes. Em conta com moeda BRL, o LinkedIn mostra orçamento, lance e gasto em reais e cobra em dólares.
  • Na raw, o dinheiro é o texto decimal que a API envia. Na clean, vira DECIMAL(18,6) na moeda da conta: cost, cost_usd e conversion_value nas tabelas de métrica, daily_budget, total_budget e unit_cost nas de cadastro.
  • Orçamento e lance chegam na raw em *_amount e *_currency. Quando o LinkedIn envia o valor sem código de moeda, como já aconteceu com o orçamento diário de grupos de campanha, *_currency fica NULL e o valor está na moeda da conta. Na clean, o código de moeda recebido ao lado do valor não aparece.
  • Métrica que a API deixa de enviar vale 0. Orçamento ou lance ausente fica NULL, que quer dizer valor desconhecido.
  • Os ids de grupo, campanha e criativo só são únicos dentro da conta. Use as colunas de chave da clean (campaign_group_key, campaign_key, ad_key), que juntam o id da conta e o id do objeto com :.
  • linkedin_ads_campaign_group_daily e linkedin_ads_account_daily são a soma de campaign_metrics. Campanha que a busca de campanhas da conta não devolveu fica com campaign_group_id NULL e forma um balde por conta e dia em linkedin_ads_campaign_group_daily: os grupos mais esse balde somam o total da conta.
  • linkedin_ads_creative_daily não traz a campanha. Chegue nela por campaign_key, em linkedin_ads_creatives.
  • Contas de teste entram no cadastro, com test verdadeiro, e ficam fora das métricas, porque uma conta de teste não veicula anúncios.
  • Horários (created_at, start_at, end_at) saem em UTC. end_at é NULL quando o grupo ou a campanha não tem data de término. As listas de status (serving_statuses, serving_hold_reasons) saem como texto JSON.

​
Permissões (ACL)

Esta fonte não define permissões por registro, então todo mundo que puder usar o conector vê todos os registros. Quem pode usar o conector é definido em Quem pode usar este conector: “Todos os usuários” ou “Apenas times específicos”. O Comportamento dos dados deste conector é sempre “Aberto”.

​
Como a fonte define acesso

No LinkedIn, o acesso é por conta de anúncio. Cada conta tem a lista dos membros com o papel de cada um (VIEWER, CREATIVE_MANAGER, CAMPAIGN_MANAGER, ACCOUNT_MANAGER ou ACCOUNT_BILLING_ADMIN), e a conta é o limite de visibilidade das campanhas dela.

​
Como a Strattum traduz o acesso

A Strattum não grava permissão por item. O conector não lê os membros nem os papéis de cada conta: ele usa a lista de contas do membro que autorizou só para descobrir quais contas ler. O LinkedIn identifica cada membro por um id opaco (urn:li:person), sem e-mail, e a plataforma ainda não tem como ligar esse id a um usuário da Strattum. Todas as contas que a credencial alcança, e todas as linhas delas, ficam visíveis para quem pode usar o conector. O conector não oferece Exigir login na fonte como prova de identidade.

​
Quando a identidade não é encontrada

Não se aplica: nenhuma linha depende da identidade de quem consulta.

​
Quando a permissão é atualizada

Não há permissão da fonte para atualizar. O acesso depende só de Quem pode usar este conector. Para tirar uma conta da Strattum, remova o papel do membro que autorizou nessa conta no LinkedIn, o que também tira o acesso dele a ela. Na execução seguinte, o cadastro da conta sai das tabelas. As métricas já gravadas dela continuam, até um full refresh.

​
Pré-requisitos

  • Um app no LinkedIn Developer Portal com o produto Advertising API aprovado e com o refresh token programático liberado pelo LinkedIn.
  • Um membro do LinkedIn com papel em cada conta de anúncio que você quer ler. O conector só lê, e qualquer papel serve para isso, inclusive VIEWER.
  • Uma só conexão LinkedIn Ads por instalação da Strattum. Ela lê todas as contas que o membro alcança.
  • Alguém para gerar um novo refresh token a cada 365 dias. Veja o aviso em Autenticação e escopos.

​
Autenticação e escopos

A autenticação é OAuth 2.0 de três pernas, de um único membro, com refresh token programático. O conector troca o refresh token por um access token no começo de cada tarefa de sincronização, e no teste de conexão. O access token fica só em memória. O conector não grava nada de volta no cofre: se o LinkedIn devolver um refresh token diferente do cadastrado, o teste e a sincronização avisam. O LinkedIn não documenta rotação do refresh token.
O refresh token vale 365 dias a partir do consentimento, e usá-lo não estende o prazo. Quando vence, o membro precisa autorizar de novo e você cola o novo refresh token no conector. O teste de conexão avisa quando faltam menos de 30 dias. Pedir um conjunto de escopos diferente do já concedido invalida os tokens anteriores do mesmo membro no mesmo app.
1

Prepare o app no LinkedIn Developer Portal

Abra o app que vai ler as contas, ou crie um, e confirme que ele tem o produto Advertising API e o refresh token programático liberados.
2

Copie o Client ID e o Client Secret

Na aba Auth do app, copie o Client ID e o Client Secret.
3

Gere o refresh token

No Token Generator, escolha o app e marque exatamente os escopos r_ads e r_ads_reporting. Autorize com o membro que tem papel nas contas de anúncio e guarde o refresh token devolvido.
4

Confira o papel do membro

No Campaign Manager, confirme que o membro que autorizou tem papel em cada conta que o conector vai ler. Conta sem papel do membro não é lida.

​
Configuração no Console

1

Abra o assistente

Em Conectores, clique em + Nova Conexão e selecione LinkedIn Ads, em Mídia paga.
2

Preencha a conexão

Nome do Conector (Opcional): como a conexão aparece na lista. O padrão é LinkedIn Ads.Client ID (Obrigatório): o Client ID do app do LinkedIn que tem o produto Advertising API.Client Secret (Obrigatório): o Client Secret do mesmo app.Refresh Token (Obrigatório): o token gerado com exatamente os escopos r_ads e r_ads_reporting.
3

Teste a conexão

Clique em Testar Conexão. Você só avança depois de um teste com sucesso ou com aviso. O teste troca o refresh token, lista as contas de anúncio do membro, lê cada uma delas e consulta as métricas dos últimos 7 dias fechados da primeira conta que não é de teste. Quando passa, informa quantas contas leu e quantos dias o LinkedIn informa que faltam para o refresh token vencer. Ele falha quando a credencial é recusada, quando falta o escopo r_ads ou r_ads_reporting e quando o membro não tem papel em nenhuma conta. Conecta com aviso quando só há contas de teste, quando o LinkedIn devolve um refresh token diferente do cadastrado e quando faltam menos de 30 dias para o token vencer.
4

Escolha a frequência

Em Sincronização (Obrigatório), escolha a frequência. O padrão do LinkedIn Ads é uma vez por dia, às 06:00 UTC.
5

Defina o acesso

Em Permissionamento, defina Quem pode usar este conector. O Comportamento dos dados é sempre “Aberto”. Se a política de acesso não for salva junto com o conector, o Console avisa com “Política de acesso pendente”, e o conector fica invisível até você configurá-la nessa mesma aba, na tela de edição.
6

Revise e salve

Em Revisão, confira os dados e salve. O Client Secret e o Refresh Token aparecem mascarados.
7

Ligue os recursos no Data Catalog

No Data Catalog, ligue os recursos e as tabelas clean que você quer carregar. Nos dois recursos de métrica, escolha o modo Incremental na aba Carga: o padrão é full refresh, e a cada execução ele relê os 12 meses de métrica e gasta muito mais da cota diária.

​
Renovar o refresh token

1

Gere um novo refresh token

No Token Generator, gere outro token com os escopos r_ads e r_ads_reporting, com o mesmo app e o mesmo membro.
2

Cole o token no conector

Em Conectores, abra o LinkedIn Ads e cole o valor em Refresh Token. Os campos que você deixa em branco mantêm o valor guardado, então não é preciso digitar o Client ID e o Client Secret de novo. Para testar na tela de edição, preencha os três campos.
3

Salve

Salve a configuração. A próxima execução já usa o novo token.

​
Como a sincronização funciona

A frequência vem do passo Sincronização. O padrão é uma execução por dia, às 06:00 UTC, porque o conector só lê dias fechados em UTC. Na primeira execução, a plataforma limita cada recurso a 1.000 linhas, como amostra. A execução seguinte é completa. Contas. Cada execução descobre as contas uma vez: lista as contas em que o membro tem papel e lê cada uma, em qualquer status. Todos os recursos usam essa lista. Erro da API em qualquer conta falha a execução, para não gravar uma leitura incompleta. Um membro sem papel em nenhuma conta não gera erro na sincronização, e a execução termina com zero linhas. O teste de conexão bloqueia esse caso. Ordem. O conector lê os recursos selecionados um por um, na ordem ad_accounts, campaign_groups, campaigns, creatives, campaign_metrics e creative_metrics, conta por conta, com uma chamada por vez. Recurso desligado no Data Catalog não é lido. Se um recurso falha, a execução para nele e os seguintes não rodam. As tabelas clean só são montadas quando todos os recursos terminam. Cadastro em full refresh. ad_accounts, campaign_groups, campaigns e creatives são reescritos por inteiro a cada execução. Grupos e campanhas são buscados em todos os status e os criativos, sem filtro, então os removidos, arquivados e cancelados continuam como linhas. Um objeto que o LinkedIn deixa de devolver some da tabela na execução seguinte. Métricas. O último dia lido é sempre ontem, em UTC. O dia de hoje nunca entra. Só as contas que não são de teste têm métrica. As consultas saem em blocos de 30 dias, do mais recente para o mais antigo, uma por conta e por bloco. Como a API não pagina e devolve no máximo 15.000 elementos, um bloco que bate esse teto é descartado, partido ao meio e lido de novo, até chegar a um dia.
  • Primeira carga e full refresh: os 12 meses que terminam ontem. Uma conta tem cerca de 13 blocos por recurso de métrica.
  • Incremental: relê os últimos 30 dias fechados e substitui as linhas pela chave de cada linha. A releitura existe porque o LinkedIn atribui conversões com janelas de 1 a 90 dias, então o número de um dia pode mudar depois. Se o recurso ficou desligado ou falhando por mais de 30 dias, a janela começa 29 dias antes do último dia carregado, para que todos os dias desde então sejam lidos.
  • Conta nova: uma conta que entra no alcance do membro depois da primeira carga recebe os 12 meses, mesmo em incremental. Uma conta que sai e volta também.
Remoção. No cadastro, o full refresh reflete a remoção. Nas métricas em incremental, os dias já gravados de uma conta que deixou de ser lida continuam na tabela. Um full refresh os remove. Falhas. A tarefa de extração tenta de novo até 3 vezes, depois de 30, 60 e 120 segundos, só o que uma nova tentativa pode resolver: erro 5xx, queda de conexão e indisponibilidade do endpoint de token. Não repete cota diária esgotada, versão da API fora do ar, credencial recusada, erro 403 nem outro erro 4xx que não seja 408 ou 429.

​
API da fonte

Todas as chamadas só leem dados. O host da API é https://api.linkedin.com, e toda chamada leva o header Linkedin-Version: 202609. As buscas de cadastro paginam por cursor (pageSize e pageToken), com 1.000 grupos, 500 campanhas ou 100 criativos por página. As consultas de métrica pedem as onze métricas no parâmetro fields, porque sem ele a API devolve só impressões e cliques. Rate limits. O LinkedIn aplica duas cotas diárias: uma por aplicativo e uma por membro dentro do aplicativo. Elas reiniciam à meia-noite UTC e os valores não são publicados: aparecem na aba Analytics do app no Developer Portal. A API de métricas tem ainda um teto de 45 milhões de valores de métrica por janela de 5 minutos, longe do que este conector pede, e a troca do refresh token também tem cota diária por aplicativo. Uma conta custa cerca de 7 chamadas por execução incremental, fora a listagem de contas e a troca de token. Em full refresh, ou na primeira carga, cada recurso de métrica soma cerca de 13 blocos por conta. O conector envia uma chamada por vez, com tempo limite de 120 segundos. Diante de um erro 429, espera o Retry-After quando a resposta traz um valor em segundos, senão um recuo que dobra a cada tentativa, de 1 segundo até no máximo 60, com variação aleatória, e tenta de novo até 3 vezes. Esgotadas as tentativas, a cota diária conta como gasta: a execução falha com a indicação de que as cotas reiniciam à meia-noite UTC, sem repetir a leitura. Erros 5xx e quedas de conexão têm até 4 novas tentativas, com o mesmo recuo. Um erro 401 provoca uma nova troca do refresh token, uma vez por chamada. Os erros 403 e 426 nunca são repetidos. Referência oficial: LinkedIn API, rate limiting e LinkedIn Ads, reporting

​
Limitações conhecidas

  • Sem permissão por item: todo usuário que pode usar o conector vê todas as contas que a credencial alcança. Para restringir, limite Quem pode usar este conector.
  • Uma conexão LinkedIn Ads por instalação. O conector lê todas as contas em que o membro tem papel, e não há como escolher contas na Strattum. Para tirar uma conta, remova o papel do membro nela no LinkedIn.
  • O refresh token vence 365 dias depois do consentimento e a renovação é manual. O conector não regrava a credencial e o Console não conduz o consentimento OAuth: quem gera o token é você, no Token Generator.
  • O dia de hoje nunca é lido. Em incremental, a plataforma não regrava na execução seguinte o dia mais recente já carregado. Em uso diário, as releituras seguintes o cobrem. Depois de uma pausa de mais de 30 dias, esse dia fica com o valor da última leitura, até um full refresh.
  • Uma correção na fonte só é capturada enquanto o dia estiver nos últimos 30 dias fechados. Conversão com janela de atribuição maior que 30 dias, que muda depois disso, fica com o número antigo até um full refresh.
  • O histórico vai até 12 meses. Os termos da API de Marketing do LinkedIn dão um ano como prazo de guarda para dados de administração e de relatório de contas de anúncio, e o conector não apaga dias antigos da tabela: a retenção é responsabilidade do cliente. Veja Data Storage Requirements.
  • Conta de teste do LinkedIn não veicula anúncios, então não tem métrica. Recurso de métrica que ainda não teve nenhuma linha relê os 12 meses a cada execução incremental, até a primeira linha aparecer. A API também devolve resposta vazia quando o membro não tem acesso de leitura à conta, então uma tabela de métrica vazia nem sempre é falta de atividade.
  • O criativo traz só os metadados. O texto e a página de destino do anúncio ficam no post que content_reference aponta, e o conector não lê o post.
  • Ficam de fora o direcionamento das campanhas, as métricas por perfil demográfico (cargo, empresa, país e outros), os leads dos formulários, os usuários e papéis de cada conta e a receita atribuída. one_click_leads é só a contagem de leads do dia.
  • Orçamentos, lances e métricas ficam no Data Catalog e não viram propriedade dos nós do Memory.
  • Um único dia de uma conta com 15.000 linhas ou mais numa consulta de métrica falha a execução, porque a API não oferece como ler o resto.
  • Não há conversão de moeda entre contas.
  • O conector usa a versão 202609 da API de Marketing, que o LinkedIn encerra em 15/09/2027. Depois dessa data toda chamada falha, até a plataforma ser atualizada para uma versão vigente. Veja Marketing API, migrations.

​
Troubleshooting

​
Próximos passos

Data Catalog

Ligue os recursos e as tabelas clean do LinkedIn Ads e escolha o modo de carga das métricas.

Memory

Veja como contas, grupos de campanha, campanhas e anúncios entram no grafo.
O conector não lê variáveis do .env. As credenciais são informadas no Console e ficam no cofre de segredos da plataforma, sob os nomes LINKEDIN_ADS_CLIENT_ID, LINKEDIN_ADS_CLIENT_SECRET e LINKEDIN_ADS_REFRESH_TOKEN. Para testar localmente, crie a conexão pelo Console da stack local.