Guia rápido para desenvolvedores

Cinco minutos do zero até uma integração funcionando com o SociaHive, via REST, SDKs ou CLI.

Chame a API REST direto, instale o SDK oficial na sua linguagem ou use scripts com a CLI. Em cinco minutos você chega ao primeiro resultado funcionando.

Gere uma chave de API

Configurações → Chaves de API → Criar chave. O conjunto mínimo de escopos úteis:

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

Copie a chave: ela começa com sk_ e aparece só uma vez. Defina-a no seu terminal:

export SOCIAHIVE_API_KEY=sk_...

Chame o primeiro endpoint

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

A resposta é um JSON com as suas contas de redes sociais conectadas. Guarde um dos valores de id: você vai precisar dele para criar posts.

Consulte a referência

Superfície	URL
Especificação OpenAPI 3.1 (legível por máquina)	/api/v1/openapi.json
Interface Scalar (legível por pessoas, com teste na hora)	/api/v1/docs

Use o endereço da especificação no Postman, nas Actions de GPTs personalizados do ChatGPT ou em qualquer gerador de SDK baseado em OpenAPI.

Instale um 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}`)

Os dois SDKs trazem clientes tipados com os mesmos grupos de recursos (accounts, posts, flows, analytics), classes de erro práticas (SociaHiveError com isAuthError, isRateLimited e outras) e extração automática do conteúdo dos envelopes de resposta da v1.

Use a CLI para operações pontuais

A CLI sociahive encapsula a API REST para uso no terminal:

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>

A saída é JSON por padrão, pronta para encadear com outros comandos. É útil em CI/CD, em tarefas agendadas (cron) e em consultas rápidas do tipo “qual é o estado de X”.

Gere tipos a partir do OpenAPI (opcional)

Nossos SDKs cobrem os endpoints mais usados com tipos escritos à mão. Para os endpoints fora dessa lista, gere os tipos direto da especificação:

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

Você recebe os formatos de requisição e resposta totalmente tipados de todos os endpoints da especificação. Combine com fetch ou axios para as superfícies que o SDK ainda não cobre.

Opções de autenticação

A autenticação por chave de API (acima) é o caminho mais rápido. Em aplicativos com vários usuários, em que cada pessoa deve autorizar o acesso ao SociaHive por conta própria, use OAuth 2.1 com registro dinâmico de clientes (DCR):

Superfície	URL
Endpoint de autorização	`https://www.sociahive.com/api/oauth/authorize`
Endpoint de token	`https://www.sociahive.com/api/oauth/token`
Registro dinâmico	`https://www.sociahive.com/api/oauth/register`
Descoberta	`https://www.sociahive.com/.well-known/oauth-authorization-server`

Os dois SDKs aceitam oauthToken no lugar de apiKey:

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

Tratamento de erros

Toda resposta que não seja 2xx lança um SociaHiveError (Node) / SociaHiveError (Python) com status, code e o corpo da resposta:

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
}

O que ler depois

Padrões de fluxo: os sete formatos que a maioria dos fluxos de automação do SociaHive adota. Útil antes de chamar flows.create.
Cookbook: receitas completas, incluindo “agendar uma semana de posts a partir de um CSV”, que usa este SDK em Python e em Node.
Guia de configuração do MCP: se você também quer que seu assistente de IA use a API junto com o código do seu aplicativo.

Guia rápido para desenvolvedores

On this page