API unificadaAPI de redes socialesGuía para desarrolladores

API unificada de redes sociales: una sola API para datos sociales públicos

Use una sola clave de API, un modelo de tareas y un esquema normalizado para recolectar datos públicos de redes sociales, anuncios, comercio, mapas, tiendas de apps y SEO en 27 plataformas.

SocQActualizado el 9 de noviembre de 202613 min de lectura

Agregar una segunda plataforma social a un producto pocas veces duplica el trabajo de integración. Cada red introduce un modelo de autenticación, un vocabulario de recursos, una estructura de respuesta, un esquema de paginación, una taxonomía de errores y un calendario de mantenimiento distintos. Veintisiete integraciones separadas pueden convertirse en veintisiete sistemas separados.

La API de redes sociales de SocQ reúne los datos públicos detrás de una sola clave de API, un único flujo de tareas asíncronas y un modelo de registros normalizado. El catálogo actual contiene más de 170 endpoints específicos en 27 plataformas: redes sociales, bibliotecas de anuncios, comercio, mapas, tiendas de apps y SEO.

Catálogo de datos públicos de SocQ

Respuesta rápida: Llame a POST /v1/{platform}/{resource} con las entradas que requiere ese recurso, conserve el ID de tarea devuelto y consulte el endpoint común de tareas. Los registros comparten convenciones normalizadas de plataforma, recurso, identidad, autor, métricas, contenido multimedia y marcas de tiempo, y conservan los valores propios de cada fuente en campos explícitos y en extra.

¿Qué es una API unificada de redes sociales?

Una API unificada es una capa de abstracción sobre varias integraciones de plataformas. En lugar de enseñar a su aplicación un sistema de autenticación nuevo y un formato de respuesta incompatible para cada fuente, usted se integra con una especificación compartida y selecciona la plataforma y el recurso en la ruta.

“Unificada” no debe significar “fingir que todas las plataformas son idénticas”. Un empleo de LinkedIn no es un video de TikTok, un artículo de Marketplace no es un perfil de Instagram, y un lugar de Google Maps no tiene un equivalente útil en Reddit. Un modelo unificado responsable estandariza los conceptos que realmente son comunes y conserva la semántica propia de cada fuente donde difieren.

API de datos públicos frente a API de cuentas conectadas

En los resultados de búsqueda aparecen dos productos distintos bajo el nombre “API unificada de redes sociales”.

Una API de cuentas conectadas usa OAuth para que los usuarios autorizados puedan publicar, programar publicaciones, gestionar comentarios o mensajes y leer estadísticas privadas de la cuenta. Es la categoría adecuada para el software de gestión de redes sociales.

Una API de datos públicos recolecta recursos públicos visibles y compatibles para investigación, monitoreo, analítica o enriquecimiento de datos. SocQ pertenece a esta segunda categoría. Sus endpoints no publican, no envían mensajes directos, no gestionan anuncios ni reemplazan las API oficiales para las acciones autorizadas de una cuenta.

Muchos productos necesitan ambas: API oficiales o de cuentas conectadas para las escrituras y los datos con permisos, y una capa de datos públicos para las fuentes externas compatibles.

27 plataformas y más de 170 endpoints

La cobertura es más fácil de analizar por categorías que mediante una breve lista de logotipos.

CategoríaEjemplos del catálogoQué se recolecta normalmente
Redes socialesInstagram (17+), TikTok (18), X (15), Facebook (14), YouTube (12), LinkedIn (11), Reddit (6), Pinterest (4), Threads (3), además de Douyin, Rednote, Snapchat, Bluesky, Twitch, Truth Social, KwaiPersonas, publicaciones, comentarios, búsqueda
Bibliotecas de anunciosFacebook, TikTok, Google y LinkedIn Ad LibraryCreatividades públicas y páginas de anunciantes, no un administrador de anuncios
ComercioTikTok Shop, Facebook Marketplace, AmazonProductos, artículos y reseñas, no un backend de vendedores
MapasGoogle MapsLugares, búsqueda y reseñas
Tiendas de appsGoogle Play, Apple App StoreDetalles públicos de apps, clasificaciones y reseñas
SEORecursos de palabras clave y SERP de SEORegistros de resultados de búsqueda y de palabras clave

La profundidad sigue importando más que el nombre de una plataforma. Instagram no es “una sola API de Instagram”. TikTok Shop no es el catálogo de videos de TikTok. Revise el catálogo de API para ver las entradas aceptadas y los campos devueltos de cada recurso.

REST es una puerta de acceso. MCP, la CLI y la Agent Skill son otras puertas al mismo catálogo. Este artículo se limita a la especificación HTTP.

Un solo patrón de autenticación y de tareas

