Dirección de producción y primera llamada
Inicia sesión en la aplicación enhttps://app.sorank.com. Administra las claves en https://app.sorank.com/settings/api y envía las solicitudes a https://app.sorank.com/api/public/v1. No tienes que crear un servidor API.
- Abre Configuración → Acceso API y crea una clave con nombre, al menos un sitio, Ver sitios (
profiles:read) y fecha de vencimiento. Añade Ver cuotas (quotas:read) para la segunda llamada. - Copia ahora la clave completa: solo se muestra una vez. El prefijo visible después no sirve para autenticarte.
- Elige un ejemplo. Con cURL, introduce la clave cuando se solicite. Para JavaScript o Go, configura
SORANK_API_KEYen el entorno del proceso servidor. La pestaña HTML incluye un servidor Node.js local: ejecútalo con la clave en su entorno y abrehttp://127.0.0.1:3100. Nunca incluyas la clave en HTML o JavaScript del navegador. Añade la autenticación de tu aplicación antes de usar este patrón fuera de la demo local.
- cURL
- HTML
- JavaScript
- Go
data. Usa un valor data[].id como profile_id en las siguientes llamadas. Si la lista está vacía, comprueba los sitios elegidos y tus permisos. Los ejemplos de cURL, JavaScript y Go también leen la cuota del primer perfil con quotas:read.
La Referencia de la API pública en la navegación para desarrolladores detalla rutas, scopes y respuestas.
Autenticarse
Crea una clave personal en Configuración → Acceso API para tus scripts o autoriza un cliente OAuth con PKCE S256. Limita los perfiles y scopes a lo necesario. Envía el token como Bearer. Las cookies del navegador y los tokens de Supabase no sirven aquí. Para una aplicación que actúe en nombre del usuario, empieza porhttps://app.sorank.com/.well-known/oauth-protected-resource/api/public/v1 y https://app.sorank.com/.well-known/oauth-authorization-server. Descubre los endpoints OAuth anunciados, registra un cliente público si hace falta y usa authorization code con PKCE S256, los scopes necesarios y el recurso exacto https://app.sorank.com/api/public/v1. Un token OAuth de MCP no sirve para REST.
Permisos y cuota
ConsultagetQuotas antes de generar contenido. El ejemplo requiere profiles:read, quotas:read, calendar:read, calendar:write, articles:read, articles:generate y articles:publish. Crear un calendario también requiere permisos de generación y publicación. La aplicación, REST y MCP comparten la cuota; más claves no la amplían.
Los permisos de lectura Ver productos (products:read), Ver analíticas (analytics:read), Ver visibilidad IA (geo:read) y Ver ajustes (settings:read) nunca consumen cuota. Editar ajustes (settings:write) cambia los mismos ajustes que la aplicación; concédalo solo si una integración debe modificarlos.
Comprobar la elegibilidad
La API está disponible cuando ha completado el onboarding en Sorank y el sitio tiene una suscripción válida. Un colaborador de agencia usa la suscripción del propietario del sitio. Sorank lo comprueba al crear una clave o aprobar una conexión OAuth, y de nuevo en cada solicitud.listProfilessolo devuelve los sitios elegibles.- Un onboarding sin terminar devuelve
403 onboarding_required. - Un sitio sin suscripción válida devuelve
402 subscription_required, condetails.reason(paused,past_due,incompleteoinactive) cuando se conoce.
Leer productos, analíticas, visibilidad IA y ajustes
Estas lecturas devuelven lo que la aplicación Sorank le muestra. Nunca inician un análisis, una sincronización ni una generación.- Productos (
products:read):listProductsrecorre el catálogo de productos con un cursor. Tras409 product_catalog_cursor_stale, vuelva a empezar desde la primera página. - Analíticas (
analytics:read): rendimiento, consultas, páginas, países y dispositivos de Search Console, y tráfico de Google Analytics procedente de asistentes de IA.startyend(YYYY-MM-DD) son obligatorios. Cada llamada consulta Google en directo y tiene un límite de frecuencia más bajo. Conecte primero Google en Sorank; si no, recibirá409 gsc_not_connectedo409 ga_not_connected, y403 google_access_lostsi se perdió el acceso. - Visibilidad IA (
geo:read): estadísticas GEO, evolución de las menciones, cronología de citas, fuentes que citan el sitio y competidores citados en un análisis. - Ajustes (
settings:read):getSettingsdevuelve el sitio, el brief de negocio con surevision, los competidores, los valores predeterminados de artículos, los visuales y el canal de YouTube.
Cambiar los ajustes
Consettings:write puede cambiar el nombre de la empresa, el color de marca y el mercado, sustituir el brief de negocio y la lista de competidores, cambiar los valores predeterminados de los artículos del calendario, el modo de imagen y las portadas, y conectar, pausar o desconectar el canal de YouTube. La URL del sitio no se puede cambiar mediante la API (400 field_not_writable).
Cada cambio requiere un Idempotency-Key. La respuesta contiene los ajustes resultantes, un recibo y una lista effects con los procesos iniciados en segundo plano, como en la aplicación: geo_questions_regeneration_queued, backlink_refresh_queued, calendar_slots_shifted, image_gallery_analysis_queued, youtube_sync_queued o youtube_purge_queued.
Para sustituir el brief de negocio, envíe la expected_revision leída en getSettings. Si el brief cambió entretanto, recibirá 409 business_brief_revision_conflict: vuelva a leer los ajustes antes de reintentar.
Probar un flujo REST completo
Este ejemplo avanzado crea contenido y puede consumir cuota. Sustituye los identificadores, fechas futuras, claves de idempotencia y credencial de ejemplo antes de ejecutarlo. Las fechas del calendario usan la zona horaria IANA indicada. ConsultagetCapabilities antes de elegir destino o categoría del CMS.
Seguir y reintentar
Cada cambio requiere unIdempotency-Key único. Use la misma clave al repetir el mismo comando. Lea data.receipt.operation_id y consulte getOperation hasta succeeded, failed o verification_pending. Un recibo aceptado no significa que la publicación haya terminado. Un lote de generación de artículos devuelve 202 con un recibo ya succeeded; siga cada artículo de selection.accepted_ids con getArticle. La autorización se comprueba en cada consulta, así que una revocación surte efecto de inmediato.
Gestionar errores
Todos los errores tienen la misma forma en REST y en MCP:{"error": {"code", "message", "request_id", "retryable", "details"}}. Base su lógica en code, no en el mensaje. Reintente solo si retryable es true, después de Retry-After cuando esté presente.
401 invalid_credential: credencial no válida, caducada o revocada.403 missing_scopeo403 onboarding_required;402 subscription_requiredo402 insufficient_quota.404 not_found: el recurso no existe o no es accesible con esta credencial.409: un conflicto comoidempotency_conflict;429 rate_limited: espereRetry-After.503 auth_state_unavailable: el acceso se deniega hasta que se recupere el estado de autorización; reintente más tarde.
code y request_id con soporte, nunca su token.
Para conectar un asistente, lee la guía MCP.
