Anuncios

Campañas en Meta, Google, LinkedIn, TikTok, Pinterest, X y Reddit con una conexión de anuncios (plataforma meta-ads, google-ads…): listarlas con gasto y resultados, pausar, reanudar, cambiar presupuestos, promocionar publicaciones, crear campañas y enviar conversiones. Los presupuestos van en unidades enteras de la moneda, nunca en céntimos.

Listar cuentas publicitarias

GET/v1/accounts/{id}/ads/ad-accounts

Las cuentas publicitarias a las que llega una conexión de anuncios. Su id es el adAccountId del resto de llamadas.

Parámetros

idstringobligatorio

Respuesta 200

data []

idstringobligatorio
Envíalo como adAccountId (act_… en Meta, el id de cliente en Google…).
namestringobligatorio
currencystring
Presupuestos y pujas van en unidades enteras de ella.
timezonestring
usablebooleanobligatorio
False si la red no deja anunciarse con ella (desactivada, sin método de pago…).

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

const res = await fetch('https://api.marsial.dev/v1/accounts/acc_3k9x2m/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_3k9x2m/ads/ad-accounts",
    headers={"Authorization": f"Bearer {os.environ['MARSIAL_API_KEY']}"},
)
data = res.json()["data"]

Listar campañas con sus resultados

GET/v1/accounts/{id}/ads/campaigns

Las campañas creadas en Marsial y en el administrador de anuncios de la red, con gasto, impresiones y clics del periodo.

Parámetros

idstringobligatorio
adAccountIdstring
Solo esta cuenta publicitaria (GET …/ads/ad-accounts).
máx. 100
fromstring
Primer día de las métricas (YYYY-MM-DD). Hace 90 días si no lo envías.
tostring
Último día de las métricas (YYYY-MM-DD). Hoy si no lo envías.

Respuesta 200

data []

idstringobligatorio
El id de la campaña en la red.
accountIdstringobligatorio
La conexión de anuncios.
networkstringobligatorio
facebook, instagram, google, linkedin, tiktok, pinterest, twitter o reddit.
namestringobligatorio
statusstringobligatorio
reviewStatusstring
adAccountIdstringobligatorio
adAccountNamestring
currencystring
budgetobject
budget
- amountnumberobligatorio
- typestringobligatorio
adCountintegerobligatorio
máx. 9.007.199.254.740.991
metricsobjectobligatorio
metrics
- spendnumberobligatorio
- impressionsnumberobligatorio
- clicksnumberobligatorio
- reachnumber
- conversionsnumber
- ctrnumber
- cpcnumber
- cpmnumber

curl "https://api.marsial.dev/v1/accounts/acc_3k9x2m/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_3k9x2m/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_3k9x2m/ads/campaigns?from=2026-10-01&to=2026-10-31",
    headers={"Authorization": f"Bearer {os.environ['MARSIAL_API_KEY']}"},
)
data = res.json()["data"]

Crear una campaña

POST/v1/accounts/{id}/ads/campaigns

Campaña, grupo de anuncios y anuncio en una llamada, en los términos de cada red (adAccountId, goal, budgetAmount, budgetType, la creatividad, la segmentación…): ver la guía de anuncios. Marsial rellena la conexión.

Parámetros

idstringobligatorio

Cuerpo

Respuesta 201

data

campaignIdstring | nullobligatorio

curl -X POST "https://api.marsial.dev/v1/accounts/acc_3k9x2m/ads/campaigns" \
  -H "Authorization: Bearer $MARSIAL_API_KEY"

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

import os, requests

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

Pausar, reanudar o cambiar el presupuesto

PATCH/v1/accounts/{id}/ads/campaigns/{campaignId}

Pausar se aplica siempre al momento. Reanudar y cambiar el presupuesto responden 202 cuando el espacio exige aprobación a quien llama.

Parámetros

idstringobligatorio
campaignIdstringobligatorio

Cuerpo

statusstring
Valores: active · paused
budgetobject
budget
- amountnumberobligatorio
  Unidades enteras de la moneda de la cuenta publicitaria: 50 son 50,00, nunca céntimos.
- typestringobligatorio
  Valores: daily · lifetime

Respuesta 200

data

