API de SoldScope en español: guía completa, cuotas y precios (2026)

Por Arofrancisco Ruiz, Planeta Prime AMZ · Actualizado el 29 de septiembre de 2026 · Lectura de referencia (API v1.0.0, OpenAPI 3.0)

Esta guía en español reúne cuotas, flujos de trabajo, una calculadora de consumo (sección 3), estrategias para gastar menos peticiones con API y MCP (sección 4), informes en marca blanca con n8n (sección 5) y una FAQ con el plan recomendado.

Datos clave de la API de SoldScope de un vistazo

1. Qué es la API de SoldScope

La API de SoldScope da acceso programático a las mismas herramientas que usas en la aplicación: puedes automatizar flujos de trabajo, extraer datos y construir integraciones propias (dashboards, informes para clientes, alertas, etc.).

2. Límites de uso y cuotas de peticiones

La API funciona con una cuota mensual de peticiones que depende de tu plan de suscripción. Solo cuentan los endpoints marcados con la etiqueta Metered (en el menú lateral aparecen con el prefijo ◈). Todo lo demás —autenticación, datos de tu cuenta, consulta de datos ya guardados— es gratuito.

Cómo consultar tu consumo

Cada respuesta de un endpoint medido incluye estas cabeceras:

HTTP/1.1 200 OK
X-API-RateLimit-Limit: 1000
X-API-RateLimit-Remaining: 847
X-API-RateLimit-Reset: 2026-01-01

Qué pasa cuando agotas la cuota

Los endpoints medidos responden con 402 Payment Required:

HTTP/1.1 402 Payment Required
Content-Type: application/json

{ "message": "API requests limit exceeded" }

3. Calculadora: ¿cuántas peticiones de la API necesito?

Compara tu consumo sin optimizar frente a con la estrategia de ahorro de la sección 4 y te dice qué plan encaja en cada caso. Es una estimación: supone que cada llamada a un endpoint Metered cuenta 1 petición y que leer datos guardados, sondear progreso y paginar con searchId no consume.

4. Cómo gastar menos peticiones de la API y del MCP

La idea central: generar datos nuevos cuesta cuota; leer datos ya guardados es gratis. Casi todo el ahorro consiste en pedir menos veces lo nuevo y releer más veces lo guardado.

La regla de las 3 preguntas (antes de cada llamada)

1. ¿Ya lo tengo? En SoldScope (búsquedas previas) o en tu propia hoja/base de datos → léelo, no lo pidas.
2. ¿Ha cambiado lo bastante? Mira la tabla de refresco de abajo; casi nada necesita datos diarios.
3. ¿Puedo pedirlo en lote? 100 keywords, 10 ASINs o un export en una sola llamada.

Cada cuánto refrescar cada dato Recomendación orientativa

Usar el MCP con Claude sin quemar cuota

El MCP de SoldScope (https://www.soldscope.com/api/mcp) se conecta a Claude desde Ajustes → Conectores → Añadir conector personalizado y se autoriza con OAuth. Sus llamadas consumen la misma cuota que la API y tiene un límite de 30 peticiones por minuto por usuario. El riesgo: un agente puede encadenar varias herramientas para una sola pregunta.

• Pide tareas acotadas («keywords de marca de este ASIN») y no abiertas («investiga todo mi nicho»).
• Ordena usar primero lo guardado y poner un tope de búsquedas nuevas.
• Agrupa: la información en vivo admite hasta 10 ASINs por llamada.
• Explora con MCP y automatiza con API: cuando una consulta se repite, pásala a un flujo programado que lea datos guardados.
• Concede solo los permisos necesarios: si solo investigas, basta lectura.

Plantilla de prompt para el agente:

Investiga las keywords de marca del ASIN B08N5WRWNW (US).
Reglas:
1) Usa primero búsquedas y datos ya guardados en mi cuenta.
2) Lanza como máximo 3 búsquedas nuevas.
3) Agrupa los ASINs en una sola llamada cuando sea posible.
4) Si vas a hacer más de 3 llamadas que consuman cuota, avísame antes.
5) Al terminar, dame los identificadores de búsqueda para reutilizarlos.

5. Informes en marca blanca y automatización con n8n En pruebas

La API no solo sirve para investigar: también para entregar informes a clientes con tu marca. SoldScope presenta la API para dashboards e informes en marca blanca; no es una función lista para usar, así que el informe lo montas tú con tus datos y tu diseño.

Flujo de informe semanal

