# SocialEcho OpenAPI - Referência LLM para desenvolvedores

Este documento legível por máquinas é destinado a desenvolvedores, testadores, implementadores, engenheiros de automação e agentes de IA que integram a OpenAPI da SocialEcho.

- Developer LLM: https://www.socialecho.net/llms-developers.txt?lang=pt
- Documentação oficial para desenvolvedores: https://www.socialecho.net/en/helpcenter/docs/socialecho-openapi-docs
- URL base da API: https://api.socialecho.net
- Fonte verificada: 2026-08-24 (documentação oficial atualizada em 2026-08-11)

## Início rápido

1. Faça login em https://app.socialecho.net e crie ou selecione uma equipe.
2. Crie uma Team API Key na gestão da equipe (as chaves têm o prefixo `se_`).
3. Adicione `Authorization: Bearer se_your_team_api_key` a cada solicitação.
4. Chame primeiro `GET /v1/team` para verificar a autenticação e o contexto da equipe.
5. Avalie os resultados primeiro pelo código de status HTTP e depois pelo `code` de negócio do corpo da resposta.
6. Obtenha os IDs de conta com `GET /v1/account` antes de consultar publicações, relatórios, publicação de conteúdo ou recursos específicos de cada plataforma.

## Autenticação e transporte

- Autenticação: token Bearer usando uma Team API Key.
- Cabeçalho de autenticação: `Authorization: Bearer se_your_team_api_key`.
- Solicitações JSON: `Content-Type: application/json`.
- Cabeçalho de idioma opcional: `X-Lang: zh_CN` ou `X-Lang: en` (padrão zh_CN).
- Rastreabilidade opcional: envie `X-Request-Id`; o servidor também devolve um cabeçalho `X-Request-Id`.
- Limite de taxa: 120 solicitações por minuto por API Key.
- Nunca exponha a Team API Key em código de navegador, repositórios públicos, logs ou prompts enviados a serviços não confiáveis.

Regra de transporte importante: a maioria dos endpoints GET recebe os parâmetros em um corpo JSON da solicitação, não na query string. O `fetch` do navegador não consegue enviar corpos em GET de forma confiável — use cURL, um cliente HTTP do lado do servidor, a CLI da SocialEcho ou um conector de automação compatível, como o nó do n8n. Os endpoints de consulta do TikTok Shop também aceitam os mesmos parâmetros como query string.

## Envelope de resposta, critérios de sucesso e tratamento de erros

Envelope uniforme: `code`, `message`, `data`, `request_id`; as falhas acrescentam um objeto `error` (`type`, `reason`, `suggestion`); as respostas paginadas acrescentam `meta`.

Uma chamada só é bem-sucedida quando as duas condições são atendidas:

- O status HTTP é `2xx`.
- O `code` de negócio do JSON de resposta é `0`.

As falhas usam HTTP 4xx/5xx com códigos de negócio iguais ao status HTTP × 100:

- `400` / `40000`: solicitação incorreta. Revise campos obrigatórios, datas, arrays, tipos MIME e enums de plataforma.
- `401` / `40100`: chave ausente ou inválida. Revise a Team API Key e o formato do cabeçalho Bearer.
- `403` / `40300`: sem permissão (por exemplo, sem permissão de rascunhos).
- `404` / `40400`: recurso inexistente ou que não pertence à equipe.
- `405` / `40500`: método HTTP incorreto.
- `409` / `40900`: conflito de estado.
- `413` / `41300`: carga grande demais.
- `419` / `41900`: tempo de autenticação esgotado.
- `422` / `42200`: validação malsucedida ou pré-condição de negócio não atendida.
- `429` / `42900`: limite de taxa ou período de espera da sincronização (as respostas de sincronização de produtos incluem `data.next_allowed_at` ou `Retry-After`).
- `500` / `50000`: erro do servidor.
- `502` / `50200`: falha da plataforma upstream.
- `503`/`504` / `50300`/`50400`: serviço indisponível ou timeout de gateway.

Política de novas tentativas: repita automaticamente apenas `429`, `502`, `503`, `504` e timeouts (backoff exponencial de 1, 2, 4 segundos); para todo o resto, corrija primeiro a solicitação ou as permissões.

Ressalvas conhecidas:

- O endpoint de upload atualmente devolve HTTP `500` / `50000` para tipos MIME não suportados.
- Um `422`/`500` ao enviar uma publicação não garante que nenhum registro tenha sido criado — verifique com `GET /v1/article` antes de tentar de novo, para evitar publicações duplicadas.

## Endpoints disponíveis (13 no total)

### GET /v1/team

Devolve a equipe autenticada (id, code, title, timezone). Chame este endpoint primeiro depois de configurar uma chave.

