Guía de incorporación a la API de Google Ads

En esta guía, se detalla el proceso de extremo a extremo para la incorporación, la autenticación y la realización de tu primera llamada a la API de Google Ads.

1. Requisitos previos y jerarquía de la cuenta

Antes de interactuar con la API de Google Ads, debes comprender la jerarquía de la cuenta y tener la estructura de cuenta de nivel superior correcta.

  • Cuenta de administrador (MCC): Una cuenta de administrador de Google Ads (anteriormente Mi centro de clientes) es una cuenta principal que se usa para ver y administrar varias cuentas de cliente. Debes tener una cuenta de administrador para solicitar un token de desarrollador de la API de Google Ads.
  • Cuenta de cliente: Es la cuenta estándar en la que se crean las campañas, los grupos de anuncios y los anuncios, y se configura la facturación.

Elemento de acción: Si no tienes una cuenta de administrador, crea una en Cuentas de administrador de Google Ads.

2. Obtén un token de desarrollador

El token de desarrollador identifica de forma única tu aplicación en la API de Google Ads y controla tu nivel de acceso al volumen de llamadas.

Pasos para postularse

  1. Accede a tu cuenta de administrador de Google Ads.
  2. Navega a Herramientas y configuración > Configuración > Centro de API (o Administrador > Centro de API).
  3. Completa el formulario de detalles del desarrollador y acepta las Condiciones del Servicio de la API.
  4. Envíe su solicitud.

Niveles de acceso

  • Aprobación pendiente: Los tokens recién creados reciben de inmediato el estado "Pendiente". Puedes usar un token pendiente para conectarte a cuentas de prueba de inmediato, pero no funcionará con las cuentas de producción.
  • Acceso básico: Permite hasta 15,000 operaciones de API por día una vez que se aprueba.
  • Acceso estándar: Operaciones de API diarias ilimitadas para aplicaciones que cumplen con las Funcionalidades Mínimas Obligatorias (RMF).

3. Configura cuentas de prueba

El desarrollo y las pruebas en cuentas de producción generan el riesgo de inversión publicitaria no deseada y modificaciones en las campañas. Se recomienda realizar todo el desarrollo activo en cuentas de prueba.

Crea una cuenta de administrador de prueba

  1. Ve a la página de creación de cuentas de administrador de prueba de Google Ads.
  2. Accede con una Cuenta de Google que no esté vinculada a tu cuenta de administrador de Google Ads de producción.
  3. Ingresa un nombre de cuenta descriptivo (p.ej., MyCompany Test MCC).
  4. Selecciona el uso principal como Administrar las cuentas de otras personas.
  5. Elige tu país de facturación, zona horaria y moneda. Haz clic en Guardar y continuar.

Crea una cuenta de cliente de prueba

Una vez que se cree tu cuenta de administrador de prueba, debes crear al menos una cuenta de cliente secundaria para ejecutar campañas de prueba.

  1. Accede a tu cuenta de administrador de prueba recién creada.
  2. En el menú de navegación de la izquierda, haz clic en Cuentas y, luego, selecciona Configuración de la cuenta secundaria (o Rendimiento).
  3. Haz clic en el botón azul + (más) y selecciona Crear cuenta nueva.
  4. Selecciona Cuenta de Google Ads.
  5. Ingresa un nombre de cuenta (p.ej., Test Client Account A).
  6. Selecciona una zona horaria y una moneda, y, luego, haz clic en Guardar y continuar.
  7. Anota el ID de cliente de 10 dígitos (p.ej., 1234567890 sin guiones) de esta nueva cuenta de cliente.

Reglas importantes para las cuentas de prueba

  • Uso del token de desarrollador: No solicites un token de desarrollador desde tu cuenta de administrador de prueba. Usa siempre el token de desarrollador pendiente o aprobado de tu cuenta de administrador de producción.
  • Facturación: Las cuentas de prueba no publican anuncios reales, por lo que no es necesario ingresar datos de facturación reales.

4. Configuración del proyecto de Google Cloud

Todas las solicitudes a la API deben autenticarse con un proyecto de Google Cloud que tenga habilitada la API de Google Ads.