Todos los endpoints actuales del catálogo usan autenticación Bearer:

Authorization: Bearer $SOCQ_API_KEY
Content-Type: application/json

La creación de recursos sigue una ruta predecible:

POST /v1/{platform}/{resource}

Ejemplos:

POST /v1/tiktok/profiles
POST /v1/instagram/reels
POST /v1/x/search
POST /v1/linkedin/jobs
POST /v1/tiktok-shop/search
POST /v1/facebook-ad-library/search
POST /v1/google-maps/search

Las entradas siguen siendo propias de cada recurso. Los perfiles pueden aceptar nombres de usuario, las entidades conocidas pueden requerir URL y los endpoints de búsqueda aceptan consultas junto con filtros compatibles. Una API unificada debe normalizar el comportamiento operativo sin forzar entradas inválidas dentro de un cuerpo genérico único.

El flujo asíncrono compartido

La recolección de larga duración no debe mantener abierta una conexión HTTP. SocQ crea una tarea:

Client
  └─ POST platform resource
       └─ task_id
            └─ poll common task endpoint
                 ├─ queued
                 ├─ running
                 ├─ succeeded → paginated records
                 └─ failed/cancelled → normalized error

Conserve el ID de tarea antes de empezar a consultar. Use retroceso exponencial, trate queued y running como estados normales, procese los registros solo después del éxito y continúe cuando el resultado indique que hay más páginas.

Esta máquina de estados compartida permite que un solo worker orqueste todo el catálogo:

def submit(platform, resource, payload):
    return post(f"/v1/{platform}/{resource}", json=payload)["data"]["task_id"]

def wait_for_task(task_id):
    while True:
        task = get(f"/v1/tasks/{task_id}")["data"]
        if task["status"] == "succeeded":
            return task
        if task["status"] in {"failed", "cancelled"}:
            raise CollectionError(task)
        backoff()

El código de producción también debe conservar los cursores, limitar los reintentos, clasificar los errores y hacer idempotentes las escrituras posteriores.

Un modelo de registros normalizado

Cuando corresponde, los registros usan convenciones comunes:

{
  "id": "source-id",
  "platform": "tiktok",
  "resource": "videos",
  "type": "video",
  "url": "https://source.example/item",
  "author": {
    "id": "author-id",
    "username": "creator",
    "name": "Creator"
  },
  "metrics": {
    "likes_count": 120,
    "comments_count": 8
  },
  "media": [],
  "created_at": "2026-09-09T08:00:00Z",
  "collected_at": "2026-09-10T08:00:00Z",
  "extra": {}
}

No todos los recursos tienen todos los campos. Un perfil puede exponer name, description y avatar_url; una publicación puede usar text; un video puede tener duración o audio; un empleo incluye datos de contratación; un resultado de Shop incluye el contexto de precio y SKU en extra. Modele los campos opcionales como anulables y ramifique según resource o type cuando se requiera lógica propia de la fuente.

Qué se puede unificar

Autenticación

Una sola clave de API de SocQ puede autenticar las solicitudes de todo el catálogo.

Ciclo de vida de las tareas

El envío, la consulta, los estados finales, la paginación y la observabilidad de las tareas pueden seguir un mismo patrón de worker.

Procedencia

Cada registro almacenado debe conservar platform, resource, la URL de origen o la consulta, la fecha de recolección y el ID de la tarea de origen.

Entidades comunes

Los ID, las URL, los autores, las métricas públicas, las referencias a contenido multimedia, las fechas de publicación y las fechas de recolección pueden seguir convenciones compartidas cuando la fuente los expone.

Manejo de errores

Su aplicación puede asignar la validación de entradas, los recursos públicos no disponibles, las fallas transitorias de origen, los límites de solicitudes y las fallas terminales de recolección a una sola taxonomía interna.

Qué no debe forzarse a una sola forma

Las métricas no son intercambiables

Una reproducción de TikTok, una vista de Instagram, una vista de YouTube, una impresión de X, una puntuación de Reddit, una reacción de LinkedIn, una impresión de anuncio, un conteo de productos vendidos y una calificación de mapas pueden tener definiciones y disponibilidad distintas. Conserve el nombre original de la métrica en lugar de crear un único número de “interacción” que induzca a error.

La profundidad de los recursos difiere

YouTube tiene transcripciones y canales. LinkedIn tiene empleos y empresas. Reddit tiene subreddits. TikTok tiene hashtags. Las bibliotecas de anuncios tienen creatividades. Los mapas tienen lugares. Una matriz de cobertura debe mostrar estas diferencias.

La semántica del descubrimiento difiere

