# SocialEcho OpenAPI - Referencia LLM para desarrolladores

Esta referencia legible por máquinas está dirigida a desarrolladores, QA, equipos de implementación, ingenieros de automatización y agentes de IA que integran la OpenAPI de SocialEcho.

- LLM para desarrolladores: https://www.socialecho.net/llms-developers.txt?lang=es
- Documentación oficial: https://www.socialecho.net/en/helpcenter/docs/socialecho-openapi-docs
- API Base URL: https://api.socialecho.net
- Fuente verificada: 2026-07-16

## Inicio rápido

1. Inicia sesión en https://app.socialecho.net y crea o selecciona un equipo.
2. Crea una Team API Key en Team Management.
3. Envía la clave mediante `Authorization: Bearer se_your_team_api_key`.
4. Llama primero a `GET /v1/team` para verificar la autenticación y el contexto del equipo.
5. Obtén los IDs de cuenta con `GET /v1/account` antes de consultar publicaciones, informes, publicar contenido o solicitar comunidades de Reddit y tableros de Pinterest.

## Autenticación y transporte

- Autenticación: Bearer Token con una Team API Key.
- Cabecera de autenticación: `Authorization: Bearer se_your_team_api_key`.
- Solicitudes JSON: `Content-Type: application/json`.
- Cabecera de idioma opcional: `X-Lang: zh_CN` o `X-Lang: en`.
- Límite: 120 solicitudes por minuto y por API Key.
- Nunca expongas una Team API Key en código del navegador, repositorios públicos, logs o prompts enviados a servicios no confiables.

Comportamiento importante: varias operaciones GET reciben parámetros en un cuerpo JSON y no en la query string. El `fetch` del navegador no admite cuerpos GET de forma fiable; usa cURL, una librería HTTP del servidor o un conector de automatización compatible.

## Criterios de éxito y errores

Una solicitud solo tiene éxito si se cumplen ambas condiciones:

- El estado HTTP es `200`.
- El campo JSON `code` es `200` o `0`.

Cualquier otro código de negocio debe tratarse como error aunque el estado HTTP sea `200`.

- `400 Bad Request`: valida campos obligatorios, fechas, arrays, tipos MIME y enums de plataforma.
- `401 Unauthorized`: comprueba la Team API Key y el formato exacto de la cabecera Bearer.
- `429 Too Many Requests`: limita el tráfico a menos de 120 solicitudes por minuto y reintenta con backoff exponencial, por ejemplo 1, 2 y 4 segundos.
- Timeout o error de red: reintenta dos o tres veces y registra endpoint, hora, estado HTTP, código de negocio y parámetros no sensibles.

## Endpoints disponibles

### GET /v1/team

Devuelve el equipo autenticado. Debe ser la primera llamada después de configurar una clave.

- Cuerpo: `{}` (opcional)
- Cabecera opcional: `X-Lang`

```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 cuentas sociales autorizadas o cuentas de competidores.

- `page`: entero opcional, número de página.
- `type`: entero opcional; `1` para cuentas autorizadas y `2` para competidores.

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

### GET /v1/article

Lista publicaciones del equipo o de cuentas seleccionadas.

- `page`: entero opcional, número de página.
- `account_ids`: array opcional de IDs enteros de cuentas SocialEcho.

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

### GET /v1/report

Devuelve analítica para un intervalo de fechas.

- `start_date`: string obligatorio con formato `YYYY-MM-DD`.
- `end_date`: string obligatorio con formato `YYYY-MM-DD`.
- `time_type`: entero obligatorio; `1` para publicaciones creadas en el período y `2` para publicaciones históricas medidas en el período.
- `account_ids`: array opcional de IDs enteros.
- `group`: string opcional; vacío para totales, o `day`, `app` o `account` para agrupar.

```bash
curl --request GET 'https://api.socialecho.net/v1/report' \
  --header 'Authorization: Bearer se_your_team_api_key' \
  --header 'Content-Type: application/json' \
  --header 'X-Lang: en' \
  --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

Devuelve información para subir un archivo. Flujo habitual: solicitar URL de subida → subir archivo → usar la URL resultante en `attachments` al publicar.

- `content_type`: tipo MIME obligatorio.
- Imágenes: `image/jpeg`, `image/jpg`, `image/png`, `image/gif`, `image/webp`, `image/bmp`.
- Videos: `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' \
  --header 'X-Lang: en' \
  --data-raw '{"content_type":"image/png"}'
```

### GET /v1/reddit/communities

Lista comunidades de Reddit disponibles para una cuenta conectada antes de publicar.

- `account_id`: entero obligatorio, ID de cuenta SocialEcho.

### GET /v1/pinterest/boards

Lista tableros de Pinterest disponibles para una cuenta conectada antes de publicar.

- `account_id`: entero obligatorio, ID de cuenta SocialEcho.

### POST /v1/publish/article

Crea un borrador, publica de inmediato o programa una publicación multiplataforma. Los campos específicos deben validarse contra la interfaz actual y la documentación OpenAPI oficial.

- `account_id`: entero obligatorio, ID de la cuenta destino.
- `type`: string obligatorio, tipo de publicación específico de plataforma.
- `status`: entero obligatorio; `0` para borrador y `1` para publicar.
- `scheduled_at`: hora opcional; con `status=1`, si se omite se publica inmediatamente.
- `comment`: array obligatorio de strings; puede estar vacío.
- `content`: texto opcional de la publicación.
- `extra`: objeto obligatorio con valores específicos, como título, ID de tablero o comunidad, enlace, indicador de borrador de TikTok o flair de Reddit.
- `attachments`: array obligatorio de objetos; cada elemento usa una URL subida, por ejemplo `{ "url": "https://..." }`.

Valores `type` habituales documentados por la OpenAPI:

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

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

## Flujo de integración recomendado

1. Verifica clave y equipo con `GET /v1/team`.
2. Obtén las cuentas autorizadas con `GET /v1/account` y guarda los IDs de SocialEcho.
3. En endpoints paginados, incrementa `page` hasta que `total` y `per_page` indiquen la última página.
4. Para publicar medios, llama a `GET /v1/upload/url`, sube el archivo y usa la URL resultante en `attachments`.
5. Obtén una comunidad de Reddit o un tablero de Pinterest antes de publicar allí.
6. Envía el payload final a `POST /v1/publish/article`.
7. Consulta `GET /v1/article` y `GET /v1/report` para cerrar el flujo desde publicación hasta analítica.

## Alcance actual de la API

La OpenAPI pública actual cubre equipo, cuentas, publicaciones, informes, URLs de subida, comunidades de Reddit, tableros de Pinterest y publicación. La documentación de origen no presenta endpoints de comentarios o mensajes directos ni un servidor MCP oficial como funciones activas; no deben darse por disponibles.

Para campos `extra` y restricciones de publicación que puedan cambiar, consulta la documentación oficial: https://www.socialecho.net/en/helpcenter/docs/socialecho-openapi-docs