idstringobligatorio
El id de la campaña en la red.
accountIdstringobligatorio
La conexión de anuncios.
networkstringobligatorio
facebook, instagram, google, linkedin, tiktok, pinterest, twitter o reddit.
namestringobligatorio
statusstringobligatorio
reviewStatusstring
adAccountIdstringobligatorio
adAccountNamestring
currencystring
budgetobject
budget
- amountnumberobligatorio
- typestringobligatorio
adCountintegerobligatorio
máx. 9.007.199.254.740.991
metricsobjectobligatorio
metrics
- spendnumberobligatorio
- impressionsnumberobligatorio
- clicksnumberobligatorio
- reachnumber
- conversionsnumber
- ctrnumber
- cpcnumber
- cpmnumber

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

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

import os, requests

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

Enviar conversiones

POST/v1/accounts/{id}/ads/conversions

Eventos desde el servidor para la red: la API de conversiones de Meta, las conversiones offline de Google, LinkedIn y TikTok.

Parámetros

idstringobligatorio

Cuerpo

Respuesta 200

data

receivedintegerobligatorio
máx. 9.007.199.254.740.991

curl -X POST "https://api.marsial.dev/v1/accounts/acc_3k9x2m/ads/conversions" \
  -H "Authorization: Bearer $MARSIAL_API_KEY"

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

import os, requests

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

Promocionar una publicación

POST/v1/posts/{id}/boost

Convierte una copia publicada de la publicación (su accountId) en un anuncio pagado por adAccountId. La red lo revisa antes de mostrarlo.

Parámetros

idstringobligatorio

Cuerpo

accountIdstringobligatorio
La cuenta de la publicación cuya copia publicada promocionar.
adAccountIdstringobligatorio
La cuenta publicitaria que paga (GET /v1/accounts/{id}/ads/ad-accounts en la conexión de anuncios).
máx. 100
namestringobligatorio
máx. 200
goalstringobligatorio
Lo que optimiza la red. Cada red acepta una parte.
Valores: engagement · traffic · awareness · video_views · lead_generation · conversions · app_promotion
budgetobjectobligatorio
budget
- amountnumberobligatorio
  Unidades enteras de la moneda de la cuenta publicitaria: 50 son 50,00, nunca céntimos.
- typestringobligatorio
  Valores: daily · lifetime
startDatestring (date-time)
endDatestring (date-time)
Obligatorio con un presupuesto total.
targetingobject
targeting
- countriesstring[]
  Códigos de país ISO.
  máx. 50 elementos
- ageMininteger
  mín. 13máx. 65
- ageMaxinteger
  mín. 13máx. 65
callToActionstring
Por ejemplo LEARN_MORE o SHOP_NOW; necesita linkUrl.
máx. 50
linkUrlstring (uri)

Respuesta 201

data

campaignIdstring | nullobligatorio

curl -X POST "https://api.marsial.dev/v1/posts/pst_7q1w0e/boost" \
  -H "Authorization: Bearer $MARSIAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acc_3k9x2m",
    "adAccountId": "act_120210",
    "name": "Autumn",
    "goal": "traffic",
    "budget": {
      "amount": 40,
      "type": "daily"
    }
  }'

const res = await fetch('https://api.marsial.dev/v1/posts/pst_7q1w0e/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": "Autumn",
    "goal": "traffic",
    "budget": {
      "amount": 40,
      "type": "daily"
    }
  }),
});
const { data } = await res.json();

import os, requests

res = requests.post(
    "https://api.marsial.dev/v1/posts/pst_7q1w0e/boost",
    headers={"Authorization": f"Bearer {os.environ['MARSIAL_API_KEY']}"},
    json={
        "accountId": "acc_3k9x2m",
        "adAccountId": "act_120210",
        "name": "Autumn",
        "goal": "traffic",
        "budget": {
            "amount": 40,
            "type": "daily"
        }
    },
)
data = res.json()["data"]

Listar los cambios de anuncios por aprobar

GET/v1/ads/requests

Con requireAdsApproval activado, los miembros y los agentes de IA (MCP) piden los cambios de anuncios que gastan dinero en vez de hacerlos. Del más reciente al más antiguo, con lo que pasó con cada uno.

Parámetros

statusstring
Solo los cambios en este estado; si no, todos, del más reciente al más antiguo.
Valores: pending · approved · rejected · failed

Respuesta 200

data []