1. n8n (programado semanal) lee los datos de los ASINs de cada cliente: históricos de precio, BSR, ventas y reseñas, y posiciones de Rank Tracker (lectura de datos guardados, sin cuota).
2. Guarda los resultados en Google Sheets o una base de datos: es tu caché y evita repetir peticiones.
3. Una plantilla con la marca (Google Slides, Looker Studio o HTML impreso a PDF) se rellena con esos datos.
4. n8n envía el informe por email o lo sube a la carpeta del cliente.

Configuración en n8n

• Nodo HTTP Request con credencial Header Auth: cabecera Authorization con valor Bearer TU_TOKEN. Un token por cliente o flujo para atribuir el consumo.
• Activa incluir las cabeceras de respuesta y guarda X-API-RateLimit-Remaining tras cada ejecución.
• En procesos asíncronos (Keyword Research multi-ASIN, Listing Analyzer, Buy Box Map, exportaciones): lanza el POST una vez, usa un nodo Wait y consulta el estado en bucle. No repitas el POST.
• Un nodo IF que detenga el flujo ante un 402 o si Remaining baja del 20 %. Reintentar un 402 no sirve.
• Programa semanal, salvo diario en los ASINs estrella.

Coste para una agencia

Ejecuta el informe de un cliente tipo una vez y compara Remaining antes y después. Multiplica por clientes y por semanas al mes y añade un 25 % de margen. Con varios clientes, Starter suele quedarse corto: empieza en Professional o, si superas el 75 % de sus 5.000 peticiones, consulta a SoldScope antes de quedarte a medias.

6. Autenticación y token de la API

Todas las peticiones necesitan un Personal Access Token enviado como Bearer token en la cabecera Authorization:

Authorization: Bearer <tu-token>

Cómo obtener el token

1. Abre API Access en tu cuenta de SoldScope.
2. Pulsa Create token, ponle un nombre y cópialo: solo se muestra una vez.
3. Úsalo en todas las peticiones.

Prueba rápida: GET /auth/check

Comprueba que el token es válido y devuelve la información básica del usuario y la cuenta. Es gratuito.

curl https://www.soldscope.com/api/auth/check \
  --header 'Authorization: Bearer TU_TOKEN'

{
  "user":    { "id": 1, "name": "John Doe", "email": "john@example.com" },
  "account": { "id": 42, "name": "My Store" }
}

Respuestas: 200 token válido · 401 no autenticado.

7. Buy Box Map por API

Muestra quién tiene la Buy Box, a qué precio y con qué plazos de entrega en distintas regiones de EE. UU., Reino Unido, Alemania o Francia. Las búsquedas son asíncronas y pertenecen a la cuenta del token. Permisos: BUY_BOX_MAP_VIEW o BUY_BOX_MAP_MANAGE para leer; BUY_BOX_MAP_MANAGE para lanzar búsquedas.

Paso 1 · Lanzar o reutilizar una búsqueda

POST /buy-box-map
{ "marketplace": "US", "asin": "B08N5WRWNW", "regenerate": false }

• Devuelve data.search y data.progress. Guarda data.search.id.
• Por defecto se reutiliza la búsqueda más reciente sin error para la misma cuenta, marketplace y ASIN creada en las últimas 24 h. Con regenerate: true fuerzas una nueva.
• Una búsqueda nueva reserva 1 uso de BBM_SEARCHES: se cobra si termina bien y se libera si falla. Reutilizar no consume.
• Errores: 402 límite agotado · 422 datos inválidos o producto no encontrado.

Paso 2 · Consultar hasta que termine

GET /buy-box-map/{search}

Usa siempre status para saber si terminó: progress puede llegar a 100 antes de que los resultados estén cerrados. Cada resultado regional incluye:

• state, stateKey: región e identificador del mapa.
• sellerId, sellerName, sellerType: 1 = Amazon, 2 = FBA, 3 = FBM.
• price: precio de la Buy Box en la moneda del marketplace.
• freeFrom/freeTo, paidFrom/paidTo, primeFrom/primeTo: días mínimos/máximos de entrega gratuita, de pago y Prime.

Paso 3 · Historial

GET /buy-box-map — lista paginada con filtros: marketplace, search (ASIN o título), sort (created_at, title, status), sortDesc, page, perPage (15 por defecto). El historial no trae resultados regionales; para eso consulta la búsqueda concreta.

8. Endpoints comunes (históricos y keywords)

