Documentação

Introdução

A API pública do BSN Social permite que sistemas externos e agentes de IA operem a sua conta programaticamente: listar suas marcas, ver as contas de rede social conectadas e criar/agendar publicações em uma ou várias redes de uma só vez (fan-out).

Todo acesso é feito com uma API key (prefixo bsn_), escopada à sua organização. A mesma lógica está exposta de duas formas:

• REST v1 — endpoints HTTP JSON convencionais em /api/public/v1/*, ideais para integrar com back-ends, automações e ferramentas de no-code.
• MCP (Model Context Protocol) — um endpoint JSON-RPC em /api/mcp que expõe as mesmas operações como tools para agentes de IA (Claude Desktop, Cursor e outros clientes MCP).

Quickstart

Do zero ao primeiro post agendado em três passos:

1. Gere uma API key no painel, em Minha conta → API & MCP (endereço /api). Ela começa com bsn_ e aparece uma única vez. Só o dono ou um administrador da organização gera chaves.
2. Descubra sua marca — chame GET /brands e anote o id (ex.: brd_123) da marca onde vai publicar.
3. Agende um post — faça um POST /posts com o brandId, as networks e a caption.

# 1) suas marcas → pegue o brandId
curl https://api-social.bsnsolution.com.br/api/public/v1/brands \
  -H "Authorization: Bearer bsn_sua_chave_aqui"

# 2) agende um post em duas redes de uma vez
curl -X POST https://api-social.bsnsolution.com.br/api/public/v1/posts \
  -H "Authorization: Bearer bsn_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "brandId": "brd_123",
    "caption": "Meu primeiro post via API 🚀",
    "mediaUrls": ["https://cdn.exemplo.com/arte.png"],
    "networks": ["INSTAGRAM", "FACEBOOK"],
    "scheduledAt": "2027-01-15T13:00:00Z"
  }'

Prefere um agente de IA em vez de HTTP? Pule para o MCP — as mesmas operações, expostas como tools para o Claude, o Cursor e afins.

Autenticação

Todas as requisições exigem o header Authorization com o token no esquema Bearer:

Authorization: Bearer bsn_sua_chave_aqui

Como gerar a chave

1. No painel, abra Minha conta (menu do seu perfil) e clique em Abrir API & MCP (endereço /api).
2. Dê um nome à chave e clique em Gerar chave (só dono ou administrador da organização).
3. O token cru (bsn_<...>) é exibido uma única vez — copie e guarde num cofre. Depois disso o painel só mostra o prefixo (ex.: bsn_ab12cd3…), nunca o token completo.

Você pode revogar uma chave a qualquer momento pelo painel; requests com uma chave revogada passam a receber 401.

Base URL

Todos os caminhos abaixo são relativos a esta base:

https://api-social.bsnsolution.com.br

Ex.: a lista de marcas fica em https://api-social.bsnsolution.com.br/api/public/v1/brands.

Referência REST v1

Prefixo /api/public/v1. Respostas em application/json. Os exemplos curl abaixo já incluem o header de autenticação.

{
  "brands": [
    {
      "id": "brd_123",
      "name": "Minha Marca",
      "handle": "minhamarca",
      "activeNetworks": ["INSTAGRAM", "FACEBOOK"]
    }
  ]
}

curl https://api-social.bsnsolution.com.br/api/public/v1/brands \
  -H "Authorization: Bearer bsn_sua_chave_aqui"

{
  "integrations": [
    {
      "id": "int_456",
      "brandId": "brd_123",
      "brandName": "Minha Marca",
      "network": "INSTAGRAM",
      "externalAccountId": "17841400000000000",
      "displayName": "@minhamarca",
      "status": "active"
    }
  ]
}

curl https://api-social.bsnsolution.com.br/api/public/v1/integrations \
  -H "Authorization: Bearer bsn_sua_chave_aqui"

{
  "groupId": "a1b2c3d4-0000-0000-0000-000000000000",
  "posts": [
    { "id": "pst_1", "network": "INSTAGRAM", "state": "SCHEDULED" },
    { "id": "pst_2", "network": "FACEBOOK",  "state": "SCHEDULED" }
  ],
  "postsCharged": 1
}

curl -X POST https://api-social.bsnsolution.com.br/api/public/v1/posts \
  -H "Authorization: Bearer bsn_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ID-UNICO-DO-PEDIDO" \
  -d '{
    "brandId": "brd_123",
    "caption": "Lançamento de hoje 🚀",
    "mediaUrls": ["https://cdn.exemplo.com/arte.png"],
    "scheduledAt": "2027-01-15T13:00:00Z",
    "networks": ["INSTAGRAM", "FACEBOOK"]
  }'

{
  "posts": [
    {
      "id": "pst_1",
      "brandId": "brd_123",
      "network": "INSTAGRAM",
      "state": "SCHEDULED",
      "caption": "Lançamento de hoje 🚀",
      "scheduledAt": "2027-01-15T13:00:00.000Z",
      "createdAt": "2026-07-14T18:20:00.000Z"
    }
  ]
}

curl "https://api-social.bsnsolution.com.br/api/public/v1/posts?brandId=brd_123&limit=20" \
  -H "Authorization: Bearer bsn_sua_chave_aqui"

Formatos

A API não tem campo de formato: ele é decidido pelas mediaUrls que você envia.

Story e Reel explícitos (escolher “Story” ou forçar um Reel) ainda não estão disponíveis pela API nem pelo MCP — use o painel para isso.

Erros

Erros retornam um JSON com o campo error (e, quando aplicável, issues com o detalhe da validação). Códigos:

No 429 com Retry-After (excesso de requisições), espere esses segundos antes de repetir. No 429 com code: "LIMIT_REACHED" não adianta repetir: o limite do plano só volta no próximo mês ou com upgrade.

MCP (Model Context Protocol)

O MCP é um protocolo aberto que permite a agentes de IA descobrir e chamar ferramentas externas. O BSN Social expõe um servidor MCP em /api/mcp (JSON-RPC 2.0 sobre HTTP), com as mesmas operações da API REST — assim um agente pode listar suas marcas e agendar posts conversando em linguagem natural.

Como conectar

Claude Code — um comando no terminal:

claude mcp add --transport http bsn-social https://api-social.bsnsolution.com.br/api/mcp \
  --header "Authorization: Bearer bsn_sua_chave_aqui"

Cursor (e outros clientes que aceitam servidor HTTP com headers) — no mcp.json:

{
  "mcpServers": {
    "bsn-social": {
      "url": "https://api-social.bsnsolution.com.br/api/mcp",
      "headers": {
        "Authorization": "Bearer bsn_sua_chave_aqui"
      }
    }
  }
}

Claude Desktop — use a ponte mcp-remote (precisa do Node.js instalado) no claude_desktop_config.json. O token vai numa variável de ambiente, sem espaços dentro dos args (no Windows o Claude Desktop quebra argumentos com espaço):

{
  "mcpServers": {
    "bsn-social": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api-social.bsnsolution.com.br/api/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer bsn_sua_chave_aqui"
      }
    }
  }
}

O servidor declara protocolVersion 2024-11-05 e capacidade de tools. É stateless (sem SSE/server-push e sem sessão persistida): cada chamada é resolvida no próprio POST, dentro do escopo da chave.

Tools disponíveis

* obrigatório.

Exemplo: chamar schedule_post

Requisição JSON-RPC (tools/call) para o endpoint MCP:

curl -X POST https://api-social.bsnsolution.com.br/api/mcp \
  -H "Authorization: Bearer bsn_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "schedule_post",
      "arguments": {
        "brandId": "brd_123",
        "caption": "Publicado por um agente de IA 🤖",
        "mediaUrls": ["https://cdn.exemplo.com/arte.png"],
        "networks": ["INSTAGRAM", "FACEBOOK"],
        "scheduledAt": "2027-01-15T13:00:00Z",
        "idempotencyKey": "ID-UNICO-DO-PEDIDO"
      }
    }
  }'

Resposta

O resultado vem no formato MCP (content[] com um bloco text contendo o JSON serializado) — o mesmo corpo da REST, com postsCharged (posts do plano consumidos: 1 por conteúdo) e, quando o pedido repetiu uma idempotencyKey já usada, "replayed": true (nada foi criado nem cobrado de novo):

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\n  \"groupId\": \"a1b2c3d4-...\",\n  \"posts\": [\n    { \"id\": \"pst_1\", \"network\": \"INSTAGRAM\", \"state\": \"SCHEDULED\" },\n    { \"id\": \"pst_2\", \"network\": \"FACEBOOK\", \"state\": \"SCHEDULED\" }\n  ],\n  \"postsCharged\": 1\n}"
      }
    ]
  }
}

Para o agente descobrir as tools, use o método tools/list; o handshake inicial é o método initialize.

Erros no MCP

• Antes do JSON-RPC (status HTTP): chave ausente ou revogada → 401; plano sem API, sem plano ativo ou conta bloqueada → 402 com { error, code }; excesso de requisições (120/min por organização) → 429 com Retry-After. Nesses casos não há resposta JSON-RPC.
• Recusa da tool (HTTP 200): quando o schedule_post recusa o pedido (mesmas regras da REST: horário no passado, rede indisponível, falta de mídia ou de conta, limite de posts do mês), o resultado vem com isError: true, a explicação em content e { error, code } em structuredContent. Nada é criado nem cobrado.
• Erro JSON-RPC: método desconhecido (-32601), parâmetro faltando (-32602) ou falha interna (-32000).