Anuncios

Los anuncios van por una conexión de anuncios: una cuenta más del perfil, con plataforma meta-ads, google-ads, linkedin-ads, tiktok-ads, pinterest-ads, x-ads o reddit-ads. No publica: llega a una o varias cuentas publicitarias de la red, que son las que pagan.

Conectar

GET /v1/connect/meta-ads (o la plataforma que toque) y mandar al usuario a la URL, como cualquier conexión:

Meta usa el inicio de sesión para empresas de Meta: no crea ninguna cuenta de Facebook para publicar. Quien conecta debe ser administrador del portfolio empresarial.
LinkedIn, TikTok, Pinterest y Google: si la cuenta social del perfil ya dio permiso de anuncios, vuelve al momento sin pedir nada.
X Ads cuelga de la cuenta de X del perfil: conéctala antes.

Luego lista sus cuentas publicitarias. Su id es el adAccountId del resto de llamadas.

curl "https://api.marsial.dev/v1/accounts/acc_ads123/ads/ad-accounts" \
  -H "Authorization: Bearer $MARSIAL_API_KEY"

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

import os, requests

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

Resultados y control

curl "https://api.marsial.dev/v1/accounts/acc_ads123/ads/campaigns?from=2026-10-01&to=2026-10-31" \
  -H "Authorization: Bearer $MARSIAL_API_KEY"

const res = await fetch('https://api.marsial.dev/v1/accounts/acc_ads123/ads/campaigns?from=2026-10-01&to=2026-10-31', {
  headers: {
    Authorization: `Bearer ${process.env.MARSIAL_API_KEY}`,
  },
});
const { data } = await res.json();

import os, requests

res = requests.get(
    "https://api.marsial.dev/v1/accounts/acc_ads123/ads/campaigns?from=2026-10-01&to=2026-10-31",
    headers={"Authorization": f"Bearer {os.environ['MARSIAL_API_KEY']}"},
)
data = res.json()["data"]

Devuelve las campañas (también las creadas en el administrador de anuncios de la red) con gasto, impresiones, clics, alcance y conversiones del periodo. Para pausar, reanudar o cambiar el presupuesto:

curl -X PATCH "https://api.marsial.dev/v1/accounts/acc_ads123/ads/campaigns/120210000000" \
  -H "Authorization: Bearer $MARSIAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "paused",
    "budget": {
      "amount": 25,
      "type": "daily"
    }
  }'

const res = await fetch('https://api.marsial.dev/v1/accounts/acc_ads123/ads/campaigns/120210000000', {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.MARSIAL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "status": "paused",
    "budget": {
      "amount": 25,
      "type": "daily"
    }
  }),
});
const { data } = await res.json();

import os, requests

res = requests.patch(
    "https://api.marsial.dev/v1/accounts/acc_ads123/ads/campaigns/120210000000",
    headers={"Authorization": f"Bearer {os.environ['MARSIAL_API_KEY']}"},
    json={
        "status": "paused",
        "budget": {
            "amount": 25,
            "type": "daily"
        }
    },
)
data = res.json()["data"]

Promocionar una publicación

Convierte la copia publicada de una publicación de Marsial en anuncio. accountId es la cuenta de esa copia (por ejemplo, el Instagram) y adAccountId, la cuenta publicitaria que paga.

curl -X POST "https://api.marsial.dev/v1/posts/pst_9f2a/boost" \
  -H "Authorization: Bearer $MARSIAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acc_3k9x2m",
    "adAccountId": "act_120210",
    "name": "Otoño",
    "goal": "traffic",
    "budget": {
      "amount": 40,
      "type": "daily"
    },
    "targeting": {
      "countries": [
        "ES",
        "PT"
      ],
      "ageMin": 25,
      "ageMax": 45
    }
  }'

const res = await fetch('https://api.marsial.dev/v1/posts/pst_9f2a/boost', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.MARSIAL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "accountId": "acc_3k9x2m",
    "adAccountId": "act_120210",
    "name": "Otoño",
    "goal": "traffic",
    "budget": {
      "amount": 40,
      "type": "daily"
    },
    "targeting": {
      "countries": [
        "ES",
        "PT"
      ],
      "ageMin": 25,
      "ageMax": 45
    }
  }),
});
const { data } = await res.json();

import os, requests

res = requests.post(
    "https://api.marsial.dev/v1/posts/pst_9f2a/boost",
    headers={"Authorization": f"Bearer {os.environ['MARSIAL_API_KEY']}"},
    json={
        "accountId": "acc_3k9x2m",
        "adAccountId": "act_120210",
        "name": "Otoño",
        "goal": "traffic",
        "budget": {
            "amount": 40,
            "type": "daily"
        },
        "targeting": {
            "countries": [
                "ES",
                "PT"
            ],
            "ageMin": 25,
            "ageMax": 45
        }
    },
)
data = res.json()["data"]

goal es lo que optimiza la red (engagement, traffic, awareness, video_views…; cada red acepta una parte). Un presupuesto lifetime necesita endDate. La red revisa el anuncio antes de mostrarlo.

Crear campañas

POST /v1/accounts/{id}/ads/campaigns crea campaña, grupo de anuncios y anuncio en una sola llamada, en los términos de cada red: adAccountId, goal, budgetAmount, budgetType, la creatividad (headline, body, imageUrl o videoUrl, linkUrl, callToAction) y la segmentación. Marsial rellena la conexión; tú no envíes accountId.

