API

API de Google Integrations (GSC + GA4)

OAuth flow, selección de propiedades e importación de datos de Search Console y Analytics.

La API de Google Integrations conecta una cuenta Rankion con Google Search Console (GSC), Google Analytics 4 (GA4) y Google Reviews. El propio OAuth flow corre por la UI web (redirect del navegador a la pantalla de consent de Google — Google no autoriza una autorización puramente API para scopes de offline access), pero todos los pasos posteriores (listar properties, linkearlas, traer datos) son totalmente API-capaces.

Contexto del módulo: Google Integrations.

Connections

Una connection es el resultado de un consent OAuth exitoso — por team puede haber varias (p. ej. una cuenta con acceso a 5 GSC properties).

Method	Endpoint	Descripción
GET	`/v1/google/connections`	Todas las conexiones activas (e-mail, scopes, status)
DELETE	`/v1/google/connections/{id}`	Desconectar + revocar refresh token

curl "$BASE/google/connections" -H "Authorization: Bearer $TOKEN" \
  | jq '.data[] | {id, google_email, scopes, last_synced_at}'

GSC — Search Console

Method	Endpoint	Créditos	Descripción
GET	`/v1/google/gsc/properties`	—	Todas las GSC properties de todas las cuentas conectadas
POST	`/v1/google/gsc/properties/{p}/link`	—	Linkear property a un proyecto Rankion. Body: `{project_id}`
DELETE	`/v1/google/gsc/properties/{p}/link`	—	Deshacer el link
POST	`/v1/google/gsc/properties/{p}/sync`	1	Sync inmediato de los últimos 16 meses de datos de performance
GET	`/v1/google/gsc/properties/{p}/metrics`	—	Clicks, impressions, CTR, position por query/page/fecha

# Linkear GSC property + sync inicial
curl -X POST "$BASE/google/gsc/properties/sc-domain%3Aexample.com/link" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"project_id": 12}'

curl -X POST "$BASE/google/gsc/properties/sc-domain%3Aexample.com/sync" \
  -H "Authorization: Bearer $TOKEN"

{p} es el identificador de property URL-encoded — las domain properties tienen el formato sc-domain:example.com, las URL properties https://example.com/. Ambas deben ir URL-encoded (%3A, %2F).

# Leer métricas de performance
curl "$BASE/google/gsc/properties/sc-domain%3Aexample.com/metrics?from=2026-04-01&to=2026-04-30&dimension=query" \
  -H "Authorization: Bearer $TOKEN" \
  | jq '.data[] | {query, clicks, impressions, ctr, position}'

GA4 — Analytics

Method	Endpoint	Descripción
GET	`/v1/google/ga4/properties`	Todas las GA4 properties (Property ID, Stream Name, Account)
POST	`/v1/google/ga4/properties/{p}/link`	Linkear. Body: `{project_id}`
DELETE	`/v1/google/ga4/properties/{p}/link`	Deshacer link
GET	`/v1/google/ga4/properties/{p}/metrics`	Sessions, users, engagement, conversions

curl "$BASE/google/ga4/properties/properties%2F123456789/metrics?from=2026-04-01&to=2026-04-30&metrics=sessions,users,conversions" \
  -H "Authorization: Bearer $TOKEN" \
  | jq '.data'

Google Reviews

Method	Endpoint	Descripción
GET	`/v1/integrations/google/reviews/status`	Estado de la integración Google Business Profile Review

Los datos de reviews en sí van por la API de Review Sources — este endpoint solo indica si la conexión auth está viva y cuándo fue el último pull con éxito.

Flujo típico

1) UI: el usuario pulsa "Conectar Google" → redirect del navegador → Google Consent → Callback
   → Rankion guarda el refresh token en BD

2) API: GET /google/connections           # muestra: connection existe, scopes ok
3) API: GET /google/gsc/properties        # lista lo que el usuario ha autorizado en GSC
4) API: POST /gsc/properties/{p}/link     # vincula property a proyecto
5) API: POST /gsc/properties/{p}/sync     # sync inicial (1 crédito)
6) API: GET  /gsc/properties/{p}/metrics  # los datos están listos

Notas

OAuth solo por UI. Google no entrega refresh tokens de offline access para flows puramente API sin pasar por la consent screen. Inclúyelo en tu wizard de onboarding.
URL-encode los property identifiers. Si no, sc-domain: se interpreta como un scheme part desconocido (400).
Sync es async-light. /sync arranca un job que corre 30 s – 5 min según el volumen de los 16 meses. last_synced_at en /connections muestra el último run con éxito.
Las cuotas siguen aplicando. Rankion respeta la cuota GSC API (1200 queries/min/proyecto) — al superarla, error de rate limit con header Retry-After.
DELETE de la connection revoca limpio. El refresh token se revoca en Google; un re-link accidental requiere pasar de nuevo por el consent flow.

Relacionado: Rank Tracking · API de Review Sources · Google Integrations.

Letzte Aktualisierung: 1 de mayo de 2026