Guía rápida para desarrolladores

El camino de cinco minutos desde cero hasta una integración funcional con SociaHive mediante REST, los SDK o la CLI.

Llama directamente a la API REST, instala el SDK oficial en tu lenguaje de programación o automatiza con la CLI. Cinco minutos hasta tu primer “ajá, esto sí funciona”.

Obtén una clave de API

Configuración → Claves de API → Crear clave. Los scopes mínimos que necesitas:

accounts:read  posts:read  posts:write  flows:read  flows:write

Copia la clave: empieza con sk_ y solo se muestra una vez. Defínela en tu shell:

export SOCIAHIVE_API_KEY=sk_...

Llama a tu primer endpoint

curl -H "X-API-Key: $SOCIAHIVE_API_KEY" \
  https://www.sociahive.com/api/v1/connected-accounts

Deberías recibir un JSON con la lista de tus cuentas de redes sociales conectadas. Guarda uno de los valores de id: lo necesitarás para crear publicaciones.

Explora la referencia

Superficie	URL
Especificación OpenAPI 3.1 (legible por máquinas)	/api/v1/openapi.json
Interfaz de Scalar (legible por personas, con pruebas en vivo)	/api/v1/docs

Pon la URL de la especificación en Postman, en las Actions de un GPT personalizado de ChatGPT o en cualquier generador de SDK basado en OpenAPI.

Instala un SDK

npm install @sociahive/sdk

import { SociaHive } from '@sociahive/sdk'
 
const sh = new SociaHive({ apiKey: process.env.SOCIAHIVE_API_KEY! })
 
const { data: accounts } = await sh.accounts.list()
console.log(`Connected to ${accounts.length} accounts`)
 
const post = await sh.posts.create({
  text: 'Hello from the SDK',
  platforms: [{ platform: 'instagram', account_id: accounts[0].id }],
  schedule_type: 'scheduled',
  scheduled_at: '2026-06-01T09:00:00Z',
  timezone: 'UTC',
})
console.log(`Scheduled post ${post.id}`)

Ambos SDK incluyen clientes tipados con la misma agrupación de recursos (accounts, posts, flows, analytics), clases de error cómodas de usar (SociaHiveError con isAuthError, isRateLimited, etc.) y extracción automática del contenido de los sobres de respuesta de la v1.

Usa la CLI para operaciones puntuales

La CLI sociahive encapsula la API REST para usarla cómodamente desde el shell:

npm install -g sociahive
export SOCIAHIVE_API_KEY=sk_...
 
sociahive accounts list
sociahive posts list --status scheduled --limit 20
sociahive posts create \
  --text "Hello!" \
  --platforms '[{"platform":"instagram","account_id":"..."}]' \
  --schedule-type immediate
sociahive flows generate \
  --description "Auto-reply to comments containing price" \
  --account-id <account_id> \
  --platform-user-id <platform_user_id>

Por defecto, la salida es JSON apto para usar con pipes. Sirve dentro de CI/CD, tareas cron y consultas rápidas del tipo “cuál es el estado de X”.

Genera tipos desde OpenAPI (opcional)

Nuestros SDK cubren los endpoints de mayor tráfico con tipos curados a mano. Para los endpoints fuera de esa superficie, genera los tipos directamente desde la especificación:

npx openapi-typescript https://www.sociahive.com/api/v1/openapi.json \
  -o sociahive.d.ts

Obtendrás tipos completos de solicitud y respuesta para cada endpoint de la especificación; combínalos con fetch o axios para las superficies que el SDK aún no cubre.

Opciones de autenticación

La autenticación con clave de API (arriba) es el camino más rápido. Para aplicaciones con varios usuarios en las que cada usuario final debe autorizar por su cuenta el acceso a SociaHive, usa OAuth 2.1 con registro dinámico de clientes (Dynamic Client Registration):

Superficie	URL
Endpoint de autorización	`https://www.sociahive.com/api/oauth/authorize`
Endpoint de tokens	`https://www.sociahive.com/api/oauth/token`
Registro dinámico	`https://www.sociahive.com/api/oauth/register`
Descubrimiento	`https://www.sociahive.com/.well-known/oauth-authorization-server`

Ambos SDK aceptan oauthToken como alternativa a apiKey:

const sh = new SociaHive({ oauthToken: 'mcp_at_...' })

Manejo de errores

Toda respuesta que no sea 2xx lanza un SociaHiveError (Node) / SociaHiveError (Python) con status, code y el cuerpo de la respuesta:

import { SociaHive, SociaHiveError } from '@sociahive/sdk'
 
try {
  await sh.posts.create({ /* ... */ })
} catch (err) {
  if (err instanceof SociaHiveError) {
    if (err.isAuthError) console.error('Bad API key or insufficient scope')
    else if (err.isRateLimited) console.error('Rate limit — slow down')
    else console.error(`HTTP ${err.status}: ${err.message}`)
  } else throw err
}

Qué leer después

Patrones de flujo: las siete formas que adoptan la mayoría de los flujos de automatización de SociaHive. Útil cuando estés a punto de llamar a flows.create.
Cookbook: recetas completas, entre ellas “programar una semana de publicaciones desde un CSV”, que usa este SDK en Python y en Node.
Guía de configuración del MCP: si además quieres que tu asistente de IA use la API junto con el código de tu propia aplicación.

Guía rápida para desarrolladores

On this page