Visão geral

A API Microsoft Ads da V4MOS.AI entrega os registros brutos sincronizados das contas Microsoft Ads conectadas à sua organização: contas, campanhas, grupos de anúncios, anúncios, palavras-chave e os relatórios diários de desempenho. As linhas vêm como foram sincronizadas, com os nomes de coluna do data warehouse (snake_case), prontas para levar ao seu BI. Todos os endpoints usam o prefixo /v1/microsoft-ads e seguem a mesma autenticação, paginação e formato de resposta.

Primeiros passosCopiar link da seção

URL base: https://data.v4mos.ai. Toda chamada exige suas credenciais de API e o organizationId — veja Autenticação.

1. Conecte a integração Microsoft Ads em app.v4mos.ai (Contas conectadas) e aguarde a primeira sincronização.
2. Chame qualquer endpoint abaixo com o seu organizationId, por exemplo GET /v1/microsoft-ads/accounts?organizationId=….
3. Toda linha traz integration_id e integration_name: a conta conectada de onde ela veio. Para ler uma conta só, passe esse valor em integrationId.

Endpoints disponíveisCopiar link da seção

• getContas/v1/microsoft-ads/accountsUma linha por conta de anúncios: número, moeda, fuso horário, idioma e status do ciclo de vida.
• getCampanhas/v1/microsoft-ads/campaignsUma linha por campanha: tipo, orçamento, estratégia de lance e configurações de rastreamento.
• getGrupos de anúncios/v1/microsoft-ads/ad-groupsUma linha por grupo de anúncios: tipo, datas, distribuição na rede, estratégia de lance e lance de CPC.
• getAnúncios/v1/microsoft-ads/adsUma linha por anúncio: tipo, status, status editorial, títulos, descrições e URLs.
• getPalavras-chave/v1/microsoft-ads/keywordsUma linha por palavra-chave: tipo de correspondência, status, status editorial, lance e URL final.
• getRelatório de desempenho de campanhas/v1/microsoft-ads/campaign-performance-reportUma linha por campanha por dia, tipo de dispositivo e rede: impressões, cliques, investimento, receita, conversões e assistências.
• getRelatório de desempenho de grupos de anúncios/v1/microsoft-ads/ad-group-performance-reportUma linha por grupo de anúncios por dia, tipo de dispositivo e rede: impressões, cliques, investimento, receita, conversões qualificadas e…
• getRelatório de desempenho de anúncios/v1/microsoft-ads/ad-performance-reportUma linha por anúncio por dia, tipo de dispositivo e rede: impressões, cliques, investimento, receita, conversões qualificadas e…
• getRelatório de desempenho de palavras-chave/v1/microsoft-ads/keyword-performance-reportUma linha por palavra-chave por dia, tipo de dispositivo e rede: impressões, cliques, investimento, receita e conversões.

RecursosCopiar link da seção

Paginação e filtrosCopiar link da seção

• page (padrão 1) e limit (padrão 500, máximo 5000). meta.hasNextPage diz se existe outra página; as linhas vêm sempre na mesma ordem, então avance as páginas até ele ser false.
• dateFrom / dateTo (YYYY-MM-DD, inclusivos) filtram pela coluna de data indicada na tabela acima. Recursos sem coluna de data recusam esses parâmetros.
• integrationId mantém só as linhas de uma conta conectada.
• As respostas ficam em cache por 30 minutos e os dados são sincronizados uma vez por dia — veja Sincronização de dados.

Formato da respostaCopiar link da seção

{
  "data": [{ "...": "um objeto por linha, com as colunas listadas em cada endpoint" }],
  "meta": {
    "page": 1,
    "limit": 500,
    "hasNextPage": true,
    "hasPreviousPage": false
  }
}

Valores monetários e contadores grandes (campos format: decimal e format: int64 no schema de cada endpoint) chegam como texto, por exemplo "125.50", para não perder precisão. Converta para um tipo decimal do seu lado.