Conjuntos e anúncios — Referência da API

PATCH /ad-sets/{id} campaigns:write

Alterar conjunto

Nome, orçamento e status (ligar ou pausar) de um conjunto, aplicados nessa ordem na Meta. O orçamento só muda aqui quando a verba é por conjunto; quando ela é da campanha, use PATCH /campaigns/{id}. Se um passo falhar, details.applied diz o que já mudou. Os ids dos conjuntos vêm em ad_sets de GET /campaigns/{id}.

Corpo

name	string	Novo nome (até 120 caracteres).
budget.amount_cents	integer	Novo orçamento do conjunto em centavos.
status	string	active ou paused.

Exemplo

cURL

curl -X PATCH "https://leadgo.com.br/api/v1/ad-sets/{id}" \
  -H "Authorization: Bearer $LEADGO_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "budget": {
        "amount_cents": 4000
    },
    "status": "active"
}'

Resposta 200

HTTP 200

{
    "data": {
        "id": 88,
        "campaign_id": "01jby0q4c8m2d6t9v3k7w5r1xa",
        "name": "Mulheres 25-45 SP",
        "status": "active",
        "budget": {
            "type": "daily",
            "amount_cents": 4000
        },
        "optimization_goal": "LINK_CLICKS",
        "targeting": {
            "geo_locations": {
                "countries": [
                    "BR"
                ]
            },
            "age_min": 25,
            "age_max": 45
        },
        "platform_ad_set_id": "120212345678900002",
        "ads": [
            {
                "id": 140,
                "campaign_id": "01jby0q4c8m2d6t9v3k7w5r1xa",
                "ad_set_id": 88,
                "name": "Promoção de outubro - Anúncio 1",
                "status": "active",
                "review_status": "APPROVED",
                "rejection_reason": null,
                "platform_ad_id": "120212345678900003",
                "creative": {
                    "headline": "Outono com 30% off",
                    "body": "Peças selecionadas com frete grátis até domingo.",
                    "description": null,
                    "call_to_action": "SHOP_NOW",
                    "link_url": "https://loja.exemplo.com.br/outubro",
                    "image_url": "https://cdn.zernio.com/u/outubro.jpg",
                    "video_id": null
                },
                "url_tags": null
            }
        ]
    }
}

Erros: validation_failed, not_found, not_toggleable, operation_failed, platform_rejected

DELETE /ad-sets/{id} campaigns:write

Excluir conjunto

Exclui de vez na Meta o conjunto e os anúncios dele. A campanha continua.

Exemplo

cURL

curl -X DELETE "https://leadgo.com.br/api/v1/ad-sets/{id}" \
  -H "Authorization: Bearer $LEADGO_TOKEN" \
  -H "Accept: application/json"

Resposta 204

Sem corpo.

Erros: not_found, platform_rejected

PATCH /ads/{id} campaigns:write

Alterar anúncio

Nome, criativo, UTMs e status de um anúncio publicado. No criativo, só o que vier muda: a Meta preserva o resto (inclusive a mídia e as UTMs) e revisa o anúncio de novo (review_status volta a PENDING_REVIEW). Para trocar a imagem, envie antes a nova em POST /media e use o id em creative.media_id; anúncios de vídeo trocam só texto, link, botão e UTMs. Mudar o criativo abre a janela de maturação do Gestor IA.

Corpo

name	string	Novo nome.
status	string	active ou paused.
creative.headline	string	Título (até 255).
creative.body	string	Texto principal (até 2000).
creative.description	string	Descrição (até 255).
creative.link_url	string	Link https de destino.
creative.call_to_action	string	Botão (veja GET /reference).
creative.media_id	string	Imagem nova, pronta na biblioteca (POST /media).
url_tags	object[]	UTMs {key, value} do anúncio: a lista enviada substitui a toda ([] remove todas). Até 10 extras além dos 4 padrão (utm_source, utm_medium, utm_campaign e utm_content), que não contam: a lista de uma campanha (os 4 + até 10 extras) cabe. Aceita as macros da Meta, como {{campaign.name}} e {{ad.name}}.

