Conectar cuentas

Tus usuarios conectan sus redes desde tu app, con tu marca. Nunca ven las credenciales ni tú tienes que guardar tokens.

El flujo

1. Tu servidor pide GET /v1/connect/{platform} con el profileId y la redirectUrl de tu app.
2. Rediriges al usuario a la url que devuelve. Autoriza la red con su cuenta.
3. Marsial le devuelve a tu redirectUrl con el resultado en la query.

curl

curl "https://api.marsial.dev/v1/connect/linkedin?profileId=prf_8f2k4d&redirectUrl=https%3A%2F%2Fapp.acme.com%2Fconectado" \
  -H "Authorization: Bearer $MARSIAL_API_KEY"

Node

const res = await fetch('https://api.marsial.dev/v1/connect/linkedin?profileId=prf_8f2k4d&redirectUrl=https%3A%2F%2Fapp.acme.com%2Fconectado', {
  headers: {
    Authorization: `Bearer ${process.env.MARSIAL_API_KEY}`,
  },
});
const { data } = await res.json();

Python

import os, requests

res = requests.get(
    "https://api.marsial.dev/v1/connect/linkedin?profileId=prf_8f2k4d&redirectUrl=https%3A%2F%2Fapp.acme.com%2Fconectado",
    headers={"Authorization": f"Bearer {os.environ['MARSIAL_API_KEY']}"},
)
data = res.json()["data"]

Qué llega a tu redirectUrl

Resultado	Parámetros
Conectada	connected=<platform>, accountId=acc_… y, si la red lo da, username
Siempre	profileId: el perfil al que se conectó
Falta elegir	select=<sessionId> y platform. Mira el paso siguiente.
Error	error=<código>, platform, error_message e is_user_fixable (true si el usuario puede reintentarlo)

Elegir página, organización o tablero

Algunas redes conectan algo concreto dentro de la cuenta del usuario. Entonces vuelve con select y tu app enseña la lista para que elija:

Red	Qué se elige
Facebook	La página
LinkedIn	Su perfil personal o una organización que administra
Pinterest	El tablero por defecto
Google Business	La ficha (ubicación)
Snapchat	El perfil público
Slack	El canal
WhatsApp	El número, si la cuenta tiene varios

Bluesky y Discord no usan OAuth puro, pero no necesitas nada distinto: la pantalla de conexión de Marsial pide al usuario lo que haga falta (la contraseña de aplicación de Bluesky o el canal de Discord) y vuelve a tu redirectUrl con connected. Slack vuelve con select=<sessionId> para elegir el canal, como Facebook o LinkedIn; un canal privado necesita que invites antes a la app (/invite).

Los sitios (WordPress, Shopify, Wix y Webflow) también se conectan aquí, con dos diferencias: Shopify necesita shop y WordPress autoalojado se conecta con POST /v1/connect/wordpress. Está todo en Blogs.

Lista las opciones

curl

curl "https://api.marsial.dev/v1/connect/sessions/cs_5t2y8u/options" \
  -H "Authorization: Bearer $MARSIAL_API_KEY"

Node

const res = await fetch('https://api.marsial.dev/v1/connect/sessions/cs_5t2y8u/options', {
  headers: {
    Authorization: `Bearer ${process.env.MARSIAL_API_KEY}`,
  },
});
const { data } = await res.json();

Python

import os, requests

res = requests.get(
    "https://api.marsial.dev/v1/connect/sessions/cs_5t2y8u/options",
    headers={"Authorization": f"Bearer {os.environ['MARSIAL_API_KEY']}"},
)
data = res.json()["data"]

200 OK

{
  "data": {
    "platform": "facebook",
    "options": [
      { "id": "1042…", "name": "Acme Store", "detail": "@acmestore" },
      { "id": "2210…", "name": "Acme Outlet", "detail": "Tienda de ropa" }
    ]
  }
}

Envía la elegida

curl

curl -X POST "https://api.marsial.dev/v1/connect/sessions/cs_5t2y8u/select" \
  -H "Authorization: Bearer $MARSIAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "optionId": "1042…"
  }'

Node

const res = await fetch('https://api.marsial.dev/v1/connect/sessions/cs_5t2y8u/select', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.MARSIAL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "optionId": "1042…"
  }),
});
const { data } = await res.json();

Python

import os, requests

res = requests.post(
    "https://api.marsial.dev/v1/connect/sessions/cs_5t2y8u/select",
    headers={"Authorization": f"Bearer {os.environ['MARSIAL_API_KEY']}"},
    json={
        "optionId": "1042…"
    },
)
data = res.json()["data"]

Devuelve la cuenta conectada (201). La sesión caduca a la hora.

Redes disponibles

instagram, facebook, tiktok, youtube, linkedin, x, threads, bluesky, pinterest, reddit, google-business, discord y snapchat. Telegram llegará pronto.

Listar y vigilar cuentas

curl

curl "https://api.marsial.dev/v1/accounts?profileId=prf_8f2k4d" \
  -H "Authorization: Bearer $MARSIAL_API_KEY"

Node

const res = await fetch('https://api.marsial.dev/v1/accounts?profileId=prf_8f2k4d', {
  headers: {
    Authorization: `Bearer ${process.env.MARSIAL_API_KEY}`,
  },
});
const { data } = await res.json();

Python

import os, requests

res = requests.get(
    "https://api.marsial.dev/v1/accounts?profileId=prf_8f2k4d",
    headers={"Authorization": f"Bearer {os.environ['MARSIAL_API_KEY']}"},
)
data = res.json()["data"]

Cada cuenta tiene un status: active, needs_reconnection (el token caducó o el usuario quitó permisos) o disconnected. Para comprobar en el momento si pueden publicar, usa GET /v1/accounts/health. Si una cuenta pide reconexión, repite el flujo con la misma red y perfil.