- Corpo: `{}` (opcional)

```bash
curl --request GET 'https://api.socialecho.net/v1/team' \
  --header 'Authorization: Bearer se_your_team_api_key' \
  --header 'Content-Type: application/json' \
  --header 'X-Lang: en' \
  --data-raw '{}'
```

### GET /v1/account

Lista as contas autorizadas ou de concorrentes.

- `page`: inteiro opcional, número da página.
- `type`: inteiro opcional; `1` = contas autorizadas, `2` = contas de concorrentes.

```bash
curl --request GET 'https://api.socialecho.net/v1/account' \
  --header 'Authorization: Bearer se_your_team_api_key' \
  --header 'Content-Type: application/json' \
  --data-raw '{"page":1,"type":1}'
```

### GET /v1/oauth/links

Devolve as URLs de autorização OAuth por plataforma para conectar contas novas. Sem parâmetros de negócio.

- Devolve: `data[].id`, `data[].title`, `data[].connections[].type`, `data[].connections[].url`.
- IDs de plataforma: Instagram 1, Facebook 2, TikTok 3, LinkedIn 4, YouTube 5, Telegram 6, X 7, Pinterest 8, Reddit 9, Threads 10, TikTokShop 11.
- Exemplos de tipo de conexão: `seller`/`creator` para TikTokShop; `instagram`/`facebook` para Instagram.

### GET /v1/article

Lista as publicações da equipe ou de contas específicas, incluindo conteúdo, URL e métricas de relatório (exposição/curtidas/comentários/compartilhamentos).

- `page`: inteiro opcional, número da página.
- `account_ids`: array de inteiros opcional com IDs de conta da SocialEcho.

```bash
curl --request GET 'https://api.socialecho.net/v1/article' \
  --header 'Authorization: Bearer se_your_team_api_key' \
  --header 'Content-Type: application/json' \
  --data-raw '{"page":1,"account_ids":[163956,163955,28]}'
```

### GET /v1/report

Devolve análises para um intervalo de datas.

- `start_date`: string obrigatória, `YYYY-MM-DD`.
- `end_date`: string obrigatória, `YYYY-MM-DD`.
- `time_type`: inteiro obrigatório; `1` = publicações criadas no intervalo, `2` = todas as publicações históricas medidas no intervalo.
- `account_ids`: array de inteiros opcional com IDs de conta.
- `group`: string opcional; vazio para o agregado, ou `day`, `app`, `account`.

```bash
curl --request GET 'https://api.socialecho.net/v1/report' \
  --header 'Authorization: Bearer se_your_team_api_key' \
  --header 'Content-Type: application/json' \
  --data-raw '{"start_date":"2026-01-01","end_date":"2026-03-24","time_type":1,"group":"day","account_ids":[163956,163955,28]}'
```

### GET /v1/upload/url

Devolve as informações de upload pré-assinadas do OSS. Fluxo: obtenha a URL → faça `PUT` do arquivo → use a `public_url` devolvida (não a `upload_url`, de validade limitada) nos `attachments` da publicação.

- `content_type`: tipo MIME obrigatório.
- `title`: string opcional, até 255 caracteres.
- Tipos de imagem: `image/jpeg`, `image/jpg`, `image/png`, `image/gif`, `image/webp`, `image/bmp`.
- Tipos de vídeo: `video/mp4`, `video/avi`, `video/mov`, `video/wmv`, `video/flv`, `video/webm`, `video/mkv`, `video/3gp`, `video/quicktime`.

```bash
curl --request GET 'https://api.socialecho.net/v1/upload/url' \
  --header 'Authorization: Bearer se_your_team_api_key' \
  --header 'Content-Type: application/json' \
  --data-raw '{"content_type":"image/png"}'
```

### GET /v1/reddit/communities

Lista as comunidades disponíveis para uma conta conectada antes de publicar no Reddit.

- `account_id`: inteiro obrigatório, ID de conta da SocialEcho.

### GET /v1/pinterest/boards

Lista os painéis disponíveis para uma conta conectada antes de publicar no Pinterest.

- `account_id`: inteiro obrigatório, ID de conta da SocialEcho.

### GET /v1/tiktokshop/products

Lista os produtos sincronizados do TikTok Shop. `status = 1` significa que o produto pode ser anexado a um vídeo comprável.

- `account_id`: inteiro obrigatório.
- `page`: inteiro opcional.
- `per_page`: inteiro opcional, 1–100, padrão 20.
- `keyword`: string opcional, até 500 caracteres.

### POST /v1/tiktokshop/products/sync

Enfileira uma atualização assíncrona de produtos. "Enfileirado" não é "concluído" — confirme mais tarde pela lista de produtos.

