V4MOS.AI API
GuiasReferência da APIapp.v4mos.ai
Google Ads

Visão Geral

Visão geral da API do Google Ads do V4MOS.AI

A API do Google Ads do V4MOS.AI permite que você acesse e gerencie dados de contas, campanhas, grupos de anúncios, anúncios, palavras‑chave, conversões, critérios e segmentações.

Endpoints Disponíveis

Autenticação

Todos os endpoints exigem os headers x-client-id e x-client-secret, além do query parameter organizationId. Veja Autenticação.

Parâmetros Comuns

  • organizationId - ID da organização (obrigatório)
  • userId - ID do usuário
  • page - Número da página (padrão: 1)
  • limit - Limite por página (padrão: 500, máximo: 5000)
  • orderBy - Campo para ordenação
  • orderDirection - Direção da ordenação (ASC/DESC)
  • createdStart - Data/hora inicial (ISO 8601)
  • createdEnd - Data/hora final (ISO 8601)

Todos os endpoints aceitam os parâmetros acima, salvo indicação em contrário.

Detalhes por Endpoint

GET /v1/google/accounts

Retorna contas do Google Ads, incluindo informações básicas e de orçamento.

organizationIdstringqueryobrigatório

ID da organização (obrigatório).

userIdstringquery

ID do usuário (opcional).

createdStartdate-timequery

Data/hora inicial (opcional) em ISO 8601.

createdEnddate-timequery

Data/hora final (opcional) em ISO 8601.

pageintegerquerypadrão: 1

Número da página.

limitintegerquerypadrão: 500

Itens por página (máximo 5000).

orderBystringquery

Campo para ordenação.

orderDirectionstringquerypadrão: DESC

Direção da ordenação. Valores: ASC, DESC.

Exemplo de requisição

cURL
curl -G 'https://data.v4mos.ai/v1/google/accounts' \
  -H 'x-client-id: SEU_CLIENT_ID' \
  -H 'x-client-secret: SEU_CLIENT_SECRET' \
  --data-urlencode 'organizationId=organization_123' \
  --data-urlencode 'createdStart=2024-01-01T00:00:00Z' \
  --data-urlencode 'createdEnd=2024-12-31T23:59:59Z' \
  --data-urlencode 'page=1' \
  --data-urlencode 'limit=100'

Exemplo de resposta

Success
{
  "data": [
    {
      "customer_resource_name": "customers/9991112222",
      "customer_id": "999-111-2222",
      "customer_descriptive_name": "Marca Brasil",
      "customer_currency_code": "BRL",
      "customer_time_zone": "America/Sao_Paulo",
      "customer_status": "ENABLED",
      "account_budget_resource_name": "customers/9991112222/accountBudgets/123",
      "account_budget_status": "APPROVED",
      "account_budget_name": "Orcamento 2024",
      "account_budget_proposed_start_date_time": "2024-01-01T00:00:00Z",
      "account_budget_approved_start_date_time": "2024-01-01T00:00:00Z",
      "account_budget_proposed_spending_limit": 5000000,
      "account_budget_approved_spending_limit": 5000000
    }
  ],
  "meta": { "page": 1, "limit": 100, "hasNextPage": false, "hasPreviousPage": false }
}

GET /v1/google/ads/campaigns

Retorna campanhas com métricas (impressions, clicks, cost, ctr, conversions, roas, etc.).

Exemplo de requisição

cURL
curl -G 'https://data.v4mos.ai/v1/google/ads/campaigns' \
  -H 'x-client-id: SEU_CLIENT_ID' \
  -H 'x-client-secret: SEU_CLIENT_SECRET' \
  --data-urlencode 'organizationId=organization_123' \
  --data-urlencode 'createdStart=2024-01-01T00:00:00Z' \
  --data-urlencode 'createdEnd=2024-12-31T23:59:59Z'

Exemplo de resposta

Success
{
  "data": [
    {
      "campaign_resource_name": "customers/9991112222/campaigns/123456789",
      "campaign_status": "ENABLED",
      "campaign_advertising_channel_type": "SEARCH",
      "campaign_advertising_channel_sub_type": "APP_CAMPAIGN",
      "campaign_name": "Aquisição App",
      "campaign_id": "123456789",
      "campaign_start_date": "2024-01-01",
      "campaign_end_date": "2024-12-31",
      "campaign_optimization_score": 0.87,
      "metrics_clicks": 5600,
      "metrics_impressions": 250000,
      "metrics_ctr": 2.24,
      "metrics_cost_micros": 1234500000,
      "metrics_cost": 1234.5,
      "metrics_conversions": 420,
      "metrics_conversions_value": 25000.0,
      "metrics_roas": 3.5,
      "segments_date": "2024-01-31"
    }
  ],
  "meta": { "page": 1, "limit": 500, "hasNextPage": false, "hasPreviousPage": false }
}

Demais endpoints

  • GET /v1/google/ads/ad-group: grupos de anúncios e métricas.
  • GET /v1/google/ads/ad-group-ads: anúncios por grupo e métricas.
  • GET /v1/google/ads/keywords: palavras‑chave e métricas (impressions, clicks, cost, conversions).
  • GET /v1/google/ads/conversions: conversões agregadas e por tipo.
  • GET /v1/google/ads/age-range: métricas por faixa etária.
  • GET /v1/google/ads/gender: métricas por gênero.
  • GET /v1/google/ads/geographic: métricas por localização.
  • GET /v1/google/ads/conversion-segmented-campaigns: campanhas segmentadas por conversão.
  • GET /v1/google/ads/conversion-segmented-ad-group: grupos segmentados por conversão.
  • GET /v1/google/ads/conversion-segmented-ad-group-ads: anúncios segmentados por conversão.
  • GET /v1/google/ads/campaigns-criterion: critérios de campanha.
  • GET /v1/google/ads/ad-group-criterion: critérios de grupo de anúncios.

Respostas

Todas as respostas seguem o padrão:

{
  "data": [...],
  "meta": {
    "page": 1,
    "limit": 500,
    "hasNextPage": true,
    "hasPreviousPage": false
  }
}

Prefira paginação com limit moderado (100–500) para investigações iniciais e aumente sob demanda.

Introdução à API

Guia para navegar pela referência da API da V4MOS.AI

Contas GET

Próxima página

Nesta página

Endpoints DisponíveisAutenticaçãoParâmetros ComunsDetalhes por EndpointGET /v1/google/accountsGET /v1/google/ads/campaignsDemais endpointsRespostas