Pasos para habilitar la API

  1. Ve a la consola de Google Cloud.
  2. Crea un proyecto nuevo o selecciona uno existente.
  3. Navega a APIs y servicios > Biblioteca.
  4. Busca API de Google Ads y haz clic en Habilitar.

Precios y facturación

  • Sin tarifas de API: Crear un proyecto de Google Cloud, habilitar la API de Google Ads y generar credenciales de OAuth 2.0 es 100% gratis. Google no cobra ninguna tarifa por llamar o usar la API de Google Ads.
  • Otros recursos de Cloud: Solo incurrirás en tarifas de Google Cloud si usas de forma activa otros servicios facturables de Google Cloud (como Compute Engine, Cloud Run o BigQuery) más allá de los límites del nivel gratuito para alojar tu aplicación o almacenar tus datos de anuncios.

5. Configuración de la autenticación de OAuth 2.0

La API de Google Ads usa OAuth 2.0 para autenticar y autorizar solicitudes.

Pasos para el flujo de aplicaciones de escritorio

  1. En tu proyecto de Google Cloud, ve a APIs y servicios > Pantalla de consentimiento de OAuth y configura la pantalla de consentimiento. Agrega tu dirección de correo electrónico a la sección Usuarios de prueba mientras la app esté en estado de prueba para evitar errores de acceso durante la autorización.
  2. Ve a APIs y servicios > Credenciales.
  3. Haz clic en Crear credenciales > ID de cliente de OAuth.
  4. Selecciona el tipo de aplicación como App de escritorio.
  5. Haz clic en Crear y, luego, descarga el archivo de credenciales de OAuth como client_secret.json (o copia tu Client ID y Client Secret).

Genera un token de actualización

Una vez que tengas tu ID de cliente y tu secreto del cliente, debes generar un token de actualización. Puedes hacerlo con Google OAuth 2.0 Playground o con una secuencia de comandos de la biblioteca cliente.

Método A: Usa Google OAuth 2.0 Playground

  1. Ve a la Google OAuth 2.0 Playground.
  2. Haz clic en el ícono de ajustes (configuración de OAuth 2.0) en la esquina superior derecha.
  3. Marca la casilla Usa tus propias credenciales de OAuth.
  4. Ingresa tu Client ID y Client Secret de OAuth2 y, luego, haz clic en Cerrar.
  5. En Paso 1 (Seleccionar y autorizar APIs) , a la izquierda, ingresa el permiso de la API de Google Ads en el campo "Ingresa tus propios permisos": https://www.googleapis.com/auth/adwords
  6. Haz clic en Autorizar APIs. Cuando se te solicite, accede con la Cuenta de Google que tenga acceso a tu cuenta de administrador de Google Ads (o cuenta de prueba).
  7. Haz clic en Continuar en la pantalla de consentimiento.
  8. En Paso 2 (Intercambiar código de autorización por tokens), haz clic en el botón azul Intercambiar código de autorización por tokens.
  9. Tu Refresh token y Access token se mostrarán en el panel de respuesta. Copia y guarda el Refresh token.

Método B: Usa la secuencia de comandos de la biblioteca cliente (ejemplo de Python)

La biblioteca cliente oficial de Python proporciona una secuencia de comandos de asistencia integrada para generar credenciales. Como alternativa, puedes descargar tu client_secret.json desde la consola de Google Cloud y ejecutar la siguiente secuencia de comandos de Python independiente:

  1. Instala la biblioteca de OAuth requerida:
pip install google-auth-oauthlib
  1. Crea una secuencia de comandos llamada generate_refresh_token.py en el mismo directorio que client_secret.json y ejecútala:
from google_auth_oauthlib.flow import InstalledAppFlow

CLIENT_SECRETS_FILE = "client_secret.json"
SCOPES = ["https://www.googleapis.com/auth/adwords"]

def main():
    flow = InstalledAppFlow.from_client_secrets_file(
        CLIENT_SECRETS_FILE, SCOPES
    )
    credentials = flow.run_local_server(port=0)
    
    print("\nAuthorization Successful!\n")
    print(f"Refresh Token: {credentials.refresh_token}")

if __name__ == "__main__":
    main()