Endpoints de uso general que combinan datos de varias herramientas. Son los más útiles para montar dashboards de seguimiento de tu catálogo.

9. Influencer Radar

Encuentra influencers de Amazon para colaboraciones: códigos de storefront, biografía, email de contacto (si existe), redes sociales, número de publicaciones, estadísticas de vídeo y categorías.

Búsqueda

GET /influencer-radar/influencers?marketplace=BR&fullDataMode=false&page=1&perPage=10&sort=postsCount&sortDesc=true

Envía siempre fullDataMode y, si paginas, page y perPage (1–100). Por defecto ordena por postsCount ascendente.

Filtros (notación con corchetes, p. ej. filters[videosCount][min]=10)

• Perfil: nombre, código de storefront exacto, email exacto, emailExists.
• Contenido: rangos de videosCount, ideasCount, photosCount, upperVideosCount, lowerVideosCount, avgVideoLength (segundos), avgVideoLikes; además isLiveStream e isTopCreator.
• Biografía: descriptionContains y descriptionExclude (términos separados por comas).
• Redes: filters[socialLinks][]=instagram (facebook, instagram, youtube, tiktok, pinterest). Deben existir todas las seleccionadas.
• Productos destacados: asins[], categories[], brand, y rangos de avgRatingsCount, avgReviewRating (1–5) y avgPrice.

emailExists, isLiveStream e isTopCreator: 0 = cualquiera, 1 = sí, 2 = no. Para filtrar por categoría raíz usa el btgNodeId (p. ej. 7841278011 para Libros en Brasil).

Paginación y créditos

• Una búsqueda nueva con resultados consume 1 crédito y devuelve meta.searchId. Pásalo en las siguientes peticiones para paginar u ordenar sin gastar otro crédito.
• Un searchId existente carga sus filtros guardados (sustituye a los de la petición). Uno desconocido se trata como búsqueda nueva.
• Máximo 1.000 influencers por búsqueda. fullDataMode=true devuelve todo de golpe.
• Sin resultados = no consume crédito. Límite: 500 búsquedas con resultados por cuenta cada 24 h.

10. Keyword Research por API

Tres tipos de búsqueda; la respuesta siempre indica searchType.

POST /keyword-research/searches/asin/multi
{ "asins": ["B08N5WRWNW", "B07XJ8C8F5"], "marketplace": "US" }

Extras: frecuencia de palabras (…/word-frequency) y listado de búsquedas (GET /keyword-research/searches).

11. Listing Analyzer y LQS por API

Analiza la calidad de tus listings y compáralos con la competencia. Cada análisis genera un LQS (Listing Quality Score) de 0 a 100 con sugerencias por atributo.

Conceptos

• Proceso: un ASIN principal + ASINs competidores en un marketplace. Estados: pendiente → procesando → completado (o fallido).
• lqsCharacteristics: desglose del LQS por atributo (puntuación, máximo, %, sugerencias y detalles).
• Review insights: número de reseñas y distribución de estrellas.

Flujo

POST /listing-analyzer/processes
{ "marketplace": "US", "mainAsin": "B08N5WRWNW",
  "competitorsAsins": ["B07XJ8C8F5", "B09B8YWXDF"] }

Sondea con GET /listing-analyzer/processes/{process}: 0 pendiente · 1 procesando · 2 completado · 3 fallido. Cada resultado incluye título, imágenes, LQS, vídeos (vendedor, influencer, cliente), BSR, categorías, precio, rating, vendedor de la Buy Box, marca, ASIN padre, nº de variaciones y review insights.

Historial: GET /listing-analyzer/processes (solo completados, hasta 1.000 por página). Borrado: DELETE /listing-analyzer/processes con {"ids":[42,43]} → 204.

12. Product Research

Descubre productos por nicho, rango de precio, BSR, volumen de ventas, tipo de fulfillment y más.

GET /product-research/products?marketplace=US&filters[bsr][max]=5000&filters[price][min]=20

• Cada búsqueda única consume 1 crédito y devuelve meta.searchId. Pagina con page/perPage y ese searchId para no gastar más.
• Variaciones: GET /product-research/products/{id}/variations?searchId=… (caché de 1 hora; si expira devuelve 404 y hay que relanzar con el searchId).
• Media del producto: GET /product-research/products/{id}/media.
• Búsquedas anteriores: GET /product-research/searches — repetir una pasada no consume crédito.

Filtrar por categoría

