Furia Reports
Conectar Google Ads por API: developer token, OAuth y MCC
Conectar Google Ads no es solo «iniciar sesión con Google». Hay un developer token que aprueba una persona, una app OAuth que Google verifica y un lío de cuentas gestoras. Guía avanzada de lo que pasa por dentro.
«Inicia sesión con Google» es un tercio del trabajo
En la guía de conexión de Furia Reports, Google Ads es el conector más corto de explicar: entras con Google, autorizas lectura, eliges cuenta. Tres pasos y ni una credencial que copiar. Comparado con WooCommerce o Shopify, donde hay que ir a generar claves a mano, parece el fácil.
Desde el otro lado del cristal es justo al revés: es el más difícil de los seis. Meta te pide una app y el permiso del usuario, y ya estás leyendo datos. Google Ads te pide tres piezas independientes, y una de ellas la aprueba una persona a mano.
Este artículo cuenta esas tres piezas. Si estás integrando la API de Google Ads en tu propia herramienta, te ahorra las dos semanas de descubrirlas por accidente. Y si eres cliente y solo querías entender por qué tu conexión hace lo que hace, la última sección es para ti.
Pieza 1: el developer token (el que aprueba una persona)
El developer token identifica a la aplicación que llama a la API — no a la cuenta que consultas ni al usuario que autoriza. Viaja en una cabecera en cada petición:
developer-token: TU_TOKEN
Authorization: Bearer ya29.a0...
Se solicita desde el API Center, que solo existe dentro de una cuenta gestora (MCC) de Google Ads. Y tiene tres niveles, que es donde está la trampa:
| Nivel | Qué puede leer | Cómo se consigue |
|---|---|---|
| Test | Solo cuentas de prueba | Al instante, al crear el token |
| Basic | Cuentas reales, con un tope diario de operaciones | Solicitud con revisión manual de Google |
| Standard | Cuentas reales, sin ese tope | Se pide después, con la herramienta ya funcionando |
Con el token en nivel de prueba todo el flujo de conexión funciona: el usuario entra con Google, autoriza, ve la lista de sus cuentas y elige una. Es al pedir métricas de esa cuenta real cuando la API contesta que el token no está aprobado. O sea: el error aparece cuando el cliente ya cree que está conectado. Si estás montando esto, prueba con una cuenta real antes de enseñárselo a nadie.
La solicitud de acceso básico es un formulario: qué hace tu herramienta, qué datos lee, quién la usa, si es interna o para terceros. Se responde por correo y no hay plazo garantizado. La causa más común de que te la devuelvan es contestar en genérico — descríbelo como se lo describirías a un cliente, con nombres y casos concretos.
Pieza 2: la app OAuth (y la trampa de los 7 días)
La segunda pieza es un cliente OAuth en Google Cloud: client ID, client secret y una URL de retorno. Nada raro hasta aquí. Lo raro son dos detalles que no salen en el tutorial de turno.
El scope es sensible. Para leer Google Ads se pide https://www.googleapis.com/auth/adwords, que Google clasifica como scope sensible. Traducción: mientras la app no pase verificación, los usuarios ven una pantalla de «Google no ha verificado esta aplicación» y hay un tope de usuarios que pueden autorizarla. Para una herramienta interna da igual. Para una que vendes, esa pantalla te tumba el onboarding — el usuario que iba a conectar sus datos de facturación ve una advertencia de seguridad y se cae del flujo.
Y el estado de publicación caduca tus tokens. Este es el bug fantasma favorito de la casa. Si la pantalla de consentimiento sigue en estado «Testing», los refresh tokens que emite caducan a los 7 días. La integración funciona perfecta toda la semana y el lunes siguiente todos los clientes aparecen desconectados, sin ningún error que lo explique salvo un invalid_grant en los logs. La solución es de un clic — publicar la app en producción — pero encontrarla cuesta días si no sabes que existe.
Para que Google te dé un refresh token hacen falta dos parámetros en la URL de autorización: access_type=offline y prompt=consent. Sin el primero no lo emite; sin el segundo, en las reautorizaciones te devuelve solo un access token de una hora y el usuario tiene que reconectar cada mañana.
Pieza 3: el customer ID y el lío de las cuentas gestoras
Ya tienes token y autorización. Ahora, ¿qué cuentas tiene este usuario? La API responde con listAccessibleCustomers, y aquí llega la sorpresa: solo devuelve las cuentas a las que el usuario accede directamente. Si alguien gestiona 40 cuentas de clientes desde un MCC, esa llamada devuelve una sola cosa: el MCC.
Para llegar a las cuentas de verdad hay que bajar un nivel en la jerarquía, consultando los clientes de esa gestora. Y una vez sabes cuál quieres leer, la petición se parte en dos identificadores:
- El customer ID de la cuenta hija va en la ruta:
/customers/1234567890/googleAds:searchStream. - El ID de la gestora va en la cabecera
login-customer-id.
Mándalo mal — o no lo mandes — y la API responde que no tienes permiso, aunque lo tengas. Es el error que más tiempo hace perder de toda la integración, porque el mensaje apunta a un problema de acceso cuando en realidad es un problema de cabecera.
Un MCC no puede tener campañas, así que pedirle gasto o conversiones devuelve ceros o error según cómo preguntes. Al listar cuentas hay que filtrarlos: si una gestora aparece como opción conectable, el usuario la elegirá tarde o temprano y verá un informe vacío. Nosotros los descartamos antes de pintar la lista, precisamente para que eso no pase.
Los errores que te vas a encontrar
Ordenados por probabilidad de que te toquen la puerta:
| Error | Qué está pasando de verdad | Qué hacer |
|---|---|---|
DEVELOPER_TOKEN_NOT_APPROVED | El token sigue en nivel de prueba y estás pidiendo datos de una cuenta real | Solicitar acceso básico en el API Center |
USER_PERMISSION_DENIED | O el usuario no tiene acceso a esa cuenta, o falta la cabecera login-customer-id | Comprobar la cabecera antes de culpar a los permisos |
invalid_grant (al refrescar) | El refresh token murió: app en «Testing», 6 meses sin uso, contraseña cambiada o acceso revocado | Volver a pedir autorización al usuario |
CUSTOMER_NOT_ENABLED | La cuenta está cancelada o nunca llegó a activarse | Nada que arreglar por API: es un asunto de la cuenta |
QUOTA_ERROR / HTTP 429 | Te pasaste del tope de operaciones | Backoff exponencial y caché — no reintentar en bucle |
La regla que aplicamos con todas las APIs de anuncios vale también aquí: un error de la fuente se cuenta como error. Nunca se rellena con ceros. Un informe que dice «0 €» cuando en realidad la API falló es peor que un informe que no carga, porque el cero se lo cree todo el mundo.
Cómo está montado esto en Furia Reports
Para que se vea el reparto de trabajo, esto es lo que ocurre cuando pulsas «Conectar Google Ads»:
- Te mandamos a Google con el scope de solo lectura,
access_type=offliney unstatealeatorio contra CSRF. - Google nos devuelve un refresh token. Se cifra antes de guardarse; en base de datos no hay ningún token en claro.
- Pedimos tus cuentas accesibles y, si alguna es una gestora, expandimos sus hijas y descartamos las gestoras (que no tienen métricas).
- Eliges qué cuentas quieres ver. Guardamos, por cada una, su customer ID y — cuando cuelga de un MCC — el
login-customer-idque hará falta en cada consulta posterior. - A partir de ahí, cada informe se pide con GAQL y se cachea, para no gastar tu cuota de API en refrescar lo mismo cada pocos minutos.
Lo único que pedimos es lectura. No hay ni un endpoint de escritura en la integración: es imposible que toquemos, pausemos o cambiemos una campaña tuya, aunque quisiéramos.
Si solo querías tus datos, esto no es tu problema
La versión corta para quien usa la herramienta: nada de este artículo es trabajo tuyo. El developer token, la verificación de la app y la gimnasia de las cuentas gestoras son cosa de quien construye la integración. Tú entras con Google, autorizas lectura y eliges cuenta.
Lo cuento por dos motivos. El primero, porque cuando algo falla ayuda saber dónde mirar: si un día tu Google Ads aparece desconectado, ya sabes que lo normal es un refresh token caducado y que se arregla reconectando, no reinstalando nada. Y el segundo, porque «autoriza el acceso de solo lectura» suena a fórmula vacía hasta que ves que detrás hay tres piezas, y que la única que pedimos sobre tu cuenta es la de leer.
¿Quieres seguir por el lado práctico? En cómo hacer un informe de Google Ads que tu cliente entienda está la otra mitad del asunto: qué haces con esos datos una vez los tienes. Y si lo que quieres es sacarlos de la herramienta hacia tu CRM o hacia una IA, eso lo cuenta la API de Furia Reports.
Preguntas frecuentes
¿Qué es el developer token de Google Ads y por qué lo necesito?
Es una cadena que identifica a la aplicación que llama a la API, no a la cuenta que consultas. Va en la cabecera developer-token de cada petición y se solicita desde el API Center de una cuenta gestora (MCC) de Google Ads. Sin él, la API responde con error aunque el usuario haya autorizado correctamente por OAuth. Es la diferencia grande frente a Meta: allí basta con la app y el permiso del usuario; aquí hay una aprobación manual por medio.
¿Cuánto tarda Google en aprobar el developer token?
No hay un plazo garantizado y varía bastante. El token se emite al instante en nivel de prueba (solo funciona contra cuentas de test), y el salto a acceso básico depende de una revisión manual: rellenas un formulario describiendo la herramienta, qué datos lees y quién la usa, y contestan por correo. Puede resolverse en días o pedirte aclaraciones y alargarse. Consejo: pídelo con margen y describe el uso real, sin adornos, porque las respuestas vagas son la causa más común de que lo devuelvan.
¿Por qué mi refresh token de Google deja de funcionar solo?
Cuatro causas habituales, por orden de frecuencia: la pantalla de consentimiento OAuth sigue en modo «Testing» (los refresh tokens caducan a los 7 días), el token lleva seis meses sin usarse, el usuario cambió la contraseña o revocó el acceso a la app desde su cuenta de Google, o has superado el tope de refresh tokens vivos por cliente OAuth y usuario (los más antiguos se invalidan en silencio). El síntoma siempre es el mismo: invalid_grant al refrescar.
¿Necesito una cuenta MCC para usar la API de Google Ads?
Para pedir el developer token, sí: el API Center solo existe en cuentas gestoras. Para consultar datos, no — puedes leer una cuenta suelta si el usuario que autoriza tiene acceso a ella. Lo que sí cambia con un MCC es la llamada: el customer ID de la URL es el de la cuenta hija y el de la gestora va aparte, en la cabecera login-customer-id.
Si uso Furia Reports, ¿tengo que hacer algo de esto?
No. Todo lo de este artículo es trabajo de quien construye la integración, no de quien la usa. En Furia Reports pulsas «Conectar Google Ads», inicias sesión con tu cuenta de Google, autorizas el acceso de lectura y eliges qué cuentas quieres ver. El developer token, la app OAuth verificada y la expansión de las cuentas gestoras están puestos por nosotros.
En Furia Reports conectas Google Ads con dos clics: el developer token, la app OAuth y la expansión del MCC son cosa nuestra. Prueba 5 días sin tarjeta.