6. Configuración de la biblioteca cliente y las credenciales

Google proporciona bibliotecas cliente compatibles de manera oficial que controlan la autenticación, la serialización y la comunicación con los extremos de gRPC.

Idiomas admitidos

  • Python: pip install google-ads
  • Java: Disponible a través de Maven o Gradle
  • PHP: composer require googleads/google-ads-php
  • .NET: Install-Package Google.Ads.GoogleAds
  • Ruby: gem install google-ads-googleads
  • Perl: cpanm Google::Ads::GoogleAds::Client

Archivo de configuración (google-ads.yaml)

Crea un archivo de configuración que contenga tus credenciales. De forma predeterminada, el método de inicialización de la biblioteca cliente (p.ej., GoogleAdsClient.load_from_storage()) buscará automáticamente google-ads.yaml en dos ubicaciones:

  1. El directorio de trabajo actual desde el que se ejecuta la secuencia de comandos.
  2. Tu directorio principal de usuario (~ en Linux/macOS o %HOMEPATH% en Windows).

Si almacenas el archivo en una ubicación personalizada, puedes pasar de forma explícita la ruta a el método de inicialización (p.ej., load_from_storage("path/to/google-ads.yaml")).

developer_token: "INSERT_YOUR_DEVELOPER_TOKEN_HERE"
client_id: "INSERT_YOUR_OAUTH2_CLIENT_ID_HERE"
client_secret: "INSERT_YOUR_OAUTH2_CLIENT_SECRET_HERE"
refresh_token: "INSERT_YOUR_OAUTH2_REFRESH_TOKEN_HERE"
login_customer_id: "INSERT_YOUR_MANAGER_ACCOUNT_ID_HERE"

7. Realiza tu primera llamada a la API

Para verificar la configuración de incorporación, ejecuta una secuencia de comandos de inicio rápido para recuperar las campañas existentes de tu cuenta de prueba.

Ejemplo de secuencia de comandos de Python (quickstart.py)

import sys
from google.ads.googleads.client import GoogleAdsClient
from google.ads.googleads.errors import GoogleAdsException

def main(client, customer_id):
    ga_service = client.get_service("GoogleAdsService")
    query = """
        SELECT
          campaign.id,
          campaign.name
        FROM campaign
        ORDER BY campaign.id
    """
    
    # Issues a search request
    stream = ga_service.search_stream(customer_id=customer_id, query=query)
    for batch in stream:
        for row in batch.results:
            print(
                f"Campaign with ID {row.campaign.id} and name "
                f"'{row.campaign.name}' was found."
            )

if __name__ == "__main__":
    # Initialize client from google-ads.yaml
    # By default, load_from_storage() searches for 'google-ads.yaml' in the
    # current working directory or the user's home directory (~). You can
    # also pass an explicit path: load_from_storage("path/to/google-ads.yaml")
    try:
        googleads_client = GoogleAdsClient.load_from_storage()
        # Replace with your test client account ID (without hyphens) from
        # Section 3, NOT your manager account ID (which belongs in
        # google-ads.yaml).
        test_customer_id = "1234567890" 
        main(googleads_client, test_customer_id)
    except GoogleAdsException as ex:
        print(
            f"Request failed with status {ex.error.code().name} and "
            f"includes the following errors:"
        )
        for error in ex.failure.errors:
            print(f"\tError with message '{error.message}'.")
            if error.location:
                for field_path_element in error.location.field_path_elements:
                    print(f"\t\tOn field: {field_path_element.field_name}")
        sys.exit(1)

8. Prácticas recomendadas y recursos

  • Registro: Habilita el registro detallado en tu biblioteca cliente para capturar los IDs de solicitud y respuesta (request-id), que son esenciales cuando solicitas asistencia de Google.
  • Manejo de errores: Implementa un manejo de errores sólido para GoogleAdsException, en particular, la administración de límites de frecuencia (RESOURCE_TEMPORARILY_EXHAUSTED).
  • Documentación oficial: Documentación para desarrolladores de la API de Google Ads
  • Bibliotecas cliente y ejemplos de código: Repositorios de Google Ads en GitHub
Anterior
Introducción
Siguiente
Guía de inicio rápido