Opción A: GET /product-research/categories-tree?marketplace=US&searchQuery=Electronics → recoge los nodeId.
Opción B: GET /product-research/categories?marketplace=US&level=2 (raíces) → GET /product-research/categories/{id}/children para bajar niveles.

13. Rank Tracker por API

Monitoriza posiciones orgánicas y patrocinadas de tus productos por keyword.

Conceptos

• Grupo: un ASIN principal en un marketplace con su lista de keywords.
• Producto: ASIN dentro del grupo; puedes añadir competidores para comparar con las mismas keywords.
• Frase: keyword seguida, con posición orgánica/patrocinada, volumen, CPC, datos ABA e histórico.
• Etiqueta: label con color para organizar grupos, productos y frases.
• Boost: recoge posiciones con más frecuencia. Requiere volumen ≥ 500.
• Frases sugeridas: keywords propuestas por SoldScope a partir de la competencia.

Flujo típico

POST /rank-tracker/groups
{ "asin": "B08N5WRWNW", "marketplace": "US", "trackAllVariations": false,
  "phrases": ["wireless earbuds", "bluetooth headphones sport"] }

Cada keyword devuelve: organicPosition, sponsoredPosition (y sus posiciones anteriores), searchVolume, cpc, cpcMin/Max y, si hay datos, abaSearchFrequencyRank, abaTotalClickShare, abaTotalConvShare.

Exportación

Simple (modo heatmap, síncrono): hasta 92 días de posiciones diarias de un producto en una sola llamada.

GET …/products/{productId}/phrases/v2?heatmap=true&heatmapDateFrom=2026-02-01&heatmapDateTo=2026-04-28&perPage=10000

Cada keyword trae un campo r_AAAA-MM-DD por día con rank (null = sin dato, 0 = no encontrado) y amazon_choice.

Widgets resumen: GET …/heatmap-widgets devuelve visibilidad (0–100, ponderada por volumen), posición media (no encontrado = 306), nº de keywords con Amazon’s Choice y distribución por tramos (1-3, 4-10, 11-50, 51-100, 100+).

Asíncrona (CSV/JSON, cualquier rango):

POST /rank-tracker/export
{ "groupId": 12, "dateFrom": "2026-01-01", "dateTo": "2026-04-28",
  "format": "csv", "granularity": "daily" }

Sondea GET /rank-tracker/export/{id} (0 pendiente · 1 listo · 2 fallido). Con status: 1, filename es una URL S3 firmada válida 15 minutos. granularity: raw (cada snapshot) o daily (mediana del día). Puedes limitar por products, keywords o filters (búsqueda, etiquetas con lógica AND, boosts).

14. SQP Analyzer (Search Query Performance) por API

Exporta los datos de Search Query Performance de Brand Analytics de una cuenta de vendedor conectada: impresiones, clics, añadidos al carrito y compras de tus ASINs frente al total del mercado, junto con métricas PPC cuando existen.

curl --get 'https://www.soldscope.com/api/sqp-analyzer/A1EXAMPLESELLER/export' \
  --header 'Authorization: Bearer <tu-token>' \
  --data-urlencode 'marketplace=US' \
  --data-urlencode 'period_type=months' \
  --data-urlencode 'periods[]=2026-07-31' \
  --data-urlencode 'periods[]=2026-08-31' \
  --data-urlencode 'group=keyword' \
  --data-urlencode 'asins[]=B08N5WRWNW' \
  --data-urlencode 'sort_by=queryVolume' \
  --data-urlencode 'sort_desc=true'

• period_type: months (fechas de fin de mes) o weeks (fin de semana).
• group: period, keyword o asin.
• Respuesta JSON síncrona sin paginación: data + meta.total.
• Filtros: searchQueryVolume (min/max), wordCount, phrasesContain (modo 1 contiene / 2 no contiene), excludeKeywords.
• Métricas: market* (mercado, deduplicado), my* (tus ASINs), CTR, CVR, cuotas en %, ctrDelta/cvrDelta (tu tasa menos la del mercado), precios medianos y campos ppc_* (spend, ventas, CPC, ACoS…).
• Errores: 422 parámetros inválidos · 404 vendedor desconocido · 500 fallo de exportación.

15. Planes y precios de SoldScope

Precios publicados en la página de precios de SoldScope (en USD, pueden aplicarse impuestos; verifica antes de contratar porque pueden cambiar).

16. Preguntas frecuentes sobre la API de SoldScope para vendedores de Amazon