- `account_id`: inteiro obrigatório.
- Período de espera: cerca de 60 minutos por conta; durante a espera a API devolve `429` com `data.next_allowed_at` ou `Retry-After`.

### GET /v1/tiktokshop/music/genres

Lista os valores de gênero da biblioteca de música comercial (por exemplo, `ALL`, `POP`, `BGM`). Sem parâmetros de negócio.

### GET /v1/tiktokshop/music/trending

Devolve a música em alta da biblioteca comercial com `uuid`, `title`, `artist`, `url`, `cover`, `duration`.

- `account_id`: inteiro obrigatório.
- `country_code`: string opcional.
- `genre`: string opcional (do enum de gêneros).
- `date_range`: string opcional, `1DAY` / `7DAY` / `30DAY` / `90DAY`.

### POST /v1/publish/article

Cria um rascunho, publica imediatamente ou agenda conteúdo multiplataforma. A publicação em si é assíncrona — sucesso significa que um registro de publicação foi criado (devolve `data.id`).

- `account_id`: inteiro obrigatório, ID da conta de destino.
- `type`: string obrigatória, tipo de publicação específico da plataforma.
- `status`: inteiro obrigatório; `0` = rascunho, `1` = publicar.
- `scheduled_at`: horário de agendamento opcional; com `status=1` e sem agendamento, publica imediatamente.
- `comment`: array de strings obrigatório, pode estar vazio.
- `content`: corpo da publicação opcional (obrigatório para o TikTok Shop).
- `extra`: objeto obrigatório com campos específicos da plataforma, como título, ID de painel ou comunidade, link, flag de rascunho do TikTok, flair do Reddit.
- `attachments`: array de objetos obrigatório; cada item usa a `public_url` de um arquivo enviado, por exemplo `{ "url": "https://..." }`.

Valores comuns de `type`:

- Facebook: `reels`, `post`, `stories`.
- Instagram: `reels`, `post`, `stories`.
- YouTube: `shorts`, `video`.
- X: `short_post`, `long_post`.
- LinkedIn: `post`.
- TikTok: `video`, `photo`.
- TikTok Shop: `video`.
- Pinterest: `post`.
- Reddit: `text`, `link`, `media`.

Regras de vídeo comprável do TikTok Shop:

- `content` é obrigatório, até 2200 unidades de código UTF-16.
- `extra.title` é obrigatório, até 30 caracteres, apenas letras/dígitos/espaços.
- `extra.product` é obrigatório e deve ser copiado literalmente da resposta da lista de produtos (`id`, `uuid`, `title`, `thumb`).
- `extra.music` é opcional; se usado, deve conter os nove campos: `url`, `uuid`, `cover`, `title`, `artist`, `duration`, `selection`, `music_volume`, `original_sound_volume`; `selection` é `none` / `trending_clip` / `full_track`.
- Anexos: exatamente um vídeo, até 500 MB.

```bash
curl --request POST 'https://api.socialecho.net/v1/publish/article' \
  --header 'Authorization: Bearer se_your_team_api_key' \
  --header 'Content-Type: application/json' \
  --data @publish-payload.json
```

## Fluxo de integração recomendado

1. Verifique a chave e a equipe com `GET /v1/team`.
2. Obtenha as contas autorizadas com `GET /v1/account` e guarde os IDs de conta da SocialEcho devolvidos; use `GET /v1/oauth/links` para gerar URLs de autorização ao conectar contas novas.
3. Nos endpoints paginados, continue incrementando `page` até que `total` e `per_page` de `meta` indiquem a última página.
4. Antes de publicar conteúdo de mídia, chame `GET /v1/upload/url`, faça `PUT` do arquivo e coloque a `public_url` em `attachments`.
5. Antes de publicar no Reddit ou no Pinterest, obtenha as comunidades ou os painéis; antes de publicar um vídeo comprável do TikTok Shop, sincronize e consulte os produtos (e consulte os gêneros/tendências de música se acrescentar uma trilha sonora).
6. Envie o payload final para `POST /v1/publish/article`.
7. Feche o ciclo de publicação até a análise com `GET /v1/article` e `GET /v1/report`.

## Escopo atual da API

A OpenAPI pública expõe atualmente 13 endpoints que cobrem equipes, contas, links de autorização OAuth, publicações, relatórios, URLs de upload, comunidades do Reddit, painéis do Pinterest, produtos e música comercial do TikTok Shop, e publicação de conteúdo. A documentação de origem não lista endpoints de comentários ou mensagens diretas, webhooks nem um servidor MCP oficial como capacidades ativas — não presuma que existam.

Os campos `extra` específicos de cada plataforma e os limites de publicação podem mudar; trate a documentação oficial como a fonte da verdade: https://www.socialecho.net/en/helpcenter/docs/socialecho-openapi-docs