Exemplo

cURL

curl -X PATCH "https://leadgo.com.br/api/v1/ads/{id}" \
  -H "Authorization: Bearer $LEADGO_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "creative": {
        "headline": "Últimas peças com 40% off",
        "media_id": "01jbx3m7k2q8f5v9w4n6c0r1ht"
    },
    "url_tags": [
        {
            "key": "utm_source",
            "value": "facebook"
        },
        {
            "key": "utm_medium",
            "value": "paid"
        },
        {
            "key": "utm_campaign",
            "value": "{{campaign.name}}"
        },
        {
            "key": "utm_content",
            "value": "{{ad.name}}"
        }
    ]
}'

Resposta 200

HTTP 200

{
    "data": {
        "id": 140,
        "campaign_id": "01jby0q4c8m2d6t9v3k7w5r1xa",
        "ad_set_id": 88,
        "name": "Promoção de outubro - Anúncio 1",
        "status": "active",
        "review_status": "PENDING_REVIEW",
        "rejection_reason": null,
        "platform_ad_id": "120212345678900003",
        "creative": {
            "headline": "Outono com 30% off",
            "body": "Peças selecionadas com frete grátis até domingo.",
            "description": null,
            "call_to_action": "SHOP_NOW",
            "link_url": "https://loja.exemplo.com.br/outubro",
            "image_url": "https://cdn.zernio.com/u/outubro.jpg",
            "video_id": null
        },
        "url_tags": [
            {
                "key": "utm_source",
                "value": "facebook"
            },
            {
                "key": "utm_medium",
                "value": "paid"
            },
            {
                "key": "utm_campaign",
                "value": "{{campaign.name}}"
            },
            {
                "key": "utm_content",
                "value": "{{ad.name}}"
            }
        ]
    }
}

Erros: validation_failed, not_found, ad_not_published, ad_media_not_supported, boost_creative_locked, not_toggleable, operation_failed, platform_rejected

DELETE /ads/{id} campaigns:write

Excluir anúncio

Exclui de vez o anúncio na Meta. O conjunto e a campanha continuam.

Exemplo

cURL

curl -X DELETE "https://leadgo.com.br/api/v1/ads/{id}" \
  -H "Authorization: Bearer $LEADGO_TOKEN" \
  -H "Accept: application/json"

Resposta 204

Sem corpo.

Erros: not_found, platform_rejected

GET /ads/{id}/preview campaigns:read

Prévia do anúncio

Como o anúncio publicado aparece em cada posicionamento, gerado pela Meta. url é o endereço da prévia para abrir num <iframe> (expira em poucos minutos; não guarde); html é o trecho original da Meta. Formatos: MOBILE_FEED_STANDARD, INSTAGRAM_STANDARD, INSTAGRAM_STORY, INSTAGRAM_REELS, FACEBOOK_STORY_MOBILE, DESKTOP_FEED_STANDARD.

Parâmetros

formats

string

Formatos separados por vírgula (padrão: todos).

Exemplo

cURL

curl -X GET "https://leadgo.com.br/api/v1/ads/{id}/preview?formats=INSTAGRAM_STORY%2CMOBILE_FEED_STANDARD" \
  -H "Authorization: Bearer $LEADGO_TOKEN" \
  -H "Accept: application/json"

Resposta 200

HTTP 200

{
    "data": {
        "ad_id": 140,
        "previews": [
            {
                "format": "INSTAGRAM_STORY",
                "label": "Stories do Instagram",
                "url": "https://www.facebook.com/ads/api/preview_iframe.php?d=AQ...&t=AQ...",
                "html": "<iframe src=\"https://www.facebook.com/ads/api/preview_iframe.php?d=AQ...&t=AQ...\" width=\"274\" height=\"213\" scrolling=\"yes\" style=\"border: none;\"></iframe>"
            }
        ]
    }
}

Erros: validation_failed, not_found, ad_not_published, platform_quota_exceeded, platform_unavailable