El posicionamiento en la búsqueda, el alcance histórico, la localización, los límites de resultados y la actualidad varían según la plataforma. La misma consulta en distintas redes – o en Shop, Ad Library y Maps – no es una medición comparable.

El acceso y la visibilidad difieren

La disponibilidad pública, el contenido eliminado, las cuentas privadas, las restricciones por edad o región y las vistas con sesión iniciada son propios de cada plataforma. Una API unificada no debe dar a entender que los controles de acceso desaparecen.

Ejemplos de solicitudes en distintas categorías

Recolectar perfiles de TikTok:

curl -X POST "https://api.socq.ai/v1/tiktok/profiles" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"usernames":["tiktok","natgeo"]}'

Buscar en TikTok Shop:

curl -X POST "https://api.socq.ai/v1/tiktok-shop/search" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"running shoes","results_limit":100,"region":"US"}'

Buscar en la Facebook Ad Library:

curl -X POST "https://api.socq.ai/v1/facebook-ad-library/search" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"running shoes","results_limit":100,"country":"US","status":"ACTIVE","media_type":"VIDEO","sort_by":"total_impressions"}'

Buscar en Google Maps:

curl -X POST "https://api.socq.ai/v1/google-maps/search" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"coffee","location":"New York, NY","country":"US","results_limit":3}'

La autorización y el flujo de tareas siguen siendo los mismos; solo cambian las entradas válidas de cada recurso. Entre las guías específicas por plataforma se encuentran TikTok, X y SocQ MCP.

Patrón de cliente en TypeScript

Use tipos de solicitud discriminados en lugar de una carga genérica sin tipos:

type RequestMap = {
  "tiktok/profiles": { usernames: string[] };
  "instagram/reels": { usernames: string[]; results_limit?: number };
  "x/search": { query: string; results_limit?: number; sort_by?: "latest" | "top" };
  "linkedin/jobs": { urls: string[] };
  "tiktok-shop/search": { query: string; results_limit?: number; region?: string };
  "facebook-ad-library/search": { query: string; results_limit?: number; country?: string };
  "google-maps/search": { query: string; location: string; country?: string; results_limit?: number };
};

async function submit<K extends keyof RequestMap>(
  endpoint: K,
  payload: RequestMap[K],
) {
  const response = await fetch(`https://api.socq.ai/v1/${endpoint}`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.SOCQ_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(payload),
  });

  if (!response.ok) throw new Error(`SocQ ${response.status}`);
  return response.json();
}

Genere o mantenga estos tipos a partir de un registro interno de endpoints, de modo que la documentación, la validación y los clientes no se desfasen de forma independiente.

Diseño de la base de datos

Un almacén de datos práctico usa un envoltorio común más tablas por recurso:

social_record
  platform
  resource
  source_id
  canonical_url
  author_id
  created_at
  collected_at
  source_task_id
  raw_json

social_metric_snapshot
  platform
  resource
  source_id
  collected_at
  metric_name
  metric_value

resource-specific tables
  transcript segments
  job details
  profile attributes
  product and listing fields
  place and review fields
  media metadata

No coloque todos los campos posibles de todas las plataformas en una sola tabla de 200 columnas. Conserve el envoltorio normalizado y luego use tablas tipadas por recurso o JSON validado para la profundidad propia de cada fuente.

Normalización de errores y reintentos

Separe:

  • Las entradas inválidas que nunca tendrán éxito.
  • Los recursos públicos no compatibles o no disponibles.
  • Los errores de autenticación y de cuenta.
  • Los límites de solicitudes o de créditos.
  • Las fallas transitorias del origen.
  • Los errores del proveedor o las fallas de validación del esquema.

Reintente solo las clases transitorias. Use un retroceso exponencial acotado con jitter. Registre el intento y el ID de tarea, y haga idempotentes las operaciones upsert para que un reintento no duplique registros.

API unificada frente a las API nativas de las plataformas

Factor de decisiónAPI unificada de datos públicosAPI nativas de las plataformas
IntegraciónUn solo patrón de autenticación y de tareasDistinto en cada plataforma
EsquemaNúcleo normalizadoObjetos nativos de cada plataforma
MantenimientoEl proveedor absorbe gran parte de los cambios de las fuentesSu equipo sigue cada plataforma
Datos públicos externosCobertura de los recursos compatiblesCon frecuencia restringidos por producto y permisos
Publicación y acciones de cuentaSocQ no las ofreceSe requieren las API oficiales
Profundidad específica por plataformaLimitada al catálogoMayor cuando el acceso está aprobado
GobernanzaUn proveedor más las obligaciones de las fuentesRelación directa con la plataforma

No es una decisión de todo o nada. Use las API nativas para las escrituras, la analítica propia y los flujos con permisos; use una API unificada de datos públicos para las lecturas públicas compatibles cuando ese modelo de acceso se ajuste.