curl -X POST "https://api.marsial.dev/v1/accounts/acc_ads123/ads/campaigns" \
  -H "Authorization: Bearer $MARSIAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "adAccountId": "act_120210",
    "name": "Rebajas",
    "goal": "traffic",
    "budgetAmount": 30,
    "budgetType": "daily",
    "headline": "Rebajas de invierno",
    "body": "Hasta un 40% en abrigos",
    "imageUrl": "https://cdn.acme.com/rebajas.jpg",
    "linkUrl": "https://acme.com/rebajas",
    "callToAction": "SHOP_NOW",
    "targeting": {
      "countries": [
        "ES"
      ]
    }
  }'

const res = await fetch('https://api.marsial.dev/v1/accounts/acc_ads123/ads/campaigns', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.MARSIAL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "adAccountId": "act_120210",
    "name": "Rebajas",
    "goal": "traffic",
    "budgetAmount": 30,
    "budgetType": "daily",
    "headline": "Rebajas de invierno",
    "body": "Hasta un 40% en abrigos",
    "imageUrl": "https://cdn.acme.com/rebajas.jpg",
    "linkUrl": "https://acme.com/rebajas",
    "callToAction": "SHOP_NOW",
    "targeting": {
      "countries": [
        "ES"
      ]
    }
  }),
});
const { data } = await res.json();

import os, requests

res = requests.post(
    "https://api.marsial.dev/v1/accounts/acc_ads123/ads/campaigns",
    headers={"Authorization": f"Bearer {os.environ['MARSIAL_API_KEY']}"},
    json={
        "adAccountId": "act_120210",
        "name": "Rebajas",
        "goal": "traffic",
        "budgetAmount": 30,
        "budgetType": "daily",
        "headline": "Rebajas de invierno",
        "body": "Hasta un 40% en abrigos",
        "imageUrl": "https://cdn.acme.com/rebajas.jpg",
        "linkUrl": "https://acme.com/rebajas",
        "callToAction": "SHOP_NOW",
        "targeting": {
            "countries": [
                "ES"
            ]
        }
    },
)
data = res.json()["data"]

Conversiones

Devuelve ventas y leads a la red para que optimice mejor: la API de conversiones de Meta, las conversiones offline de Google, LinkedIn y TikTok.

curl -X POST "https://api.marsial.dev/v1/accounts/acc_ads123/ads/conversions" \
  -H "Authorization: Bearer $MARSIAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pixelId": "1234567890",
    "events": [
      {
        "eventName": "Purchase",
        "eventTime": 1793000000,
        "user": {
          "email": "ana@acme.com"
        },
        "value": 59.9,
        "currency": "EUR"
      }
    ]
  }'

const res = await fetch('https://api.marsial.dev/v1/accounts/acc_ads123/ads/conversions', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.MARSIAL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "pixelId": "1234567890",
    "events": [
      {
        "eventName": "Purchase",
        "eventTime": 1793000000,
        "user": {
          "email": "ana@acme.com"
        },
        "value": 59.9,
        "currency": "EUR"
      }
    ]
  }),
});
const { data } = await res.json();

import os, requests

res = requests.post(
    "https://api.marsial.dev/v1/accounts/acc_ads123/ads/conversions",
    headers={"Authorization": f"Bearer {os.environ['MARSIAL_API_KEY']}"},
    json={
        "pixelId": "1234567890",
        "events": [
            {
                "eventName": "Purchase",
                "eventTime": 1793000000,
                "user": {
                    "email": "ana@acme.com"
                },
                "value": 59.9,
                "currency": "EUR"
            }
        ]
    },
)
data = res.json()["data"]

Aprobación de cambios

Si activas la aprobación de anuncios (PATCH /v1/workspace con requireAdsApproval: true, o en el panel, Ajustes → Equipo), lo que gasta dinero (reanudar, cambiar presupuestos, promocionar y crear campañas) no llega a la red cuando lo piden miembros o agentes de IA: la API responde 202 con la solicitud (adr_…, status: "pending") y un propietario o admin la aprueba o la rechaza. Pausar se aplica siempre al momento, porque solo deja de gastar. Las claves API usadas en /v1 son tu integración y no esperan; un agente que entra por el servidor MCP siempre espera, aunque actúe por un propietario.

curl "https://api.marsial.dev/v1/ads/requests?status=pending" \
  -H "Authorization: Bearer $MARSIAL_API_KEY"

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

import os, requests

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

curl -X POST "https://api.marsial.dev/v1/ads/requests/adr_3m8p2q/review" \
  -H "Authorization: Bearer $MARSIAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "decision": "approve"
  }'

const res = await fetch('https://api.marsial.dev/v1/ads/requests/adr_3m8p2q/review', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.MARSIAL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "decision": "approve"
  }),
});
const { data } = await res.json();

import os, requests

res = requests.post(
    "https://api.marsial.dev/v1/ads/requests/adr_3m8p2q/review",
    headers={"Authorization": f"Bearer {os.environ['MARSIAL_API_KEY']}"},
    json={
        "decision": "approve"
    },
)
data = res.json()["data"]

Al aprobar, el cambio se envía a la red en ese momento y la solicitud queda approved; si la red lo rechaza, queda failed con el motivo en error. Con reject puedes dejar una note para quien lo pidió. Los agentes de IA nunca pueden aprobar.

Lo que cuesta

El gasto en anuncios lo pagas directamente a cada red, en su cuenta publicitaria. Marsial cobra la conexión como una cuenta más y, a partir de 500 anuncios activos, cada anuncio gestionado (tarifas).

En el panel, la sección Anuncios muestra las campañas y deja pausarlas y cambiar su presupuesto; el detalle de una publicación publicada tiene el botón para promocionarla. Los agentes de IA pueden hacer lo mismo por el servidor MCP.