idstringobligatorio
adr_…
changeobject | object | objectobligatorio
Lo que llega a la red al aprobarlo.
change
- kind"update_campaign"obligatorio
- accountIdstringobligatorio
- campaignIdstringobligatorio
- campaignNamestringobligatorio
- currencystring
- currentobjectobligatorio
  La campaña cuando se pidió el cambio.
  current
  - statusstringobligatorio
  - budgetobject
    budget
    amountnumberobligatorio
    typestringobligatorio
- statusstring
  Valores: active · paused
- budgetobject
  budget
  - amountnumberobligatorio
  - typestringobligatorio
statusstringobligatorio
failed: aprobado, pero la red lo rechazó (ver error).
Valores: pending · approved · rejected · failed
requestedBystring
El usuario que lo pidió, o por quien lo pidió un agente de IA.
viastringobligatorio
Valores: agent · person
requestedAtstring (date-time)obligatorio
decidedBystring
decidedAtstring (date-time)
notestring
campaignIdstring
La campaña que creó una promoción o campaña aprobada.
errorstring

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"]

Ver un cambio de anuncios pedido

GET/v1/ads/requests/{id}

Parámetros

idstringobligatorio

Respuesta 200

data

idstringobligatorio
adr_…
changeobject | object | objectobligatorio
Lo que llega a la red al aprobarlo.
change
- kind"update_campaign"obligatorio
- accountIdstringobligatorio
- campaignIdstringobligatorio
- campaignNamestringobligatorio
- currencystring
- currentobjectobligatorio
  La campaña cuando se pidió el cambio.
  current
  - statusstringobligatorio
  - budgetobject
    budget
    amountnumberobligatorio
    typestringobligatorio
- statusstring
  Valores: active · paused
- budgetobject
  budget
  - amountnumberobligatorio
  - typestringobligatorio
statusstringobligatorio
failed: aprobado, pero la red lo rechazó (ver error).
Valores: pending · approved · rejected · failed
requestedBystring
El usuario que lo pidió, o por quien lo pidió un agente de IA.
viastringobligatorio
Valores: agent · person
requestedAtstring (date-time)obligatorio
decidedBystring
decidedAtstring (date-time)
notestring
campaignIdstring
La campaña que creó una promoción o campaña aprobada.
errorstring

curl "https://api.marsial.dev/v1/ads/requests/adr_3m8p2q" \
  -H "Authorization: Bearer $MARSIAL_API_KEY"

const res = await fetch('https://api.marsial.dev/v1/ads/requests/adr_3m8p2q', {
  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/adr_3m8p2q",
    headers={"Authorization": f"Bearer {os.environ['MARSIAL_API_KEY']}"},
)
data = res.json()["data"]

Aprobar o rechazar un cambio de anuncios

POST/v1/ads/requests/{id}/review

Propietarios y admins (y claves API). Al aprobar se envía a la red en el momento; si la red lo rechaza, la solicitud queda failed con el motivo. Los agentes de IA no pueden revisar.

Parámetros

idstringobligatorio

Cuerpo

decisionstringobligatorio
approve envía el cambio a la red en el momento; reject lo descarta.
Valores: approve · reject
notestring
Por qué, para quien lo pidió.
máx. 1000

Respuesta 200

data

idstringobligatorio
adr_…
changeobject | object | objectobligatorio
Lo que llega a la red al aprobarlo.
change
- kind"update_campaign"obligatorio
- accountIdstringobligatorio
- campaignIdstringobligatorio
- campaignNamestringobligatorio
- currencystring
- currentobjectobligatorio
  La campaña cuando se pidió el cambio.
  current
  - statusstringobligatorio
  - budgetobject
    budget
    amountnumberobligatorio
    typestringobligatorio
- statusstring
  Valores: active · paused
- budgetobject
  budget
  - amountnumberobligatorio
  - typestringobligatorio
statusstringobligatorio
failed: aprobado, pero la red lo rechazó (ver error).
Valores: pending · approved · rejected · failed
requestedBystring
El usuario que lo pidió, o por quien lo pidió un agente de IA.
viastringobligatorio
Valores: agent · person
requestedAtstring (date-time)obligatorio
decidedBystring
decidedAtstring (date-time)
notestring
campaignIdstring
La campaña que creó una promoción o campaña aprobada.
errorstring

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"]