Casos de uso comunes

  • Monitoreo de marcas y temas en redes sociales.
  • Investigación de influencers y creadores de contenido.
  • Análisis de contenido y creatividades de la competencia.
  • Investigación pública de Shop, Marketplace y productos.
  • Recolección de lugares y reseñas.
  • Conjuntos de datos de tiendas de apps y de SEO.
  • Herramientas de investigación para agentes de IA que comparten un mismo catálogo.
  • Conjuntos de datos de comentarios, publicaciones, videos y transcripciones.
  • Enriquecimiento de perfiles públicos o de empresas con las salvaguardas adecuadas.

Diseñe el pipeline en torno a los datos mínimos necesarios para el caso de uso, no a todos los campos que la fuente pudiera exponer.

Cuándo no usar una API unificada de datos públicos

No use SocQ cuando:

  • Necesite publicar, responder, enviar mensajes directos o gestionar anuncios.
  • Necesite estadísticas privadas de cuentas con autorización del usuario.
  • Sea obligatorio un programa oficial de socios.
  • Una función específica de una plataforma sea esencial y no esté en el catálogo.
  • Sus requisitos legales, contractuales o de gobernanza prohíban la recolección propuesta.

La respuesta correcta puede ser una API oficial, un proveedor de cuentas conectadas, un conjunto de datos con licencia o no recolectar nada.

  1. Defina un envoltorio interno normalizado antes de agregar fuentes.
  2. Integre un recurso de alto valor y conserve las respuestas sin procesar.
  3. Valide los ID, las marcas de tiempo, las métricas, el contenido multimedia y el manejo de valores nulos.
  4. Agregue una segunda plataforma o categoría mediante el mismo worker de tareas.
  5. Mantenga los adaptadores propios de cada fuente en el límite de validación.
  6. Ejecute en paralelo los pipelines anterior y nuevo sobre una muestra fija.
  7. Compare los registros únicos aceptados, la actualidad y el costo.
  8. Migre de forma gradual y conserve rutas de reversión.

Agregar plataformas se convierte en un trabajo de configuración solo cuando el significado de los datos, la observabilidad y el manejo de fallas están realmente estandarizados.

Seguridad, privacidad y uso responsable

Guarde las claves de API en un gestor de secretos, use acceso de mínimo privilegio a los datos almacenados, cifre el tránsito y el almacenamiento, registre el acceso administrativo y defina procedimientos de retención y eliminación.

Recolecte únicamente los datos públicos compatibles que se necesiten para un propósito legítimo. No eluda las cuentas privadas, las barreras de inicio de sesión, los controles de audiencia ni otras restricciones. Revise los términos de las plataformas, las obligaciones de privacidad, las normas de propiedad intelectual y la legislación aplicable. Una interfaz técnica unificada no unifica ni elimina las obligaciones legales.

Preguntas frecuentes (FAQ)

¿Una API unificada de redes sociales reemplaza a las API oficiales?

No. SocQ gestiona las lecturas públicas compatibles. Las API oficiales siguen siendo necesarias para publicar, realizar acciones de usuario con OAuth, obtener estadísticas privadas y usar los productos de socios de las plataformas.

¿Las 27 plataformas devuelven exactamente los mismos campos?

No. Comparten convenciones normalizadas cuando los conceptos coinciden, mientras que los campos propios de cada recurso siguen siendo distintos.

¿Necesito una clave de API por plataforma?

Una sola clave de SocQ cubre el catálogo de SocQ. Las integraciones oficiales o de otros proveedores siguen requiriendo sus propias credenciales.

¿SocQ puede publicar en redes sociales?

No. Los endpoints actuales son operaciones de solo lectura de datos públicos.

¿Cómo se manejan los límites de solicitudes?

Su aplicación debe respetar los límites de la cuenta de SocQ, conservar el estado de las tareas asíncronas, aplicar retroceso al consultar y reintentar solo las fallas transitorias.

¿Es adecuada para agentes de IA?

Sí, siempre que el agente use herramientas tipadas, entradas restringidas, persistencia del estado de las tareas, validación y aprobación humana para las acciones posteriores con consecuencias. Comience con MCP si el cliente usa ese protocolo.

¿Qué cubre el catálogo actual?

27 plataformas y más de 170 endpoints en redes sociales, bibliotecas de anuncios, comercio, mapas, tiendas de apps y SEO. Consulte /apis para ver la lista actualizada.

MULTI-PLATFORM API

Probar el flujo de trabajo con una URL pública de Multi-platform

Envíe entradas públicas y reciba registros normalizados con contexto de origen rastreable.

Ver las API de Multi-platform