{
"openapi": "3.1.0",
"info": {
"title": "API LeadGo",
"version": "1.2.0",
"description": "Crie e opere campanhas de Meta Ads pelas mesmas rotinas do painel. Guia completo: https://leadgo.com.br/docs/api"
},
"servers": [
{
"url": "https://leadgo.com.br/api/v1"
}
],
"security": [
{
"bearerAuth": []
}
],
"tags": [
{
"name": "Conta e conta de anúncio",
"description": "Quem é o token, a conta de anúncio vinculada, o que ela oferece às campanhas (Pixels, formulários, perfis do Instagram), a saúde, o saldo e os alertas."
},
{
"name": "Listas e segmentação",
"description": "Valores aceitos na criação, busca de cidades e interesses e estimativa de alcance."
},
{
"name": "Mídias",
"description": "Imagens e vídeos dos anúncios. Envie uma vez e use o id em quantas campanhas quiser."
},
{
"name": "Campanhas",
"description": "Criar, consultar, alterar, duplicar e excluir campanhas, pelas mesmas rotinas do painel."
},
{
"name": "Conjuntos e anúncios",
"description": "Operar cada conjunto e cada anúncio publicado: verba, status, nome, troca do criativo e das UTMs, prévia."
},
{
"name": "Personas e padrões",
"description": "Públicos salvos (à mão ou sugeridos pela IA) e padrões de campanha: criar, alterar, excluir e reaproveitar."
},
{
"name": "Públicos",
"description": "Remarketing (visitantes do site, engajamento com a Página e o Instagram), compradores e os públicos que já existem na Meta, para incluir ou excluir na segmentação."
},
{
"name": "Métricas e relatórios",
"description": "Resultados da conta, de cada campanha e de cada anúncio, lidos da Meta (atualizam a cada 15–60 min)."
},
{
"name": "Leads",
"description": "Leads dos formulários instantâneos e o funil comercial: listar, consultar, mudar a etapa, registrar venda e perda, notas e exclusão (LGPD)."
},
{
"name": "Gestor IA",
"description": "Relatórios da IA que acompanha a conta: pedir análise, aprovar ou recusar as ações propostas e desfazer as aplicadas."
},
{
"name": "Rascunho pela IA",
"description": "A IA do LeadGo monta a campanha a partir de um briefing; você revisa e cria."
},
{
"name": "Webhooks",
"description": "URLs do seu sistema que recebem os avisos das campanhas e das mídias."
}
],
"paths": {
"/me": {
"get": {
"operationId": "api.v1.me",
"tags": [
"Conta e conta de anúncio"
],
"externalDocs": {
"url": "https://leadgo.com.br/docs/api/referencia/conta#me"
},
"summary": "Conferir o token",
"description": "A conta que o token opera, quem o criou e os escopos. Bom primeiro teste da integração.",
"responses": {
"200": {
"description": "Conferir o token",
"content": {
"application/json": {
"example": {
"data": {
"token": {
"id": "01jbw9t3b7e1h5m9q3v7z1d5gk",
"name": "Loja virtual",
"prefix": "lgo_x7Kp2mQa",
"abilities": [
"campaigns:read",
"campaigns:write",
"media:write",
"reports:read",
"ai:draft",
"webhooks:manage",
"account:manage",
"leads:read",
"leads:write",
"brain:read",
"brain:manage"
],
"expires_at": "2027-10-28T15:00:00+00:00",
"created_at": "2026-10-28T15:00:00+00:00"
},
"account": {
"id": "01jbw8r5x9a3d7g1k5n9s3w7b1",
"name": "Loja Exemplo",
"timezone": "America/Sao_Paulo",
"is_managed_client": false
},
"user": {
"id": 42,
"name": "Ana Souza",
"email": "ana@loja.exemplo.com.br"
},
"rate_limit": {
"requests_per_minute": 120
}
}
}
}
}
},
"401": {
"description": "Sem o cabeçalho Authorization ou com um token que não existe.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"402": {
"description": "A conta não tem um plano ativo.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Limite de requisições.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/ad-account": {
"get": {
"operationId": "api.v1.ad-account.show",
"tags": [
"Conta e conta de anúncio"
],
"externalDocs": {
"url": "https://leadgo.com.br/docs/api/referencia/conta#ad-account-show"
},
"summary": "Conta de anúncio vinculada",
"description": "Onde as campanhas são criadas: moeda, fuso, verba diária mínima, Pixel padrão e a Página do Facebook da conexão. Cada conta opera uma única conta de anúncio, escolhida em Integrações no painel.\n\nEscopo: `campaigns:read`.",
"responses": {
"200": {
"description": "Conta de anúncio vinculada",
"content": {
"application/json": {
"example": {
"data": {
"id": 12,
"name": "Loja Exemplo · Meta",
"platform": "meta",
"platform_ad_account_id": "act_1234567890",
"currency": "BRL",
"timezone": "America/Sao_Paulo",
"minimum_daily_budget_cents": 600,
"default_pixel_id": "123456789012345",
"payment_method_missing": false,
"page": {
"id": "998877665544",
"name": "Loja Exemplo"
},
"connection_status": "connected",
"last_synced_at": "2026-10-28T14:40:00+00:00"
}
}
}
}
},
"409": {
"description": "A conta ainda não vinculou uma conta de anúncio da Meta.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Token ausente, inválido, revogado ou vencido.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Limite de requisições.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
},
"patch": {
"operationId": "api.v1.ad-account.update",
"tags": [
"Conta e conta de anúncio"
],
"externalDocs": {
"url": "https://leadgo.com.br/docs/api/referencia/conta#ad-account-update"
},
"summary": "Alterar o limite de gasto",
"description": "Define o limite de gasto da conta de anúncio: ao chegar nele, a Meta pausa todas as campanhas. null remove o limite. Responde o saldo atualizado.\n\nEscopo: `account:manage`.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"spend_cap_cents": {
"type": "integer",
"description": "Limite em centavos (mínimo 100) ou null para remover."
}
},
"required": [
"spend_cap_cents"
]
},
"example": {
"spend_cap_cents": 5000000
}
}
}
},
"responses": {
"200": {
"description": "Alterar o limite de gasto",
"content": {
"application/json": {
"example": {
"data": {
"currency": "BRL",
"balance_cents": 0,
"amount_spent_cents": 1834590,
"spend_cap_cents": 5000000,
"funding_source": "Mastercard *4985"
}
}
}
}
},
"422": {
"description": "Campos inválidos; o detalhe de cada um vem em errors.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "A conta ainda não vinculou uma conta de anúncio da Meta.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Muitas consultas novas à plataforma (buscas e métricas fora do cache).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Token ausente, inválido, revogado ou vencido.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/ad-account/pixels": {
"get": {
"operationId": "api.v1.ad-account.pixels",
"tags": [
"Conta e conta de anúncio"
],
"externalDocs": {
"url": "https://leadgo.com.br/docs/api/referencia/conta#ad-account-pixels"
},
"summary": "Pixels da conta",
"description": "Pixels (conjuntos de dados) que a conta de anúncio enxerga, para tracking.pixel_id: o Pixel que marca \"Eventos do site\" nos anúncios de qualquer objetivo (e que as conversões otimizam). is_default marca o padrão da conta, usado quando a campanha não envia tracking.pixel_id.\n\nEscopo: `campaigns:read`.",
"responses": {
"200": {
"description": "Pixels da conta",
"content": {
"application/json": {
"example": {
"data": [
{
"id": "123456789012345",
"label": "Pixel da loja · 123456789012345",
"is_default": true
}
]
}
}
}
},
"409": {
"description": "A conta ainda não vinculou uma conta de anúncio da Meta.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Token ausente, inválido, revogado ou vencido.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Limite de requisições.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/ad-account/lead-forms": {
"get": {
"operationId": "api.v1.ad-account.lead-forms",
"tags": [
"Conta e conta de anúncio"
],
"externalDocs": {
"url": "https://leadgo.com.br/docs/api/referencia/conta#ad-account-lead-forms"
},
"summary": "Formulários de cadastro",
"description": "Formulários instantâneos da conta. Use platform_form_id em lead_form_id para uma nova campanha receber os leads no mesmo formulário.\n\nEscopo: `campaigns:read`.",
"responses": {
"200": {
"description": "Formulários de cadastro",
"content": {
"application/json": {
"example": {
"data": [
{
"id": 7,
"platform_form_id": "1122334455667788",
"name": "Tabela de preços",
"status": "ACTIVE",
"questions": [
{
"type": "FULL_NAME"
},
{
"type": "EMAIL"
},
{
"type": "PHONE"
}
],
"privacy_policy_url": "https://imobiliaria.exemplo.com.br/privacidade",
"last_synced_at": "2026-10-28T14:40:00+00:00"
}
]
}
}
}
},
"409": {
"description": "A conta ainda não vinculou uma conta de anúncio da Meta.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Token ausente, inválido, revogado ou vencido.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Limite de requisições.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/ad-account/instagram-accounts": {
"get": {
"operationId": "api.v1.ad-account.instagram-accounts",
"tags": [
"Conta e conta de anúncio"
],
"externalDocs": {
"url": "https://leadgo.com.br/docs/api/referencia/conta#ad-account-instagram-accounts"
},
"summary": "Perfis do Instagram",
"description": "Perfis do Instagram com que a conta de anúncio pode anunciar. Use o id em instagram_account_id para o anúncio sair com outro perfil que não o ligado à Página. page_backed indica um perfil criado a partir da Página. Cache de 10 minutos.\n\nEscopo: `campaigns:read`.",
"responses": {
"200": {
"description": "Perfis do Instagram",
"content": {
"application/json": {
"example": {
"data": [
{
"id": "17841400000000001",
"username": "lojaexemplo",
"picture_url": "https://scontent.cdninstagram.com/perfil.jpg",
"page_backed": false
}
]
}
}
}
},
"409": {
"description": "A conta ainda não vinculou uma conta de anúncio da Meta.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Muitas consultas novas à plataforma (buscas e métricas fora do cache).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"502": {
"description": "A plataforma de anúncios não respondeu. Tente de novo.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Token ausente, inválido, revogado ou vencido.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/ad-account/instagram-posts": {
"get": {
"operationId": "api.v1.ad-account.instagram-posts",
"tags": [
"Conta e conta de anúncio"
],
"externalDocs": {
"url": "https://leadgo.com.br/docs/api/referencia/conta#ad-account-instagram-posts"
},
"summary": "Posts do Instagram",
"description": "Posts do Instagram ligado à conta, dos mais novos para os mais antigos, para escolher o que impulsionar em POST /boosts (use o id em post.id com post.source instagram). Pagine com cursor (meta.next_cursor). Gasta a cota de consultas à plataforma.\n\nEscopo: `campaigns:read`.",
"parameters": [
{
"name": "cursor",
"in": "query",
"required": false,
"description": "meta.next_cursor da página anterior.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Posts do Instagram",
"content": {
"application/json": {
"example": {
"data": [
{
"id": "17900000000000001",
"caption": "Chegou a coleção de verão!",
"media_type": "IMAGE",
"media_url": "https://scontent.cdninstagram.com/post.jpg",
"thumbnail_url": "https://scontent.cdninstagram.com/post.jpg",
"permalink": "https://www.instagram.com/p/AbC123/",
"published_at": "2026-10-20T14:00:00+0000"
}
],
"meta": {
"instagram_user_id": "17841400000000001",
"username": "lojaexemplo",
"next_cursor": "QVFIUz..."
}
}
}
}
},
"409": {
"description": "A conta ainda não vinculou uma conta de anúncio da Meta.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Muitas consultas novas à plataforma (buscas e métricas fora do cache).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"502": {
"description": "A plataforma de anúncios não respondeu. Tente de novo.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Token ausente, inválido, revogado ou vencido.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/ad-account/health": {
"get": {
"operationId": "api.v1.ad-account.health",
"tags": [
"Conta e conta de anúncio"
],
"externalDocs": {
"url": "https://leadgo.com.br/docs/api/referencia/conta#ad-account-health"
},
"summary": "Saúde da conta de anúncio",
"description": "Confere na Meta o que pode impedir ou atrapalhar os anúncios: situação da conta, forma de pagamento, limite de gasto, Página, Instagram, termos de cadastro, Pixel e WhatsApp. status geral: ok, attention ou blocked; cada checagem: ok, warning, error, missing ou unknown, com o link de correção. Bom para conferir antes de criar campanhas. Cache de 10 minutos.\n\nEscopo: `campaigns:read`.",
"responses": {
"200": {
"description": "Saúde da conta de anúncio",
"content": {
"application/json": {
"example": {
"data": {
"status": "attention",
"checked_at": "2026-10-28T15:00:00Z",
"checks": [
{
"id": "payment",
"label": "Forma de pagamento",
"status": "ok",
"status_label": "Tudo certo",
"title": "Payment method",
"message": "",
"fix_label": null,
"fix_url": null
},
{
"id": "pixel",
"label": "Pixel",
"status": "warning",
"status_label": "Atenção",
"title": "Pixel",
"message": "O Pixel não recebe eventos há 7 dias.",
"fix_label": "Abrir o Gerenciador de Eventos",
"fix_url": "https://business.facebook.com/events_manager2"
}
]
}
}
}
}
},
"409": {
"description": "A conta ainda não vinculou uma conta de anúncio da Meta.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Muitas consultas novas à plataforma (buscas e métricas fora do cache).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"502": {
"description": "A plataforma de anúncios não respondeu. Tente de novo.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Token ausente, inválido, revogado ou vencido.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/ad-account/finance": {
"get": {
"operationId": "api.v1.ad-account.finance",
"tags": [
"Conta e conta de anúncio"
],
"externalDocs": {
"url": "https://leadgo.com.br/docs/api/referencia/conta#ad-account-finance"
},
"summary": "Saldo e limite de gasto",
"description": "Total gasto, saldo, limite de gasto (null = sem limite) e a forma de pagamento da conta de anúncio, em centavos na moeda dela. Cache de 10 minutos.\n\nEscopo: `campaigns:read`.",
"responses": {
"200": {
"description": "Saldo e limite de gasto",
"content": {
"application/json": {
"example": {
"data": {
"currency": "BRL",
"balance_cents": 0,
"amount_spent_cents": 1834590,
"spend_cap_cents": 5000000,
"funding_source": "Mastercard *4985"
}
}
}
}
},
"409": {
"description": "A conta ainda não vinculou uma conta de anúncio da Meta.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Muitas consultas novas à plataforma (buscas e métricas fora do cache).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"502": {
"description": "A plataforma de anúncios não respondeu. Tente de novo.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Token ausente, inválido, revogado ou vencido.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/alerts": {
"get": {
"operationId": "api.v1.alerts.index",
"tags": [
"Conta e conta de anúncio"
],
"externalDocs": {
"url": "https://leadgo.com.br/docs/api/referencia/conta#alerts-index"
},
"summary": "Alertas da conta",
"description": "O que pede atenção na conta de anúncio, os mais graves primeiro: anúncio reprovado, problema de entrega, pagamento, verba no limite, gasto sem resultado e conta restrita. Atualizados de hora em hora e pelos avisos da Meta; cada alerta novo também chega pelo webhook alert.created.\n\nEscopo: `campaigns:read`.",
"parameters": [
{
"name": "status",
"in": "query",
"required": false,
"description": "open (padrão) ou all (inclui resolvidos e dispensados, os 100 mais recentes).",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Alertas da conta",
"content": {
"application/json": {
"example": {
"data": [
{
"id": 31,
"kind": "spend_no_results",
"kind_label": "Gasto sem resultado",
"severity": "warning",
"title": "Gastando sem resultado",
"message": "A campanha gastou em 3 dos últimos 7 dias sem nenhuma conversão.",
"entity": {
"level": "campaign",
"platform_id": "120212345678900001",
"name": "Promoção de outubro"
},
"fix": {
"label": "Abrir no Gerenciador",
"url": "https://adsmanager.facebook.com/adsmanager/manage/campaigns"
},
"status": "open",
"detected_at": "2026-10-28T09:00:00+00:00",
"dismissed_at": null,
"resolved_at": null
}
]
}
}
}
},
"422": {
"description": "Campos inválidos; o detalhe de cada um vem em errors.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "A conta ainda não vinculou uma conta de anúncio da Meta.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Token ausente, inválido, revogado ou vencido.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Limite de requisições.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/alerts/{id}/dismiss": {
"post": {
"operationId": "api.v1.alerts.dismiss",
"tags": [
"Conta e conta de anúncio"
],
"externalDocs": {
"url": "https://leadgo.com.br/docs/api/referencia/conta#alerts-dismiss"
},
"summary": "Dispensar alerta",
"description": "Esconde o alerta (status dismissed). Se o problema continuar, ele volta depois de 30 dias.\n\nEscopo: `account:manage`.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Dispensar alerta",
"content": {
"application/json": {
"example": {
"data": {
"id": 31,
"kind": "spend_no_results",
"kind_label": "Gasto sem resultado",
"severity": "warning",
"title": "Gastando sem resultado",
"message": "A campanha gastou em 3 dos últimos 7 dias sem nenhuma conversão.",
"entity": {
"level": "campaign",
"platform_id": "120212345678900001",
"name": "Promoção de outubro"
},
"fix": {
"label": "Abrir no Gerenciador",
"url": "https://adsmanager.facebook.com/adsmanager/manage/campaigns"
},
"status": "dismissed",
"detected_at": "2026-10-28T09:00:00+00:00",
"dismissed_at": "2026-10-28T16:00:00+00:00",
"resolved_at": null
}
}
}
}
},
"404": {
"description": "O recurso não existe nesta conta.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"502": {
"description": "A plataforma de anúncios não respondeu. Tente de novo.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Token ausente, inválido, revogado ou vencido.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Limite de requisições.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/ad-account/sync": {
"post": {
"operationId": "api.v1.ad-account.sync",
"tags": [
"Conta e conta de anúncio"
],
"externalDocs": {
"url": "https://leadgo.com.br/docs/api/referencia/conta#ad-account-sync"
},
"summary": "Sincronizar com a Meta",
"description": "Pede uma sincronização das campanhas (status, conjuntos, anúncios). As rotinas já sincronizam de hora em hora; use depois de mudar algo direto no Gerenciador de Anúncios. No máximo uma a cada 5 minutos.\n\nEscopo: `campaigns:read`.",
"responses": {
"202": {
"description": "Sincronizar com a Meta",
"content": {
"application/json": {
"example": {
"data": {
"queued": true
}
}
}
}
},
"409": {
"description": "A conta ainda não vinculou uma conta de anúncio da Meta.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Uma sincronização foi pedida há pouco (campanhas: 5 minutos; públicos: 1 minuto). Espere o Retry-After.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Token ausente, inválido, revogado ou vencido.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/reference": {
"get": {
"operationId": "api.v1.reference",
"tags": [
"Listas e segmentação"
],
"externalDocs": {
"url": "https://leadgo.com.br/docs/api/referencia/consultas#reference"
},
"summary": "Valores aceitos",
"description": "Objetivos (e o que cada um exige: link, Pixel, vídeo, WhatsApp), botões, países, eventos de conversão, categorias especiais, campos de formulário, tipos de mídia, limites, escopos e eventos de webhook. Os mesmos do painel. Em limits, max_url_tags conta os parâmetros de URL extras, na campanha e no anúncio: os 4 UTMs padrão (utm_source, utm_medium, utm_campaign e utm_content) ficam fora da conta.\n\nEscopo: `campaigns:read`.",
"responses": {
"200": {
"description": "Valores aceitos",
"content": {
"application/json": {
"example": {
"data": {
"goals": [
{
"value": "traffic",
"label": "Tráfego",
"description": "Leva pessoas para o seu site, loja ou WhatsApp.",
"needs_link": true,
"requires_pixel": false,
"requires_video": false,
"uses_messaging": false
}
],
"call_to_actions": [
{
"value": "LEARN_MORE",
"label": "Saiba mais"
}
],
"countries": [
{
"value": "BR",
"label": "Brasil"
}
],
"conversion_events": [
{
"value": "PURCHASE",
"label": "Compra"
}
],
"limits": {
"max_creatives": 10,
"max_cities": 25,
"max_interests": 25,
"max_interest_groups": 3,
"max_url_tags": 10
}
}
}
}
}
},
"401": {
"description": "Token ausente, inválido, revogado ou vencido.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Limite de requisições.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/targeting/cities": {
"get": {
"operationId": "api.v1.targeting.cities",
"tags": [
"Listas e segmentação"
],
"externalDocs": {
"url": "https://leadgo.com.br/docs/api/referencia/consultas#targeting-cities"
},
"summary": "Buscar cidades",
"description": "Cidades da segmentação da Meta. Use key e name em targeting.cities. Resultados ficam em cache por um dia; buscas novas gastam a cota de consultas à plataforma.\n\nEscopo: `campaigns:read`.",
"parameters": [
{
"name": "q",
"in": "query",
"required": true,
"description": "Nome da cidade (mínimo 2 letras).",
"schema": {
"type": "string"
}
},
{
"name": "country",
"in": "query",
"required": false,
"description": "Restringe a um país (BR, AR...).",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Buscar cidades",
"content": {
"application/json": {
"example": {
"data": [
{
"key": "2490299",
"name": "Campinas, São Paulo",
"type": "Cidade",
"detail": "São Paulo, Brasil",
"country_code": "BR"
}
]
}
}
}
},
"422": {
"description": "Campos inválidos; o detalhe de cada um vem em errors.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Muitas consultas novas à plataforma (buscas e métricas fora do cache).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "A conta ainda não vinculou uma conta de anúncio da Meta.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Token ausente, inválido, revogado ou vencido.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/targeting/interests": {
"get": {
"operationId": "api.v1.targeting.interests",
"tags": [
"Listas e segmentação"
],
"externalDocs": {
"url": "https://leadgo.com.br/docs/api/referencia/consultas#targeting-interests"
},
"summary": "Buscar interesses",
"description": "Interesses da segmentação da Meta. Use id e name em targeting.interests (ou num grupo de targeting.narrow_interests).\n\nEscopo: `campaigns:read`.",
"parameters": [
{
"name": "q",
"in": "query",
"required": true,
"description": "Termo (mínimo 2 letras).",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Buscar interesses",
"content": {
"application/json": {
"example": {
"data": [
{
"id": "6003397425735",
"name": "Corrida",
"audience_size": 48000000
}
]
}
}
}
},
"422": {
"description": "Campos inválidos; o detalhe de cada um vem em errors.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Muitas consultas novas à plataforma (buscas e métricas fora do cache).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "A conta ainda não vinculou uma conta de anúncio da Meta.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Token ausente, inválido, revogado ou vencido.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/targeting/reach-estimate": {
"post": {
"operationId": "api.v1.targeting.reach-estimate",
"tags": [
"Listas e segmentação"
],
"externalDocs": {
"url": "https://leadgo.com.br/docs/api/referencia/consultas#targeting-reach-estimate"
},
"summary": "Estimar alcance",
"description": "Quantas pessoas cabem num público, segundo a Meta, antes de criar a campanha. Recebe o mesmo persona_id e o mesmo objeto targeting de POST /campaigns (com exclusões, idiomas e grupos de interesses). Quando a Meta ainda está calculando, ready vem false: tente de novo em instantes. Com targeting.narrow_interests, cada grupo é estimado à parte (uma consulta à plataforma por grupo): narrowed vem true, upper é o teto do menor grupo e lower vem null (o cruzamento a Meta só calcula depois de publicar). warning traz um aviso quando o público pode ser pequeno demais para a Meta entregar (senão, null). Cache de 1 hora para a mesma segmentação.\n\nEscopo: `campaigns:read`.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"persona_id": {
"type": "integer",
"description": "Persona da conta como base do público."
},
"targeting": {
"type": "object",
"description": "O mesmo objeto targeting de POST /campaigns."
}
}
},
"example": {
"targeting": {
"cities": [
{
"key": "269969",
"name": "São Paulo, São Paulo",
"country_code": "BR",
"radius_km": 25
}
],
"age_min": 25,
"age_max": 45,
"gender": "female",
"interests": [
{
"id": "6003107902433",
"name": "Compras online"
}
]
}
}
}
}
},
"responses": {
"200": {
"description": "Estimar alcance",
"content": {
"application/json": {
"example": {
"data": {
"available": true,
"lower": 1200000,
"upper": 1450000,
"ready": true,
"narrowed": false,
"warning": null
}
}
}
}
},
"422": {
"description": "Campos inválidos; o detalhe de cada um vem em errors.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "A conta ainda não vinculou uma conta de anúncio da Meta.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Muitas consultas novas à plataforma (buscas e métricas fora do cache).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"502": {
"description": "A plataforma de anúncios não respondeu. Tente de novo.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Token ausente, inválido, revogado ou vencido.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/media": {
"post": {
"operationId": "api.v1.media.store",
"tags": [
"Mídias"
],
"externalDocs": {
"url": "https://leadgo.com.br/docs/api/referencia/midias#media-store"
},
"summary": "Enviar mídia",
"description": "Envie o arquivo (multipart, campo file) e ele fica pronto na hora (201); ou informe a URL (JSON, campo url) e o download segue em segundo plano (202, status pending → ready ou failed, com o aviso media.ready). Imagens JPG/PNG até 30 MB; vídeos MP4/MOV até 200 MB; o tipo é conferido pelo conteúdo. A URL precisa ser https, pública e direta (links de compartilhamento do Drive e do Dropbox redirecionam e falham). Mídias sem uso somem depois de 7 dias; usadas, 30 dias depois do último uso.\n\nEscopo: `media:write`.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "URL https direta do arquivo (application/json). Obrigatório sem file."
},
"filename": {
"type": "string",
"description": "Nome de exibição."
}
}
},
"example": {
"url": "https://cdn.loja.exemplo.com.br/banners/outubro.jpg"
}
},
"multipart/form-data": {
"schema": {
"type": "object",
"properties": {
"file": {
"type": "string",
"format": "binary",
"description": "O arquivo (multipart/form-data). Obrigatório sem url."
},
"filename": {
"type": "string",
"description": "Nome de exibição."
}
}
}
}
}
},
"responses": {
"201": {
"description": "Enviar mídia",
"content": {
"application/json": {
"example": {
"data": {
"id": "01jbx3m7k2q8f5v9w4n6c0r1ht",
"status": "ready",
"kind": "image",
"filename": "outubro.jpg",
"mime_type": "image/jpeg",
"size": 482113,
"source_url": null,
"error": null,
"ready_at": "2026-10-28T15:00:02+00:00",
"last_used_at": null,
"expires_at": "2026-11-04T15:00:02+00:00",
"created_at": "2026-10-28T15:00:02+00:00"
}
}
}
}
},
"422": {
"description": "Campos inválidos; o detalhe de cada um vem em errors.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Já há 5 mídias baixando por URL nesta conta.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Token ausente, inválido, revogado ou vencido.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
},
"get": {
"operationId": "api.v1.media.index",
"tags": [
"Mídias"
],
"externalDocs": {
"url": "https://leadgo.com.br/docs/api/referencia/midias#media-index"
},
"summary": "Listar mídias",
"description": "Mídias da conta, das mais novas para as mais antigas (paginado por cursor, 50 por página).\n\nEscopo: `media:write`.",
"parameters": [
{
"name": "cursor",
"in": "query",
"required": false,
"description": "Valor de meta.next_cursor da página anterior.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Listar mídias",
"content": {
"application/json": {
"example": {
"data": [
{
"id": "01jbx3m7k2q8f5v9w4n6c0r1ht",
"status": "ready",
"kind": "image",
"filename": "outubro.jpg",
"mime_type": "image/jpeg",
"size": 482113,
"source_url": null,
"error": null,
"ready_at": "2026-10-28T15:00:02+00:00",
"last_used_at": null,
"expires_at": "2026-11-04T15:00:02+00:00",
"created_at": "2026-10-28T15:00:02+00:00"
}
],
"links": {
"first": null,
"last": null,
"prev": null,
"next": null
},
"meta": {
"path": "/api/v1/media",
"per_page": 50,
"next_cursor": null,
"prev_cursor": null
}
}
}
}
},
"401": {
"description": "Token ausente, inválido, revogado ou vencido.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Limite de requisições.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/media/{id}": {
"get": {
"operationId": "api.v1.media.show",
"tags": [
"Mídias"
],
"externalDocs": {
"url": "https://leadgo.com.br/docs/api/referencia/midias#media-show"
},
"summary": "Consultar mídia",
"description": "Situação de uma mídia: use para acompanhar o download por URL (status pending → ready ou failed, com o motivo em error).\n\nEscopo: `media:write`.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Consultar mídia",
"content": {
"application/json": {
"example": {
"data": {
"id": "01jbx3m7k2q8f5v9w4n6c0r1ht",
"status": "ready",
"kind": "image",
"filename": "outubro.jpg",
"mime_type": "image/jpeg",
"size": 482113,
"source_url": null,
"error": null,
"ready_at": "2026-10-28T15:00:02+00:00",
"last_used_at": null,
"expires_at": "2026-11-04T15:00:02+00:00",
"created_at": "2026-10-28T15:00:02+00:00"
}
}
}
}
},
"404": {
"description": "O recurso não existe nesta conta.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Token ausente, inválido, revogado ou vencido.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Limite de requisições.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
},
"delete": {
"operationId": "api.v1.media.destroy",
"tags": [
"Mídias"
],
"externalDocs": {
"url": "https://leadgo.com.br/docs/api/referencia/midias#media-destroy"
},
"summary": "Excluir mídia",
"description": "Apaga a mídia da biblioteca. Campanhas já criadas com ela não são afetadas (cada uma tem a sua cópia).\n\nEscopo: `media:write`.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"204": {
"description": "Excluir mídia"
},
"404": {
"description": "O recurso não existe nesta conta.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Token ausente, inválido, revogado ou vencido.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Limite de requisições.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/campaigns": {
"get": {
"operationId": "api.v1.campaigns.index",
"tags": [
"Campanhas"
],
"externalDocs": {
"url": "https://leadgo.com.br/docs/api/referencia/campanhas#campaigns-index"
},
"summary": "Listar campanhas",
"description": "Campanhas da conta (criadas pela API, pelo painel e as importadas da Meta), das mais novas para as mais antigas, paginadas por cursor.\n\nEscopo: `campaigns:read`.",
"parameters": [
{
"name": "status",
"in": "query",
"required": false,
"description": "creating, failed, pending_review, active, paused, rejected, error, completed ou cancelled.",
"schema": {
"type": "string"
}
},
{
"name": "goal",
"in": "query",
"required": false,
"description": "Objetivo (veja GET /reference).",
"schema": {
"type": "string"
}
},
{
"name": "search",
"in": "query",
"required": false,
"description": "Parte do nome da campanha.",
"schema": {
"type": "string"
}
},
{
"name": "limit",
"in": "query",
"required": false,
"description": "Itens por página, de 1 a 100 (padrão 25).",
"schema": {
"type": "integer"
}
},
{
"name": "cursor",
"in": "query",
"required": false,
"description": "Valor de meta.next_cursor (ou siga links.next).",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Listar campanhas",
"content": {
"application/json": {
"example": {
"data": [
{
"id": "01jby0q4c8m2d6t9v3k7w5r1xa",
"name": "Promoção de outubro",
"goal": "traffic",
"goal_label": "Tráfego",
"status": "active",
"status_label": "Ativa",
"created_via": "api",
"budget": {
"level": "campaign",
"type": "daily",
"amount_cents": 5000,
"currency": "BRL"
},
"schedule": {
"starts_at": "2026-10-28T03:00:00+00:00",
"ends_at": null
},
"error": null,
"platform": "meta",
"platform_campaign_id": "120212345678900001",
"published_at": "2026-10-28T15:02:11+00:00",
"synced_at": "2026-10-28T15:40:00+00:00",
"created_at": "2026-10-28T15:00:00+00:00",
"updated_at": "2026-10-28T15:02:11+00:00",
"links": {
"panel": "https://app.leadgo.com.br/app/campaigns/01jby0q4c8m2d6t9v3k7w5r1xa"
}
}
],
"links": {
"first": null,
"last": null,
"prev": null,
"next": "https://app.leadgo.com.br/api/v1/campaigns?cursor=eyJjcmVhdGVkX2F0Ijo..."
},
"meta": {
"path": "https://app.leadgo.com.br/api/v1/campaigns",
"per_page": 25,
"next_cursor": "eyJjcmVhdGVkX2F0Ijo...",
"prev_cursor": null
}
}
}
}
},
"422": {
"description": "Campos inválidos; o detalhe de cada um vem em errors.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Token ausente, inválido, revogado ou vencido.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Limite de requisições.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
},
"post": {
"operationId": "api.v1.campaigns.store",
"tags": [
"Campanhas"
],
"externalDocs": {
"url": "https://leadgo.com.br/docs/api/referencia/campanhas#campaigns-store"
},
"summary": "Criar campanha",
"description": "Cria a campanha pelas mesmas rotinas do painel: ela é gravada com status creating e a publicação na Meta segue pela fila (a resposta é 202, com Location). O fim chega pelo webhook campaign.published ou campaign.failed, ou consultando GET /campaigns/{id}. Com ?validate_only=true nada é criado: a resposta traz o rascunho como seria publicado, com os padrões aplicados (Pixel, datas, público). Os campos que faltarem seguem os padrões do assistente do painel. Cada item de creatives é um anúncio do mesmo conjunto: arte ou vídeo (media_id) ou carrossel (cards, um por campanha), até 10; do segundo item em diante, o título, o texto, a descrição e o botão que faltarem vêm do primeiro. Na resposta, um carrossel sozinho volta no formato antigo (format carousel, carousel.cards); junto de arte ou vídeo, volta no próprio item (media_type carousel, cards). Todo anúncio novo, de qualquer objetivo, sai com \"Eventos do site\" marcado (o Pixel é obrigatório: veja tracking.pixel_id; sem Pixel para escolher, 422 nesse campo) e sempre com os 4 UTMs padrão; tracking.url_tags acrescenta extras ou troca o valor de um dos 4.\n\nEscopo: `campaigns:write`.",
"parameters": [
{
"name": "validate_only",
"in": "query",
"required": false,
"description": "Só confere o corpo (200, nada é criado).",
"schema": {
"type": "boolean"
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": false,
"description": "Valor único por operação: repetir devolve a primeira resposta.",
"schema": {
"type": "string",
"maxLength": 255
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Nome da campanha (até 120 caracteres)."
},
"goal": {
"type": "string",
"description": "traffic, awareness, engagement, video_views, conversions, lead_generation ou whatsapp_messages."
},
"status": {
"type": "string",
"description": "paused (padrão) ou active: como a campanha nasce depois de aprovada."
},
"budget": {
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "daily (padrão) ou lifetime (total, exige schedule.end_date)."
},
"amount_cents": {
"type": "integer",
"description": "Valor em centavos (5000 = R$ 50,00). A diária respeita a mínima da conta."
}
}
},
"schedule": {
"type": "object",
"properties": {
"start_date": {
"type": "string",
"description": "AAAA-MM-DD no fuso da conta (padrão: hoje)."
},
"end_date": {
"type": "string",
"description": "AAAA-MM-DD, depois do início. Obrigatória no orçamento total."
}
}
},
"tracking": {
"type": "object",
"properties": {
"pixel_id": {
"type": "string",
"description": "Pixel que marca \"Eventos do site\" nos anúncios, em qualquer objetivo (nas conversões, é também o Pixel que elas otimizam). Obrigatório: todo anúncio novo sai com ele. Sem pixel_id, vale o padrão da conta (default_pixel_id em GET /ad-account) e, sem padrão, o único que ela enxerga (GET /ad-account/pixels), que passa a ser o padrão. Com vários Pixels e nenhum padrão, sem nenhum Pixel ou com a consulta fora do ar, a campanha é recusada com 422 neste campo. Nas respostas, mostra o Pixel escolhido."
},
"conversion_event": {
"type": "string",
"description": "PURCHASE (padrão), LEAD, COMPLETE_REGISTRATION, ADD_TO_CART ou INITIATED_CHECKOUT."
},
"url_tags": {
"type": "array",
"items": {
"type": "object"
},
"description": "UTMs extras {key, value}, somadas ao link de todos os anúncios. Os 4 padrão vão sempre (utm_source=facebook, utm_medium=paid, utm_campaign={{campaign.name}}, utm_content={{ad.name}}): ausente ou [], a campanha sai só com eles. Um extra com a chave de um dos 4 troca o valor dele (ex.: utm_campaign=blackfriday); os demais vêm depois, na ordem enviada. Até 10 extras: as chaves dos 4 não contam, então reenviar a lista de uma resposta passa. Aceita as macros da Meta, como {{campaign.name}} e {{ad.name}}. Vale em todo objetivo, inclusive cadastro e WhatsApp. Nas respostas, mostra a lista efetiva: os 4 (com o valor trocado, quando houver) e os extras."
}
}
},
"special_ad_category": {
"type": "string",
"description": "HOUSING, EMPLOYMENT, CREDIT, FINANCIAL_PRODUCTS_SERVICES ou ISSUES_ELECTIONS_POLITICS (anúncios desses temas têm segmentação restrita pela Meta)."
},
"persona_id": {
"type": "integer",
"description": "Persona da conta: a base do público (targeting sobrescreve campo a campo)."
},
"targeting": {
"type": "object",
"properties": {
"countries": {
"type": "array",
"items": {
"type": "string"
},
"description": "Países (padrão BR). Com cidades, o país sai delas."
},
"cities": {
"type": "array",
"items": {
"type": "object",
"properties": {
"radius_km": {
"type": "integer",
"description": "Raio em volta da cidade: 17, 25, 40, 50, 80 km (sem raio, só a cidade)."
}
}
},
"description": "Cidades {key, name, country_code} de GET /targeting/cities (até 25)."
},
"age_min": {
"type": "integer",
"description": "13 a 65 (padrão 18)."
},
"age_max": {
"type": "integer",
"description": "13 a 65, maior ou igual à mínima (padrão 65)."
},
"gender": {
"type": "string",
"description": "all (padrão), male ou female."
},
"interests": {
"type": "array",
"items": {
"type": "object"
},
"description": "Interesses {id, name} de GET /targeting/interests (até 25): basta ter um deles (OU)."
},
"narrow_interests": {
"type": "array",
"items": {
"type": "array",
"items": {
"type": "object"
}
},
"description": "Grupos que o público também precisa ter: um interesse de cada grupo (E), além de um da lista principal (OU). Até 3 grupos de até 25 interesses {id, name}. Não combina com Advantage+ público. Com persona, [] tira os grupos dela."
},
"audience_id": {
"type": "string",
"description": "Público da conta a incluir (platform_audience_id de GET /audiences)."
},
"excluded_audience_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Públicos a excluir (até 10), como quem já comprou."
},
"excluded_cities": {
"type": "array",
"items": {
"type": "object"
},
"description": "Cidades a excluir {key, name} de GET /targeting/cities (até 25)."
},
"languages": {
"type": "array",
"items": {
"type": "string"
},
"description": "pt, es, en (sem idioma, todos)."
},
"advantage_audience": {
"type": "boolean",
"description": "Deixa a Meta ampliar o público além do definido (Advantage+ público). Padrão false. Não vale com targeting.narrow_interests."
}
}
},
"placements": {
"type": "array",
"items": {
"type": "string"
},
"description": "Posicionamentos manuais (veja GET /reference). Vazio ou ausente: automáticos, o recomendado."
},
"instagram_account_id": {
"type": "string",
"description": "Perfil do Instagram do anúncio (GET /ad-account/instagram-accounts). Sem ele, o ligado à Página. Não vale no WhatsApp."
},
"bidding": {
"type": "object",
"properties": {
"strategy": {
"type": "string",
"description": "COST_CAP (custo por resultado), LOWEST_COST_WITH_BID_CAP (lance máximo) ou LOWEST_COST_WITH_MIN_ROAS (ROAS mínimo, só vendas com Compra). Sem ela, lance automático."
},
"amount_cents": {
"type": "integer",
"description": "Valor em centavos, obrigatório em COST_CAP e LOWEST_COST_WITH_BID_CAP."
},
"roas_floor": {
"type": "number",
"description": "Retorno mínimo (2.5 = 2,5x), obrigatório em LOWEST_COST_WITH_MIN_ROAS."
}
}
},
"format": {
"type": "string",
"description": "single (padrão) ou carousel, o formato antigo do carrossel sozinho (segue aceito): um criativo só (texto principal, título e botão) e as imagens em carousel.cards. Para juntar o carrossel com arte ou vídeo, use creatives[].cards."
},
"carousel": {
"type": "object",
"properties": {
"cards": {
"type": "array",
"items": {
"type": "object",
"properties": {
"media_id": {
"type": "string",
"description": "Formato antigo: imagem pronta da biblioteca de cada cartão (2 a 10 cartões)."
},
"headline": {
"type": "string",
"description": "Título do cartão (obrigatório em cada cartão)."
},
"description": {
"type": "string",
"description": "Descrição do cartão."
},
"link_url": {
"type": "string",
"description": "Link do cartão (padrão: link_url)."
},
"call_to_action": {
"type": "string",
"description": "Botão do cartão (padrão: o do criativo)."
}
}
}
},
"optimize_order": {
"type": "boolean",
"description": "true (padrão): a Meta reordena os cartões pelo desempenho. false: ordem fixa, até 5 cartões."
}
}
},
"text_variations": {
"type": "object",
"properties": {
"headlines": {
"type": "array",
"items": {
"type": "string"
},
"description": "Até 4 títulos alternativos que a Meta alterna (só num anúncio simples: um criativo, sem carrossel, objetivos com link)."
},
"bodies": {
"type": "array",
"items": {
"type": "string"
},
"description": "Até 4 textos principais alternativos."
}
}
},
"link_url": {
"type": "string",
"description": "URL https de destino. Obrigatória nos objetivos com link (veja needs_link em GET /reference)."
},
"creatives": {
"type": "array",
"items": {
"type": "object",
"properties": {
"media_id": {
"type": "string",
"description": "Arte ou vídeo pronto da biblioteca (POST /media): o tipo do anúncio sai da mídia. Cada item de creatives é um anúncio do mesmo conjunto, até 10. Cada item leva media_id ou cards, nunca os dois."
},
"headline": {
"type": "string",
"description": "Título (até 255). Obrigatório no primeiro item; nos demais, sem ele, vale o do primeiro."
},
"body": {
"type": "string",
"description": "Texto principal (até 2000). Obrigatório no primeiro item; nos demais, sem ele, vale o do primeiro."
},
"description": {
"type": "string",
"description": "Descrição (até 255). Do segundo item em diante, sem ela, vale a do primeiro; envie null para o anúncio sair sem descrição."
},
"call_to_action": {
"type": "string",
"description": "Botão (padrão LEARN_MORE; veja GET /reference). Do segundo item em diante, sem ele, vale o do primeiro; null volta ao LEARN_MORE. No WhatsApp, ignorado."
},
"cards": {
"type": "array",
"items": {
"type": "object",
"properties": {
"media_id": {
"type": "string",
"description": "Imagem (JPG ou PNG) da biblioteca para o cartão (obrigatória em cada cartão)."
},
"headline": {
"type": "string",
"description": "Título do cartão (obrigatório em cada cartão)."
},
"description": {
"type": "string",
"description": "Descrição do cartão."
},
"link_url": {
"type": "string",
"description": "Link do cartão (padrão: link_url). No WhatsApp, não envie: o toque no cartão abre a conversa."
},
"call_to_action": {
"type": "string",
"description": "Botão do cartão (padrão: o do anúncio). No WhatsApp, não envie: o botão é sempre o de conversa."
}
}
},
"description": "Carrossel: de 2 a 10 cartões, só imagens. Um carrossel por campanha, ao lado de artes e vídeos. Vale em todos os objetivos, menos video_views."
},
"optimize_order": {
"type": "boolean",
"description": "No item com cards: true (padrão), a Meta reordena os cartões pelo desempenho; false, ordem fixa, até 5 cartões."
}
}
}
},
"whatsapp": {
"type": "object",
"properties": {
"greeting": {
"type": "string",
"description": "Boas-vindas da empresa na conversa (objetivo whatsapp_messages)."
},
"prefill": {
"type": "string",
"description": "Mensagem que já vem digitada para o cliente enviar."
},
"phone_number": {
"type": "string",
"description": "Número em E.164 (+5511999998888); sem ele, o da Página."
}
}
},
"lead_form_id": {
"type": "string",
"description": "Formulário existente (platform_form_id de GET /ad-account/lead-forms), no objetivo lead_generation."
},
"lead_form": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Nome do formulário novo (padrão: o da campanha)."
},
"fields": {
"type": "array",
"items": {
"type": "string"
},
"description": "Campos padrão: FULL_NAME, EMAIL, PHONE, CITY, STATE, ZIP, COMPANY_NAME, JOB_TITLE (nome e telefone sempre entram)."
},
"questions": {
"type": "array",
"items": {
"type": "object"
},
"description": "Até 3 perguntas {question, options[]} (sem options, resposta livre)."
},
"privacy_policy_url": {
"type": "string",
"description": "Política de privacidade (padrão: a de Leads › Configurações; a Meta exige)."
},
"thank_you": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Título da tela final (obrigatório com lead_form)."
},
"body": {
"type": "string",
"description": "Texto da tela final (obrigatório com lead_form)."
}
}
}
}
}
},
"required": [
"name",
"goal",
"budget",
"creatives"
]
},
"example": {
"name": "Promoção de outubro",
"goal": "traffic",
"status": "paused",
"budget": {
"type": "daily",
"amount_cents": 5000
},
"targeting": {
"countries": [
"BR"
],
"age_min": 25,
"age_max": 55,
"gender": "all"
},
"link_url": "https://loja.exemplo.com.br/outubro",
"creatives": [
{
"media_id": "01jbx3m7k2q8f5v9w4n6c0r1ht",
"headline": "Outono com 30% off",
"body": "Peças selecionadas com frete grátis até domingo.",
"call_to_action": "SHOP_NOW"
}
]
}
}
}
},
"responses": {
"202": {
"description": "Criar campanha",
"content": {
"application/json": {
"example": {
"data": {
"id": "01jby0q4c8m2d6t9v3k7w5r1xa",
"name": "Promoção de outubro",
"goal": "traffic",
"goal_label": "Tráfego",
"status": "creating",
"status_label": "Publicando",
"created_via": "api",
"budget": {
"level": "campaign",
"type": "daily",
"amount_cents": 5000,
"currency": "BRL"
},
"schedule": {
"starts_at": "2026-10-28T03:00:00+00:00",
"ends_at": null
},
"error": null,
"platform": "meta",
"platform_campaign_id": null,
"published_at": null,
"synced_at": null,
"created_at": "2026-10-28T15:00:00+00:00",
"updated_at": "2026-10-28T15:02:11+00:00",
"draft": {
"name": "Promoção de outubro",
"goal": "traffic",
"status": "paused",
"budget": {
"type": "daily",
"amount_cents": 5000
},
"schedule": {
"start_date": "2026-10-28",
"end_date": null
},
"tracking": {
"pixel_id": "123456789012345",
"conversion_event": 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}}"
}
]
},
"special_ad_category": null,
"targeting": {
"countries": [
"BR"
],
"cities": [],
"age_min": 25,
"age_max": 55,
"gender": "all",
"interests": [],
"narrow_interests": [],
"audience_id": null
},
"link_url": "https://loja.exemplo.com.br/outubro",
"creatives": [
{
"media_type": "image",
"headline": "Outono com 30% off",
"body": "Peças selecionadas com frete grátis até domingo.",
"call_to_action": "SHOP_NOW"
}
],
"whatsapp": null,
"lead_form": null
},
"ad_sets": [],
"brain": {
"mode": null,
"effective_mode": "manual",
"target_cpa_cents": null,
"target_roas": null,
"effective_target_cpa_cents": 3000,
"effective_target_roas": null,
"locked_until": null,
"last_touched_at": null,
"last_touched_by": null
},
"links": {
"panel": "https://app.leadgo.com.br/app/campaigns/01jby0q4c8m2d6t9v3k7w5r1xa"
}
}
}
}
}
},
"422": {
"description": "Campos inválidos; o detalhe de cada um vem em errors.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "A conta ainda não vinculou uma conta de anúncio da Meta.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Já há 5 campanhas sendo publicadas nesta conta.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Token ausente, inválido, revogado ou vencido.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/campaigns/preview": {
"post": {
"operationId": "api.v1.campaigns.preview",
"tags": [
"Campanhas"
],
"externalDocs": {
"url": "https://leadgo.com.br/docs/api/referencia/campanhas#campaigns-preview"
},
"summary": "Prévia antes de criar",
"description": "Recebe o mesmo corpo de POST /campaigns e devolve a prévia da Meta de cada posicionamento, sem criar nada. Com vários anúncios, escolha qual em ?creative= (o primeiro é 0): o carrossel é o anúncio da posição dele em creatives e aparece com todos os cartões; no carrossel sozinho, é sempre 0. url é o endereço da prévia para um "
}
]
}
}
}
}
},
"422": {
"description": "Campos inválidos; o detalhe de cada um vem em errors.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "A conta ainda não vinculou uma conta de anúncio da Meta.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Muitas consultas novas à plataforma (buscas e métricas fora do cache).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Token ausente, inválido, revogado ou vencido.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/boosts": {
"post": {
"operationId": "api.v1.boosts.store",
"tags": [
"Campanhas"
],
"externalDocs": {
"url": "https://leadgo.com.br/docs/api/referencia/campanhas#boosts-store"
},
"summary": "Impulsionar post",
"description": "Transforma um post que já está no Facebook ou no Instagram em anúncio, mantendo as curtidas e os comentários. Cria campanha, conjunto e anúncio pela mesma fila da criação (202, status creating; o fim chega por campaign.published ou campaign.failed). Posts do Instagram vêm de GET /ad-account/instagram-posts; no Facebook, use {idDaPágina}_{idDoPost}. Objetivos: engagement, traffic, awareness, video_views (tráfego leva link_url e call_to_action). O criativo de um post impulsionado não muda depois (boost_creative_locked). O anúncio sai com \"Eventos do site\" marcado, com o Pixel escolhido como em POST /campaigns (tracking.pixel_id, o padrão da conta ou o único que ela enxerga; sem Pixel para escolher, 422 em tracking.pixel_id, também no validate_only), e com os 4 UTMs padrão, em todo objetivo (o impulsionamento não aceita extras). Com ?validate_only=true só confere o corpo.\n\nEscopo: `campaigns:write`.",
"parameters": [
{
"name": "validate_only",
"in": "query",
"required": false,
"description": "Só confere (200, nada é criado).",
"schema": {
"type": "boolean"
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": false,
"description": "Valor único por operação: repetir devolve a primeira resposta.",
"schema": {
"type": "string",
"maxLength": 255
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Nome da campanha."
},
"goal": {
"type": "string",
"description": "engagement, traffic, awareness, video_views."
},
"post": {
"type": "object",
"properties": {
"source": {
"type": "string",
"description": "instagram ou facebook."
},
"id": {
"type": "string",
"description": "Id da mídia do Instagram ou do post do Facebook ({idDaPágina}_{idDoPost})."
},
"caption": {
"type": "string",
"description": "Legenda, para mostrar no painel."
},
"thumbnail_url": {
"type": "string",
"description": "Imagem do post, para mostrar no painel."
},
"permalink": {
"type": "string",
"description": "Link público do post."
}
}
},
"status": {
"type": "string",
"description": "paused (padrão) ou active."
},
"budget": {
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "daily (padrão) ou lifetime (exige schedule.end_date)."
},
"amount_cents": {
"type": "integer",
"description": "Valor em centavos (respeita a mínima da conta)."
}
}
},
"schedule": {
"type": "object",
"properties": {
"start_date": {
"type": "string",
"description": "AAAA-MM-DD no fuso da conta (padrão: hoje)."
},
"end_date": {
"type": "string",
"description": "AAAA-MM-DD."
}
}
},
"persona_id": {
"type": "integer",
"description": "Persona como base do público."
},
"targeting": {
"type": "object",
"description": "Países, cidades (com radius_km), idade, gênero, interesses, grupos de interesses (narrow_interests) e audience_id, como em POST /campaigns."
},
"link_url": {
"type": "string",
"description": "Destino do botão (obrigatório em traffic)."
},
"call_to_action": {
"type": "string",
"description": "Botão em traffic (padrão LEARN_MORE)."
},
"instagram_account_id": {
"type": "string",
"description": "Perfil do Instagram com que o anúncio roda."
},
"tracking": {
"type": "object",
"properties": {
"pixel_id": {
"type": "string",
"description": "Pixel que marca \"Eventos do site\" no anúncio (GET /ad-account/pixels). Sem ele, o padrão da conta ou o único que ela enxerga, como em POST /campaigns. Na resposta, boost.tracking.pixel_id mostra o Pixel escolhido."
}
}
}
},
"required": [
"name",
"goal",
"post",
"budget"
]
},
"example": {
"name": "Impulsionar | Coleção de verão",
"goal": "engagement",
"budget": {
"amount_cents": 2000
},
"post": {
"source": "instagram",
"id": "17900000000000001"
},
"targeting": {
"cities": [
{
"key": "269969",
"name": "São Paulo, São Paulo",
"country_code": "BR",
"radius_km": 25
}
],
"age_min": 20,
"age_max": 45
}
}
}
}
},
"responses": {
"202": {
"description": "Impulsionar post",
"content": {
"application/json": {
"example": {
"data": {
"id": "01jby0q4c8m2d6t9v3k7w5r1xa",
"name": "Impulsionar | Coleção de verão",
"goal": "engagement",
"goal_label": "Engajamento",
"status": "creating",
"status_label": "Publicando",
"created_via": "api",
"budget": {
"level": "campaign",
"type": "daily",
"amount_cents": 5000,
"currency": "BRL"
},
"schedule": {
"starts_at": "2026-10-28T03:00:00+00:00",
"ends_at": null
},
"error": null,
"platform": "meta",
"platform_campaign_id": null,
"published_at": null,
"synced_at": null,
"created_at": "2026-10-28T15:00:00+00:00",
"updated_at": "2026-10-28T15:02:11+00:00",
"links": {
"panel": "https://app.leadgo.com.br/app/campaigns/01jby0q4c8m2d6t9v3k7w5r1xa"
},
"draft": null,
"boost": {
"name": "Impulsionar | Coleção de verão",
"goal": "engagement",
"status": "paused",
"budget": {
"type": "daily",
"amount_cents": 2000
},
"post": {
"source": "instagram",
"id": "17900000000000001",
"caption": null,
"thumbnail_url": null,
"permalink": null
},
"tracking": {
"pixel_id": "123456789012345"
}
},
"ad_sets": []
}
}
}
}
},
"422": {
"description": "Campos inválidos; o detalhe de cada um vem em errors.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "A conta ainda não vinculou uma conta de anúncio da Meta.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Já há 5 campanhas sendo publicadas nesta conta.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Token ausente, inválido, revogado ou vencido.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/campaigns/{id}": {
"get": {
"operationId": "api.v1.campaigns.show",
"tags": [
"Campanhas"
],
"externalDocs": {
"url": "https://leadgo.com.br/docs/api/referencia/campanhas#campaigns-show"
},
"summary": "Consultar campanha",
"description": "A campanha com os conjuntos, os anúncios (com a situação da revisão da Meta) e, se foi criada pelo LeadGo, o rascunho de criação em draft. Em status failed, o motivo vem em error.message.\n\nEscopo: `campaigns:read`.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Consultar campanha",
"content": {
"application/json": {
"example": {
"data": {
"id": "01jby0q4c8m2d6t9v3k7w5r1xa",
"name": "Promoção de outubro",
"goal": "traffic",
"goal_label": "Tráfego",
"status": "pending_review",
"status_label": "Em análise",
"created_via": "api",
"budget": {
"level": "campaign",
"type": "daily",
"amount_cents": 5000,
"currency": "BRL"
},
"schedule": {
"starts_at": "2026-10-28T03:00:00+00:00",
"ends_at": null
},
"error": null,
"platform": "meta",
"platform_campaign_id": "120212345678900001",
"published_at": "2026-10-28T15:02:11+00:00",
"synced_at": "2026-10-28T15:40:00+00:00",
"created_at": "2026-10-28T15:00:00+00:00",
"updated_at": "2026-10-28T15:02:11+00:00",
"draft": {
"name": "Promoção de outubro",
"goal": "traffic",
"status": "paused",
"budget": {
"type": "daily",
"amount_cents": 5000
},
"schedule": {
"start_date": "2026-10-28",
"end_date": null
},
"tracking": {
"pixel_id": "123456789012345",
"conversion_event": 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}}"
}
]
},
"special_ad_category": null,
"targeting": {
"countries": [
"BR"
],
"cities": [],
"age_min": 25,
"age_max": 55,
"gender": "all",
"interests": [],
"narrow_interests": [],
"audience_id": null
},
"link_url": "https://loja.exemplo.com.br/outubro",
"creatives": [
{
"media_type": "image",
"headline": "Outono com 30% off",
"body": "Peças selecionadas com frete grátis até domingo.",
"call_to_action": "SHOP_NOW"
}
],
"whatsapp": null,
"lead_form": null
},
"ad_sets": [
{
"id": 88,
"campaign_id": "01jby0q4c8m2d6t9v3k7w5r1xa",
"name": "Promoção de outubro - Público",
"status": "pending_review",
"budget": null,
"optimization_goal": "LINK_CLICKS",
"targeting": {
"geo_locations": {
"countries": [
"BR"
]
},
"age_min": 25,
"age_max": 55
},
"platform_ad_set_id": "120212345678900002",
"ads": [
{
"id": 140,
"campaign_id": "01jby0q4c8m2d6t9v3k7w5r1xa",
"ad_set_id": 88,
"name": "Promoção de outubro - Anúncio 1",
"status": "pending_review",
"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": null
}
]
}
],
"brain": {
"mode": null,
"effective_mode": "manual",
"target_cpa_cents": null,
"target_roas": null,
"effective_target_cpa_cents": 3000,
"effective_target_roas": null,
"locked_until": "2026-10-31T15:02:11+00:00",
"last_touched_at": null,
"last_touched_by": null
},
"links": {
"panel": "https://app.leadgo.com.br/app/campaigns/01jby0q4c8m2d6t9v3k7w5r1xa"
}
}
}
}
}
},
"404": {
"description": "O recurso não existe nesta conta.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Token ausente, inválido, revogado ou vencido.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Limite de requisições.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
},
"patch": {
"operationId": "api.v1.campaigns.update",
"tags": [
"Campanhas"
],
"externalDocs": {
"url": "https://leadgo.com.br/docs/api/referencia/campanhas#campaigns-update"
},
"summary": "Alterar campanha",
"description": "Nome, orçamento e status (ligar ou pausar) de uma campanha publicada, aplicados nessa ordem na Meta. Se um falhar, details.applied diz o que já mudou. Cada mudança abre a janela de maturação do Gestor IA (ele não mexe na campanha por alguns dias). O bloco brain muda a regra do Gestor IA só desta campanha (vale também antes de publicar e exige, de quem criou o token, a permissão de configurar a IA); a regra atual vem em brain no GET /campaigns/{id}.\n\nEscopo: `campaigns:write`.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Novo nome (até 120 caracteres)."
},
"budget": {
"type": "object",
"properties": {
"amount_cents": {
"type": "integer",
"description": "Novo orçamento em centavos (respeita a verba mínima da conta)."
}
}
},
"status": {
"type": "string",
"description": "active ou paused."
},
"brain": {
"type": "object",
"properties": {
"mode": {
"type": "string",
"description": "auto, manual ou off só nesta campanha; null volta a seguir a conta. O automático depende do plano."
},
"target_cpa_cents": {
"type": "integer",
"description": "Meta de custo por resultado em centavos (null usa a da conta)."
},
"target_roas": {
"type": "number",
"description": "Meta de ROAS, de 0 a 1000 (null usa a da conta)."
}
}
}
}
},
"example": {
"budget": {
"amount_cents": 8000
},
"status": "active",
"brain": {
"mode": "manual",
"target_cpa_cents": 2500
}
}
}
}
},
"responses": {
"200": {
"description": "Alterar campanha",
"content": {
"application/json": {
"example": {
"data": {
"id": "01jby0q4c8m2d6t9v3k7w5r1xa",
"name": "Promoção de outubro",
"goal": "traffic",
"goal_label": "Tráfego",
"status": "active",
"status_label": "Ativa",
"created_via": "api",
"budget": {
"level": "campaign",
"type": "daily",
"amount_cents": 5000,
"currency": "BRL"
},
"schedule": {
"starts_at": "2026-10-28T03:00:00+00:00",
"ends_at": null
},
"error": null,
"platform": "meta",
"platform_campaign_id": "120212345678900001",
"published_at": "2026-10-28T15:02:11+00:00",
"synced_at": "2026-10-28T15:40:00+00:00",
"created_at": "2026-10-28T15:00:00+00:00",
"updated_at": "2026-10-28T15:02:11+00:00",
"draft": {
"name": "Promoção de outubro",
"goal": "traffic",
"status": "paused",
"budget": {
"type": "daily",
"amount_cents": 5000
},
"schedule": {
"start_date": "2026-10-28",
"end_date": null
},
"tracking": {
"pixel_id": "123456789012345",
"conversion_event": 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}}"
}
]
},
"special_ad_category": null,
"targeting": {
"countries": [
"BR"
],
"cities": [],
"age_min": 25,
"age_max": 55,
"gender": "all",
"interests": [],
"narrow_interests": [],
"audience_id": null
},
"link_url": "https://loja.exemplo.com.br/outubro",
"creatives": [
{
"media_type": "image",
"headline": "Outono com 30% off",
"body": "Peças selecionadas com frete grátis até domingo.",
"call_to_action": "SHOP_NOW"
}
],
"whatsapp": null,
"lead_form": null
},
"ad_sets": [
{
"id": 88,
"campaign_id": "01jby0q4c8m2d6t9v3k7w5r1xa",
"name": "Promoção de outubro - Público",
"status": "active",
"budget": null,
"optimization_goal": "LINK_CLICKS",
"targeting": {
"geo_locations": {
"countries": [
"BR"
]
},
"age_min": 25,
"age_max": 55
},
"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
}
]
}
],
"brain": {
"mode": null,
"effective_mode": "manual",
"target_cpa_cents": null,
"target_roas": null,
"effective_target_cpa_cents": 3000,
"effective_target_roas": null,
"locked_until": "2026-10-31T15:02:11+00:00",
"last_touched_at": null,
"last_touched_by": null
},
"links": {
"panel": "https://app.leadgo.com.br/app/campaigns/01jby0q4c8m2d6t9v3k7w5r1xa"
}
}
}
}
}
},
"422": {
"description": "Campos inválidos; o detalhe de cada um vem em errors.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Quem criou o token não tem a permissão equivalente no painel.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "A campanha ainda não está na plataforma.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Token ausente, inválido, revogado ou vencido.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Limite de requisições.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
},
"delete": {
"operationId": "api.v1.campaigns.destroy",
"tags": [
"Campanhas"
],
"externalDocs": {
"url": "https://leadgo.com.br/docs/api/referencia/campanhas#campaigns-destroy"
},
"summary": "Excluir campanha",
"description": "Publicada: exclui de vez na Meta, com conjuntos e anúncios. Não publicada (falhou): descarta o rascunho. Durante a publicação, responde 409.\n\nEscopo: `campaigns:write`.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"204": {
"description": "Excluir campanha"
},
"404": {
"description": "O recurso não existe nesta conta.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "A campanha está sendo publicada; aguarde terminar.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"422": {
"description": "A Meta (via Zernio) recusou o pedido; o motivo vem em message.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Token ausente, inválido, revogado ou vencido.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Limite de requisições.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/campaigns/{id}/retry": {
"post": {
"operationId": "api.v1.campaigns.retry",
"tags": [
"Campanhas"
],
"externalDocs": {
"url": "https://leadgo.com.br/docs/api/referencia/campanhas#campaigns-retry"
},
"summary": "Reenviar publicação",
"description": "Tenta de novo publicar uma campanha com status failed, depois de corrigir o motivo (forma de pagamento, Página, conexão, Pixel...). As mídias que já subiram não sobem de novo. Uma campanha sem Pixel (publicada antes da 1.2.0) ganha o padrão da conta ou o único que ela enxerga; sem Pixel para escolher, o reenvio é recusado com operation_failed.\n\nEscopo: `campaigns:write`.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": false,
"description": "Valor único por operação: repetir devolve a primeira resposta.",
"schema": {
"type": "string",
"maxLength": 255
}
}
],
"responses": {
"202": {
"description": "Reenviar publicação",
"content": {
"application/json": {
"example": {
"data": {
"id": "01jby0q4c8m2d6t9v3k7w5r1xa",
"name": "Promoção de outubro",
"goal": "traffic",
"goal_label": "Tráfego",
"status": "creating",
"status_label": "Publicando",
"created_via": "api",
"budget": {
"level": "campaign",
"type": "daily",
"amount_cents": 5000,
"currency": "BRL"
},
"schedule": {
"starts_at": "2026-10-28T03:00:00+00:00",
"ends_at": null
},
"error": null,
"platform": "meta",
"platform_campaign_id": null,
"published_at": null,
"synced_at": null,
"created_at": "2026-10-28T15:00:00+00:00",
"updated_at": "2026-10-28T15:02:11+00:00",
"links": {
"panel": "https://app.leadgo.com.br/app/campaigns/01jby0q4c8m2d6t9v3k7w5r1xa"
}
}
}
}
}
},
"404": {
"description": "O recurso não existe nesta conta.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"422": {
"description": "Uma regra do painel impediu a operação; o motivo vem em message.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Token ausente, inválido, revogado ou vencido.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Limite de requisições.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/campaigns/{id}/duplicate": {
"post": {
"operationId": "api.v1.campaigns.duplicate",
"tags": [
"Campanhas"
],
"externalDocs": {
"url": "https://leadgo.com.br/docs/api/referencia/campanhas#campaigns-duplicate"
},
"summary": "Duplicar campanha",
"description": "Nova campanha igual a uma criada pelo LeadGo, trocando só o que vier no corpo (mesmos campos de POST /campaigns, todos opcionais). Mídias e formulário de cadastro são os da origem; o objetivo não muda. Saem todos os anúncios da origem, cada um com o tipo dele (arte, vídeo ou carrossel): os criativos se mesclam por posição e só os textos mudam. Envie [{\"headline\": \"...\"}] para trocar só o título do primeiro. media_id ou template_media_index num criativo ou num cartão é recusado (422); para outra mídia, crie a campanha em POST /campaigns. No carrossel, cards troca a lista inteira: envie todos os cartões, no mesmo número e na mesma ordem da origem (as imagens seguem as da origem). Num carrossel sozinho, os cartões ficam em carousel.cards, como no draft de GET /campaigns/{id}; creatives[0].cards também vale. Sem name, vira \"Nome (cópia)\".\n\nEscopo: `campaigns:write`.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "validate_only",
"in": "query",
"required": false,
"description": "Só confere (200, nada é criado).",
"schema": {
"type": "boolean"
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": false,
"description": "Valor único por operação: repetir devolve a primeira resposta.",
"schema": {
"type": "string",
"maxLength": 255
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object"
},
"example": {
"budget": {
"amount_cents": 9000
},
"creatives": [
{
"headline": "Agora com 40% off"
}
]
}
}
}
},
"responses": {
"202": {
"description": "Duplicar campanha",
"content": {
"application/json": {
"example": {
"data": {
"id": "01jby0q4c8m2d6t9v3k7w5r1xa",
"name": "Promoção de outubro",
"goal": "traffic",
"goal_label": "Tráfego",
"status": "creating",
"status_label": "Publicando",
"created_via": "api",
"budget": {
"level": "campaign",
"type": "daily",
"amount_cents": 5000,
"currency": "BRL"
},
"schedule": {
"starts_at": "2026-10-28T03:00:00+00:00",
"ends_at": null
},
"error": null,
"platform": "meta",
"platform_campaign_id": null,
"published_at": null,
"synced_at": null,
"created_at": "2026-10-28T15:00:00+00:00",
"updated_at": "2026-10-28T15:02:11+00:00",
"links": {
"panel": "https://app.leadgo.com.br/app/campaigns/01jby0q4c8m2d6t9v3k7w5r1xa"
}
}
}
}
}
},
"422": {
"description": "Campos inválidos; o detalhe de cada um vem em errors.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "Só campanhas criadas pelo LeadGo podem ser duplicadas.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Já há 5 campanhas sendo publicadas nesta conta.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Token ausente, inválido, revogado ou vencido.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/templates/{id}/campaigns": {
"post": {
"operationId": "api.v1.templates.campaigns.store",
"tags": [
"Campanhas"
],
"externalDocs": {
"url": "https://leadgo.com.br/docs/api/referencia/campanhas#templates-campaigns-store"
},
"summary": "Criar campanha a partir de um padrão",
"description": "Vale a configuração do padrão e o corpo traz só o que muda (mesmos campos de POST /campaigns, todos opcionais). Sem creatives (ou com null), saem todos os anúncios do padrão. Com creatives, sai só o que veio: um anúncio por item, na ordem, e os anúncios do padrão que não vierem ficam de fora. Na posição de um anúncio do padrão, {} o mantém como está (textos e mídia guardada), um item só com textos troca os textos e mantém a mídia, e um item com media_id ou cards troca o anúncio, inclusive o tipo (arte, vídeo ou carrossel). Itens além dos do padrão viram anúncios a mais no mesmo conjunto: repetem o título, o texto, a descrição e o botão do primeiro (já com o que veio no corpo) e trazem a própria mídia. Num padrão de um anúncio, por exemplo, [{\"media_id\": \"\"}, {\"media_id\": \"\"}] publica a foto e o vídeo como dois anúncios com os mesmos textos; com só uma das duas, envie um item. Cada cartão de carrossel usa a imagem guardada no padrão (template_media_index) ou uma nova (media_id). creatives [] é recusado. Até 10 anúncios, um carrossel só; variações de texto valem num anúncio simples. O padrão só de carrossel aceita também o formato antigo (format carousel e carousel.cards). Com persona no padrão, o público vem dela; o público da conta (audience_id), as exclusões (excluded_cities, excluded_audience_ids), os idiomas e o Advantage+ seguem os guardados no padrão. persona_id null usa o público guardado no padrão. Com duração definida no padrão, a data de término é calculada.\n\nEscopo: `campaigns:write`.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "validate_only",
"in": "query",
"required": false,
"description": "Só confere (200, nada é criado).",
"schema": {
"type": "boolean"
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": false,
"description": "Valor único por operação: repetir devolve a primeira resposta.",
"schema": {
"type": "string",
"maxLength": 255
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"creatives": {
"type": "array",
"items": {
"type": "object",
"properties": {
"media_id": {
"type": "string",
"description": "Arte ou vídeo novo da biblioteca para o anúncio dessa posição (troca o que o padrão tinha ali). Obrigatória nos itens além dos do padrão."
},
"template_media_index": {
"type": "integer",
"description": "Arte ou vídeo guardado no padrão (template_media_index e has_media em creatives de GET /templates/{id})."
},
"cards": {
"type": "array",
"items": {
"type": "object",
"properties": {
"media_id": {
"type": "string",
"description": "Imagem nova da biblioteca para o cartão."
},
"template_media_index": {
"type": "integer",
"description": "Imagem guardada no padrão para o cartão (creatives[].cards em GET /templates/{id})."
}
}
},
"description": "Carrossel nesta posição, com os mesmos campos de POST /campaigns (troca a lista inteira). Cada cartão leva media_id ou template_media_index."
}
}
},
"description": "Os anúncios a publicar, na ordem. Ausente ou null: todos os do padrão. Com a lista, só os enviados ({} mantém o anúncio do padrão daquela posição)."
}
}
},
"example": {
"name": "Oferta de novembro",
"budget": {
"amount_cents": 7000
},
"creatives": [
{
"media_id": "01jbx3m7k2q8f5v9w4n6c0r1ht"
},
{
"media_id": "01jbx3n2p6s0d4g8j2m6q0t4wy"
},
{
"cards": [
{
"media_id": "01jbx3p5r9t3e7h1k5n9r3v7c2",
"headline": "Vestidos",
"link_url": "https://loja.exemplo.com.br/verao/vestidos"
},
{
"media_id": "01jbx3q8v2w6a0c4f8j2m6p0s4",
"headline": "Sandálias",
"link_url": "https://loja.exemplo.com.br/verao/sandalias"
}
]
}
]
}
}
}
},
"responses": {
"202": {
"description": "Criar campanha a partir de um padrão",
"content": {
"application/json": {
"example": {
"data": {
"id": "01jby0q4c8m2d6t9v3k7w5r1xa",
"name": "Promoção de outubro",
"goal": "traffic",
"goal_label": "Tráfego",
"status": "creating",
"status_label": "Publicando",
"created_via": "api",
"budget": {
"level": "campaign",
"type": "daily",
"amount_cents": 5000,
"currency": "BRL"
},
"schedule": {
"starts_at": "2026-10-28T03:00:00+00:00",
"ends_at": null
},
"error": null,
"platform": "meta",
"platform_campaign_id": null,
"published_at": null,
"synced_at": null,
"created_at": "2026-10-28T15:00:00+00:00",
"updated_at": "2026-10-28T15:02:11+00:00",
"links": {
"panel": "https://app.leadgo.com.br/app/campaigns/01jby0q4c8m2d6t9v3k7w5r1xa"
}
}
}
}
}
},
"422": {
"description": "Campos inválidos; o detalhe de cada um vem em errors.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Já há 5 campanhas sendo publicadas nesta conta.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Token ausente, inválido, revogado ou vencido.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/ad-sets/{id}": {
"patch": {
"operationId": "api.v1.ad-sets.update",
"tags": [
"Conjuntos e anúncios"
],
"externalDocs": {
"url": "https://leadgo.com.br/docs/api/referencia/conjuntos-e-anuncios#ad-sets-update"
},
"summary": "Alterar conjunto",
"description": "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}.\n\nEscopo: `campaigns:write`.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Novo nome (até 120 caracteres)."
},
"budget": {
"type": "object",
"properties": {
"amount_cents": {
"type": "integer",
"description": "Novo orçamento do conjunto em centavos."
}
}
},
"status": {
"type": "string",
"description": "active ou paused."
}
}
},
"example": {
"budget": {
"amount_cents": 4000
},
"status": "active"
}
}
}
},
"responses": {
"200": {
"description": "Alterar conjunto",
"content": {
"application/json": {
"example": {
"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
}
]
}
}
}
}
},
"422": {
"description": "Campos inválidos; o detalhe de cada um vem em errors.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "O recurso não existe nesta conta.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "O status atual do conjunto ou do anúncio não permite ligar nem pausar.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Token ausente, inválido, revogado ou vencido.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Limite de requisições.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
},
"delete": {
"operationId": "api.v1.ad-sets.destroy",
"tags": [
"Conjuntos e anúncios"
],
"externalDocs": {
"url": "https://leadgo.com.br/docs/api/referencia/conjuntos-e-anuncios#ad-sets-destroy"
},
"summary": "Excluir conjunto",
"description": "Exclui de vez na Meta o conjunto e os anúncios dele. A campanha continua.\n\nEscopo: `campaigns:write`.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"204": {
"description": "Excluir conjunto"
},
"404": {
"description": "O recurso não existe nesta conta.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"422": {
"description": "A Meta (via Zernio) recusou o pedido; o motivo vem em message.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Token ausente, inválido, revogado ou vencido.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Limite de requisições.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/ads/{id}": {
"patch": {
"operationId": "api.v1.ads.update",
"tags": [
"Conjuntos e anúncios"
],
"externalDocs": {
"url": "https://leadgo.com.br/docs/api/referencia/conjuntos-e-anuncios#ads-update"
},
"summary": "Alterar anúncio",
"description": "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.\n\nEscopo: `campaigns:write`.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Novo nome."
},
"status": {
"type": "string",
"description": "active ou paused."
},
"creative": {
"type": "object",
"properties": {
"headline": {
"type": "string",
"description": "Título (até 255)."
},
"body": {
"type": "string",
"description": "Texto principal (até 2000)."
},
"description": {
"type": "string",
"description": "Descrição (até 255)."
},
"link_url": {
"type": "string",
"description": "Link https de destino."
},
"call_to_action": {
"type": "string",
"description": "Botão (veja GET /reference)."
},
"media_id": {
"type": "string",
"description": "Imagem nova, pronta na biblioteca (POST /media)."
}
}
},
"url_tags": {
"type": "array",
"items": {
"type": "object"
},
"description": "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}}."
}
}
},
"example": {
"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}}"
}
]
}
}
}
},
"responses": {
"200": {
"description": "Alterar anúncio",
"content": {
"application/json": {
"example": {
"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}}"
}
]
}
}
}
}
},
"422": {
"description": "Campos inválidos; o detalhe de cada um vem em errors.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "O recurso não existe nesta conta.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "O anúncio ainda não está na plataforma.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Token ausente, inválido, revogado ou vencido.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Limite de requisições.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
},
"delete": {
"operationId": "api.v1.ads.destroy",
"tags": [
"Conjuntos e anúncios"
],
"externalDocs": {
"url": "https://leadgo.com.br/docs/api/referencia/conjuntos-e-anuncios#ads-destroy"
},
"summary": "Excluir anúncio",
"description": "Exclui de vez o anúncio na Meta. O conjunto e a campanha continuam.\n\nEscopo: `campaigns:write`.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"204": {
"description": "Excluir anúncio"
},
"404": {
"description": "O recurso não existe nesta conta.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"422": {
"description": "A Meta (via Zernio) recusou o pedido; o motivo vem em message.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Token ausente, inválido, revogado ou vencido.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Limite de requisições.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/ads/{id}/preview": {
"get": {
"operationId": "api.v1.ads.preview",
"tags": [
"Conjuntos e anúncios"
],
"externalDocs": {
"url": "https://leadgo.com.br/docs/api/referencia/conjuntos-e-anuncios#ads-preview"
},
"summary": "Prévia do anúncio",
"description": "Como o anúncio publicado aparece em cada posicionamento, gerado pela Meta. url é o endereço da prévia para abrir num "
}
]
}
}
}
}
},
"422": {
"description": "Campos inválidos; o detalhe de cada um vem em errors.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "O recurso não existe nesta conta.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "O anúncio ainda não está na plataforma.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Muitas consultas novas à plataforma (buscas e métricas fora do cache).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"502": {
"description": "A plataforma de anúncios não respondeu. Tente de novo.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Token ausente, inválido, revogado ou vencido.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/personas": {
"get": {
"operationId": "api.v1.personas.index",
"tags": [
"Personas e padrões"
],
"externalDocs": {
"url": "https://leadgo.com.br/docs/api/referencia/personas-e-padroes#personas-index"
},
"summary": "Listar personas",
"description": "Públicos salvos da conta. Use o id em persona_id: a campanha herda idade, gênero, locais, interesses e grupos de interesses (o que vier em targeting sobrescreve, campo a campo).\n\nEscopo: `campaigns:read`.",
"responses": {
"200": {
"description": "Listar personas",
"content": {
"application/json": {
"example": {
"data": [
{
"id": 5,
"name": "Mães que trabalham fora",
"description": "Mulheres de 28 a 45 anos, com filhos pequenos, sem tempo para cozinhar.",
"source": "manual",
"targeting": {
"countries": [
"BR"
],
"cities": [],
"age_min": 28,
"age_max": 45,
"gender": "female",
"interests": [
{
"id": "6003107902433",
"name": "Maternidade"
}
],
"narrow_interests": []
},
"created_at": "2026-10-10T12:00:00+00:00",
"updated_at": "2026-10-10T12:00:00+00:00"
}
]
}
}
}
},
"401": {
"description": "Token ausente, inválido, revogado ou vencido.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Limite de requisições.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
},
"post": {
"operationId": "api.v1.personas.store",
"tags": [
"Personas e padrões"
],
"externalDocs": {
"url": "https://leadgo.com.br/docs/api/referencia/personas-e-padroes#personas-store"
},
"summary": "Criar persona",
"description": "Salva um público para reaproveitar nas campanhas e nos padrões. Aparece também no painel, no passo Público dos assistentes.\n\nEscopo: `campaigns:write`.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Nome (até 120 caracteres)."
},
"description": {
"type": "string",
"description": "Quem é esse cliente (até 2000)."
},
"source": {
"type": "string",
"description": "manual (padrão) ou ai, quando vier de POST /personas/generate."
},
"targeting": {
"type": "object",
"properties": {
"countries": {
"type": "array",
"items": {
"type": "string"
},
"description": "Países (GET /reference). Sem país nem cidade, o Brasil."
},
"cities": {
"type": "array",
"items": {
"type": "object"
},
"description": "Cidades {key, name, country_code, radius_km} de GET /targeting/cities."
},
"age_min": {
"type": "integer",
"description": "De 13 a 65 (padrão 18)."
},
"age_max": {
"type": "integer",
"description": "De 13 a 65 (padrão 65)."
},
"gender": {
"type": "string",
"description": "all, male ou female."
},
"interests": {
"type": "array",
"items": {
"type": "object"
},
"description": "Interesses {id, name} de GET /targeting/interests: basta ter um deles (OU)."
},
"narrow_interests": {
"type": "array",
"items": {
"type": "array",
"items": {
"type": "object"
}
},
"description": "Grupos que o público também precisa ter: um interesse de cada grupo (E), além de um da lista principal (OU). Até 3 grupos. Na campanha, não combina com Advantage+ público."
}
}
}
},
"required": [
"name"
]
},
"example": {
"name": "Mães que trabalham fora",
"description": "Mulheres de 28 a 45 anos, com filhos pequenos, sem tempo para cozinhar.",
"targeting": {
"countries": [
"BR"
],
"age_min": 28,
"age_max": 45,
"gender": "female",
"interests": [
{
"id": "6003107902433",
"name": "Maternidade"
}
]
}
}
}
}
},
"responses": {
"201": {
"description": "Criar persona",
"content": {
"application/json": {
"example": {
"data": {
"id": 5,
"name": "Mães que trabalham fora",
"description": "Mulheres de 28 a 45 anos, com filhos pequenos, sem tempo para cozinhar.",
"source": "manual",
"targeting": {
"countries": [
"BR"
],
"cities": [],
"age_min": 28,
"age_max": 45,
"gender": "female",
"interests": [
{
"id": "6003107902433",
"name": "Maternidade"
}
],
"narrow_interests": []
},
"created_at": "2026-10-10T12:00:00+00:00",
"updated_at": "2026-10-10T12:00:00+00:00"
}
}
}
}
},
"422": {
"description": "Campos inválidos; o detalhe de cada um vem em errors.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Token ausente, inválido, revogado ou vencido.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Limite de requisições.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/personas/{id}": {
"get": {
"operationId": "api.v1.personas.show",
"tags": [
"Personas e padrões"
],
"externalDocs": {
"url": "https://leadgo.com.br/docs/api/referencia/personas-e-padroes#personas-show"
},
"summary": "Consultar persona",
"description": "Uma persona da conta.\n\nEscopo: `campaigns:read`.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Consultar persona",
"content": {
"application/json": {
"example": {
"data": {
"id": 5,
"name": "Mães que trabalham fora",
"description": "Mulheres de 28 a 45 anos, com filhos pequenos, sem tempo para cozinhar.",
"source": "manual",
"targeting": {
"countries": [
"BR"
],
"cities": [],
"age_min": 28,
"age_max": 45,
"gender": "female",
"interests": [
{
"id": "6003107902433",
"name": "Maternidade"
}
],
"narrow_interests": []
},
"created_at": "2026-10-10T12:00:00+00:00",
"updated_at": "2026-10-10T12:00:00+00:00"
}
}
}
}
},
"404": {
"description": "O recurso não existe nesta conta.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Token ausente, inválido, revogado ou vencido.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Limite de requisições.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
},
"patch": {
"operationId": "api.v1.personas.update",
"tags": [
"Personas e padrões"
],
"externalDocs": {
"url": "https://leadgo.com.br/docs/api/referencia/personas-e-padroes#personas-update"
},
"summary": "Alterar persona",
"description": "Só o que vier muda; os campos de targeting enviados vão por cima dos atuais, um a um (enviar targeting.interests troca a lista toda; targeting.narrow_interests troca todos os grupos, e [] tira). Campanhas já criadas não mudam.\n\nEscopo: `campaigns:write`.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Novo nome."
},
"description": {
"type": "string",
"description": "Nova descrição (null apaga)."
},
"targeting": {
"type": "object",
"properties": {
"countries": {
"type": "array",
"items": {
"type": "string"
},
"description": "Países (GET /reference). Sem país nem cidade, o Brasil."
},
"cities": {
"type": "array",
"items": {
"type": "object"
},
"description": "Cidades {key, name, country_code, radius_km} de GET /targeting/cities."
},
"age_min": {
"type": "integer",
"description": "De 13 a 65 (padrão 18)."
},
"age_max": {
"type": "integer",
"description": "De 13 a 65 (padrão 65)."
},
"gender": {
"type": "string",
"description": "all, male ou female."
},
"interests": {
"type": "array",
"items": {
"type": "object"
},
"description": "Interesses {id, name} de GET /targeting/interests: basta ter um deles (OU)."
},
"narrow_interests": {
"type": "array",
"items": {
"type": "array",
"items": {
"type": "object"
}
},
"description": "Grupos que o público também precisa ter: um interesse de cada grupo (E), além de um da lista principal (OU). Até 3 grupos. Na campanha, não combina com Advantage+ público."
}
}
}
}
},
"example": {
"targeting": {
"age_min": 30
}
}
}
}
},
"responses": {
"200": {
"description": "Alterar persona",
"content": {
"application/json": {
"example": {
"data": {
"id": 5,
"name": "Mães que trabalham fora",
"description": "Mulheres de 28 a 45 anos, com filhos pequenos, sem tempo para cozinhar.",
"source": "manual",
"targeting": {
"countries": [
"BR"
],
"cities": [],
"age_min": 28,
"age_max": 45,
"gender": "female",
"interests": [
{
"id": "6003107902433",
"name": "Maternidade"
}
],
"narrow_interests": []
},
"created_at": "2026-10-10T12:00:00+00:00",
"updated_at": "2026-10-10T12:00:00+00:00"
}
}
}
}
},
"422": {
"description": "Campos inválidos; o detalhe de cada um vem em errors.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "O recurso não existe nesta conta.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Token ausente, inválido, revogado ou vencido.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Limite de requisições.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
},
"delete": {
"operationId": "api.v1.personas.destroy",
"tags": [
"Personas e padrões"
],
"externalDocs": {
"url": "https://leadgo.com.br/docs/api/referencia/personas-e-padroes#personas-destroy"
},
"summary": "Excluir persona",
"description": "Os padrões que usavam a persona passam a usar o público guardado neles; campanhas já criadas não mudam.\n\nEscopo: `campaigns:write`.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"204": {
"description": "Excluir persona"
},
"404": {
"description": "O recurso não existe nesta conta.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Token ausente, inválido, revogado ou vencido.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Limite de requisições.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/personas/generate": {
"post": {
"operationId": "api.v1.personas.generate",
"tags": [
"Personas e padrões"
],
"externalDocs": {
"url": "https://leadgo.com.br/docs/api/referencia/personas-e-padroes#personas-generate"
},
"summary": "Sugerir persona pela IA",
"description": "O \"Criar com a IA\" das personas: a partir do que o negócio vende e para quem, a IA sugere nome, descrição, idade, gênero, interesses e, quando o público pede um cruzamento, grupos de interesses em narrow_interests (procurados na Meta; os que não acharmos voltam em unresolved_keywords). Nada é salvo: revise e envie em POST /personas. Leva de 10 a 40 segundos. Limite de 10 por hora por pessoa, somado ao painel.\n\nEscopo: `ai:draft`.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"prompt": {
"type": "string",
"description": "O que o negócio vende e para quem (de 10 a 2000 caracteres)."
}
},
"required": [
"prompt"
]
},
"example": {
"prompt": "Marmitas fitness congeladas com entrega em São Paulo, para quem trabalha o dia todo e quer comer bem."
}
}
}
},
"responses": {
"200": {
"description": "Sugerir persona pela IA",
"content": {
"application/json": {
"example": {
"data": {
"name": "Profissional sem tempo",
"description": "Adultos de 25 a 45 anos que trabalham fora e cuidam da alimentação.",
"source": "ai",
"targeting": {
"countries": [
"BR"
],
"cities": [],
"age_min": 25,
"age_max": 45,
"gender": "all",
"interests": [
{
"id": "6003384248805",
"name": "Alimentação saudável"
}
],
"narrow_interests": []
},
"unresolved_keywords": [
"marmita fit"
]
}
}
}
}
},
"422": {
"description": "Campos inválidos; o detalhe de cada um vem em errors.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Limite de rascunhos pela IA por hora (somado ao painel).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "A IA não respondeu; tente de novo em instantes.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Token ausente, inválido, revogado ou vencido.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/templates": {
"get": {
"operationId": "api.v1.templates.index",
"tags": [
"Personas e padrões"
],
"externalDocs": {
"url": "https://leadgo.com.br/docs/api/referencia/personas-e-padroes#templates-index"
},
"summary": "Listar padrões de campanha",
"description": "Configurações prontas para reaproveitar (POST /templates/{id}/campaigns). Em creatives, um item por anúncio: has_media diz se o padrão já guarda a mídia daquele anúncio (no carrossel, de cada cartão, em cards).\n\nEscopo: `campaigns:read`.",
"responses": {
"200": {
"description": "Listar padrões de campanha",
"content": {
"application/json": {
"example": {
"data": [
{
"id": 9,
"name": "Oferta da semana",
"description": null,
"goal": "traffic",
"persona_id": null,
"duration_days": 7,
"uses_count": 12,
"last_used_at": "2026-10-27T10:00:00+00:00",
"creatives": [
{
"template_media_index": 0,
"media_type": "image",
"has_media": true
},
{
"media_type": "carousel",
"cards": [
{
"template_media_index": 1,
"has_media": true
},
{
"template_media_index": 2,
"has_media": true
}
]
}
],
"has_lead_form": false,
"draft": {
"name": "Oferta da semana",
"goal": "traffic",
"budget": {
"type": "daily",
"amount_cents": 3000
},
"link_url": "https://loja.exemplo.com.br"
},
"created_at": "2026-10-01T12:00:00+00:00"
}
]
}
}
}
},
"401": {
"description": "Token ausente, inválido, revogado ou vencido.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Limite de requisições.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/templates/{id}": {
"get": {
"operationId": "api.v1.templates.show",
"tags": [
"Personas e padrões"
],
"externalDocs": {
"url": "https://leadgo.com.br/docs/api/referencia/personas-e-padroes#templates-show"
},
"summary": "Consultar padrão",
"description": "Um padrão de campanha, com o rascunho completo em draft. Em creatives, um item por anúncio, na ordem: arte e vídeo trazem template_media_index, media_type e has_media; o carrossel traz media_type carousel e, em cards, o template_media_index e o has_media de cada cartão. Use esses índices em creatives[].template_media_index e creatives[].cards[].template_media_index.\n\nEscopo: `campaigns:read`.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Consultar padrão",
"content": {
"application/json": {
"example": {
"data": {
"id": 9,
"name": "Oferta da semana",
"description": null,
"goal": "traffic",
"persona_id": null,
"duration_days": 7,
"uses_count": 12,
"last_used_at": "2026-10-27T10:00:00+00:00",
"creatives": [
{
"template_media_index": 0,
"media_type": "image",
"has_media": true
},
{
"media_type": "carousel",
"cards": [
{
"template_media_index": 1,
"has_media": true
},
{
"template_media_index": 2,
"has_media": true
}
]
}
],
"has_lead_form": false,
"draft": {
"name": "Oferta da semana",
"goal": "traffic",
"budget": {
"type": "daily",
"amount_cents": 3000
},
"link_url": "https://loja.exemplo.com.br"
},
"created_at": "2026-10-01T12:00:00+00:00"
}
}
}
}
},
"404": {
"description": "O recurso não existe nesta conta.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Token ausente, inválido, revogado ou vencido.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Limite de requisições.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
},
"patch": {
"operationId": "api.v1.templates.update",
"tags": [
"Personas e padrões"
],
"externalDocs": {
"url": "https://leadgo.com.br/docs/api/referencia/personas-e-padroes#templates-update"
},
"summary": "Alterar padrão",
"description": "Edita o padrão por completo, menos o objetivo e a conta de anúncio. Só com name, description e persona_id, troca esses campos sem conferir a configuração (persona_id null tira a persona: vale o público guardado no padrão). Com qualquer outro campo, aceita os mesmos de POST /templates/{id}/campaigns (verba, público, posicionamentos, lance, link, rastreamento, mensagem do WhatsApp, textos, mídias, carrossel e variações de texto), todos opcionais, mais duration_days, com a mesma junção: objetos se mesclam campo a campo, listas são trocadas inteiras e, em creatives, sai só o que veio ({} mantém o anúncio do padrão daquela posição; media_id ou cards trocam o anúncio, inclusive o tipo; cards troca a lista inteira). As regras são as de criar campanha, na conta de anúncio do padrão (verba mínima, Pixel, públicos), mas a mídia pode faltar: anúncio ou cartão sem mídia fica sem mídia guardada, e ela é pedida ao usar o padrão. A mídia enviada é conferida: media_id da biblioteca sobe para o armazenamento e vira mídia guardada, e template_media_index aponta uma que o padrão já tem. Para manter a imagem de um cartão ao reenviar cards, envie o template_media_index dele (GET /templates/{id}). Com persona, o público vem dela; de targeting, seguem do padrão audience_id, excluded_cities, excluded_audience_ids, languages e advantage_audience, e o público guardado no padrão fica como está (é o que vale com persona_id null). Quando o público tem grupos de interesses (os da persona ou os enviados), o Advantage+ guardado sai sozinho; advantage_audience true enviado junto com grupos é recusado (422). goal diferente do padrão é recusado (422): para outro objetivo, crie outro padrão. schedule, status, lead_form e lead_form_id não entram: o padrão não guarda datas (a data de término sai de duration_days) e o formulário de cadastro segue o dele. Com orçamento total (lifetime), duration_days é obrigatório quando o padrão não tem duração. Com ?validate_only=true, confere do mesmo jeito e nada é gravado nem enviado ao armazenamento: a resposta é 200 com {\"data\": {\"valid\": true, \"template\": ...}}, o padrão como ficaria (a mídia da biblioteca aparece com has_media true). As campanhas já criadas com o padrão não mudam.\n\nEscopo: `campaigns:write`.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "validate_only",
"in": "query",
"required": false,
"description": "Só confere (200 com valid e o padrão como ficaria; nada é gravado e nenhuma mídia sobe).",
"schema": {
"type": "boolean"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Novo nome."
},
"description": {
"type": "string",
"description": "Nova descrição (null apaga)."
},
"persona_id": {
"type": "integer",
"description": "Persona do padrão (null tira)."
},
"duration_days": {
"type": "integer",
"description": "Duração das campanhas criadas com o padrão, de 1 a 365 dias (null: sem data de término)."
},
"budget": {
"type": "object",
"description": "type e amount_cents, como em POST /campaigns (verba mínima da conta do padrão)."
},
"targeting": {
"type": "object",
"description": "Público, como em POST /campaigns (os campos enviados trocam os do padrão)."
},
"link_url": {
"type": "string",
"description": "Link de destino."
},
"tracking": {
"type": "object",
"properties": {
"url_tags": {
"type": "array",
"items": {
"type": "object"
},
"description": "Parâmetros de URL extras {key, value}, somados aos 4 UTMs padrão ([] = nenhum extra)."
}
}
},
"creatives": {
"type": "array",
"items": {
"type": "object",
"properties": {
"media_id": {
"type": "string",
"description": "Arte ou vídeo da biblioteca que passa a ser a mídia guardada do anúncio."
},
"template_media_index": {
"type": "integer",
"description": "Mídia que o padrão já guarda (GET /templates/{id}), inclusive a de outra posição."
},
"cards": {
"type": "array",
"items": {
"type": "object",
"properties": {
"media_id": {
"type": "string",
"description": "Imagem da biblioteca que passa a ser a imagem guardada do cartão."
},
"template_media_index": {
"type": "integer",
"description": "Imagem guardada do cartão. Sem ela (nem media_id), o cartão fica sem imagem."
}
}
},
"description": "Os cartões do carrossel (troca a lista inteira, de 2 a 10)."
}
}
},
"description": "Os anúncios do padrão, na ordem, como em POST /templates/{id}/campaigns. Ausente ou null: ficam como estão. Item sem mídia é aceito."
}
}
},
"example": {
"budget": {
"amount_cents": 6000
},
"duration_days": 14,
"tracking": {
"url_tags": [
{
"key": "utm_term",
"value": "inverno"
}
]
},
"creatives": [
{
"media_id": "01jbx3m7k2q8f5v9w4n6c0r1ht",
"headline": "Coleção de inverno"
}
]
}
}
}
},
"responses": {
"200": {
"description": "Alterar padrão",
"content": {
"application/json": {
"example": {
"data": {
"id": 9,
"name": "Oferta da semana",
"description": null,
"goal": "traffic",
"persona_id": null,
"duration_days": 7,
"uses_count": 12,
"last_used_at": "2026-10-27T10:00:00+00:00",
"creatives": [
{
"template_media_index": 0,
"media_type": "image",
"has_media": true
},
{
"media_type": "carousel",
"cards": [
{
"template_media_index": 1,
"has_media": true
},
{
"template_media_index": 2,
"has_media": true
}
]
}
],
"has_lead_form": false,
"draft": {
"name": "Oferta da semana",
"goal": "traffic",
"budget": {
"type": "daily",
"amount_cents": 3000
},
"link_url": "https://loja.exemplo.com.br"
},
"created_at": "2026-10-01T12:00:00+00:00"
}
}
}
}
},
"422": {
"description": "Campos inválidos; o detalhe de cada um vem em errors.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "O recurso não existe nesta conta.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Muitas consultas novas à plataforma (buscas e métricas fora do cache).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"502": {
"description": "A plataforma de anúncios não respondeu. Tente de novo.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "A plataforma de anúncios pediu uma pausa. Espere o Retry-After.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Token ausente, inválido, revogado ou vencido.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
},
"delete": {
"operationId": "api.v1.templates.destroy",
"tags": [
"Personas e padrões"
],
"externalDocs": {
"url": "https://leadgo.com.br/docs/api/referencia/personas-e-padroes#templates-destroy"
},
"summary": "Excluir padrão",
"description": "As campanhas criadas com o padrão não mudam.\n\nEscopo: `campaigns:write`.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"204": {
"description": "Excluir padrão"
},
"404": {
"description": "O recurso não existe nesta conta.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Token ausente, inválido, revogado ou vencido.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Limite de requisições.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/campaigns/{id}/template": {
"post": {
"operationId": "api.v1.campaigns.template",
"tags": [
"Personas e padrões"
],
"externalDocs": {
"url": "https://leadgo.com.br/docs/api/referencia/personas-e-padroes#campaigns-template"
},
"summary": "Criar padrão a partir de uma campanha",
"description": "Congela a configuração da campanha (objetivo, verba, público, textos e mídias) para a próxima nascer igual. Vale para as criadas aqui e para as importadas da Meta (essas gastam a cota de consultas à plataforma). O público vira uma persona nova (new_persona), usa uma existente (existing_persona) ou fica só no padrão (inline, o padrão). Com replace_template_id, atualiza um padrão que já existe em vez de criar outro. Campanhas com carrossel viram padrão com a imagem de cada cartão; posts impulsionados, não.\n\nEscopo: `campaigns:write`.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Nome do padrão (até 120)."
},
"description": {
"type": "string",
"description": "Até 500 caracteres."
},
"audience": {
"type": "object",
"properties": {
"mode": {
"type": "string",
"description": "new_persona, existing_persona ou inline (padrão)."
},
"persona_name": {
"type": "string",
"description": "Com new_persona: nome da persona criada."
},
"persona_id": {
"type": "integer",
"description": "Com existing_persona: a persona a usar."
}
}
},
"replace_template_id": {
"type": "integer",
"description": "Padrão a atualizar (responde 200 em vez de 201)."
}
},
"required": [
"name"
]
},
"example": {
"name": "Oferta da semana",
"audience": {
"mode": "new_persona",
"persona_name": "Público da oferta da semana"
}
}
}
}
},
"responses": {
"201": {
"description": "Criar padrão a partir de uma campanha",
"content": {
"application/json": {
"example": {
"data": {
"id": 9,
"name": "Oferta da semana",
"description": null,
"goal": "traffic",
"persona_id": null,
"duration_days": 7,
"uses_count": 12,
"last_used_at": "2026-10-27T10:00:00+00:00",
"creatives": [
{
"template_media_index": 0,
"media_type": "image",
"has_media": true
},
{
"media_type": "carousel",
"cards": [
{
"template_media_index": 1,
"has_media": true
},
{
"template_media_index": 2,
"has_media": true
}
]
}
],
"has_lead_form": false,
"draft": {
"name": "Oferta da semana",
"goal": "traffic",
"budget": {
"type": "daily",
"amount_cents": 3000
},
"link_url": "https://loja.exemplo.com.br"
},
"created_at": "2026-10-01T12:00:00+00:00"
}
}
}
}
},
"422": {
"description": "Campos inválidos; o detalhe de cada um vem em errors.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "O recurso não existe nesta conta.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "Posts impulsionados, campanhas ainda publicando e importadas com um objetivo que o LeadGo não recria não viram padrão.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Muitas consultas novas à plataforma (buscas e métricas fora do cache).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"502": {
"description": "A plataforma de anúncios não respondeu. Tente de novo.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Token ausente, inválido, revogado ou vencido.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/audiences": {
"get": {
"operationId": "api.v1.audiences.index",
"tags": [
"Públicos"
],
"externalDocs": {
"url": "https://leadgo.com.br/docs/api/referencia/publicos#audiences-index"
},
"summary": "Listar públicos",
"description": "Os públicos da conta de anúncio: os do sistema (source system: compradores e o semelhante a eles), os de remarketing criados pela API ou pelo painel (source user) e os que já existiam na Meta (source imported, trazidos por POST /audiences/sync e todo dia). Use o platform_audience_id em targeting.audience_id (incluir) ou targeting.excluded_audience_ids (deixar de fora).\n\nEscopo: `campaigns:read`.",
"parameters": [
{
"name": "type",
"in": "query",
"required": false,
"description": "customer_list, lookalike, website ou meta_engagement.",
"schema": {
"type": "string"
}
},
{
"name": "source",
"in": "query",
"required": false,
"description": "system, user ou imported.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Listar públicos",
"content": {
"application/json": {
"example": {
"data": [
{
"id": 17,
"platform_audience_id": "23859876543210987",
"name": "Visitantes do site — 30 dias",
"description": null,
"type": "website",
"type_label": "Visitantes do site",
"source": "user",
"purpose": null,
"status": "ready",
"rule": {
"pixel_id": "123456789012345",
"retention_days": 30,
"url_contains": "/produtos"
},
"country": null,
"approximate_size": 4800,
"can_delete": true,
"last_synced_at": "2026-10-28T15:00:00+00:00",
"created_at": "2026-10-28T15:00:00+00:00"
},
{
"id": 3,
"platform_audience_id": "23851234567890123",
"name": "Compradores",
"description": null,
"type": "customer_list",
"type_label": "Lista de clientes",
"source": "system",
"purpose": "buyers",
"status": null,
"rule": null,
"country": null,
"approximate_size": 1200,
"can_delete": false,
"last_synced_at": "2026-10-28T03:00:00+00:00",
"created_at": "2026-10-01T03:00:00+00:00"
}
]
}
}
}
},
"422": {
"description": "Campos inválidos; o detalhe de cada um vem em errors.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "A conta ainda não vinculou uma conta de anúncio da Meta.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Token ausente, inválido, revogado ou vencido.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Limite de requisições.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
},
"post": {
"operationId": "api.v1.audiences.store",
"tags": [
"Públicos"
],
"externalDocs": {
"url": "https://leadgo.com.br/docs/api/referencia/publicos#audiences-store"
},
"summary": "Criar público de remarketing",
"description": "Cria na Meta um público de quem visitou o site (type website, pelo Pixel) ou de quem interagiu com a Página ou o perfil do Instagram (type meta_engagement). A pessoa fica no público pelos dias de retention_days depois da última visita ou interação. Gasta a cota de consultas à plataforma.\n\nEscopo: `campaigns:write`.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "website ou meta_engagement."
},
"name": {
"type": "string",
"description": "Nome do público (até 120 caracteres)."
},
"description": {
"type": "string",
"description": "Para você lembrar do que se trata (até 500)."
},
"retention_days": {
"type": "integer",
"description": "Dias para trás: até 180 no website e até 365 no engajamento."
},
"pixel_id": {
"type": "string",
"description": "website: o Pixel (GET /ad-account/pixels). Obrigatório nesse tipo."
},
"url_contains": {
"type": "string",
"description": "website: só quem visitou páginas cujo endereço contém esse trecho (ex.: /produtos). Em branco, qualquer página."
},
"engagement_source": {
"type": "string",
"description": "meta_engagement: page (Página do Facebook) ou instagram. Obrigatório nesse tipo."
},
"source_id": {
"type": "string",
"description": "meta_engagement: id da Página ou do perfil do Instagram (GET /ad-account/instagram-accounts). Em branco com page, vale a Página da conexão; com instagram é obrigatório."
}
},
"required": [
"type",
"name",
"retention_days"
]
},
"example": {
"type": "website",
"name": "Visitantes do site — 30 dias",
"retention_days": 30,
"pixel_id": "123456789012345",
"url_contains": "/produtos"
}
}
}
},
"responses": {
"201": {
"description": "Criar público de remarketing",
"content": {
"application/json": {
"example": {
"data": {
"id": 17,
"platform_audience_id": "23859876543210987",
"name": "Visitantes do site — 30 dias",
"description": null,
"type": "website",
"type_label": "Visitantes do site",
"source": "user",
"purpose": null,
"status": "ready",
"rule": {
"pixel_id": "123456789012345",
"retention_days": 30,
"url_contains": "/produtos"
},
"country": null,
"approximate_size": 4800,
"can_delete": true,
"last_synced_at": "2026-10-28T15:00:00+00:00",
"created_at": "2026-10-28T15:00:00+00:00"
}
}
}
}
},
"422": {
"description": "Campos inválidos; o detalhe de cada um vem em errors.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "A conta ainda não vinculou uma conta de anúncio da Meta.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Muitas consultas novas à plataforma (buscas e métricas fora do cache).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"502": {
"description": "A plataforma de anúncios não respondeu. Tente de novo.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Token ausente, inválido, revogado ou vencido.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/audiences/{id}": {
"get": {
"operationId": "api.v1.audiences.show",
"tags": [
"Públicos"
],
"externalDocs": {
"url": "https://leadgo.com.br/docs/api/referencia/publicos#audiences-show"
},
"summary": "Consultar público",
"description": "Um público pelo id. approximate_size e status são os da última sincronização (a Meta leva algumas horas para encher um público novo e só entrega anúncios para ele a partir de cerca de 100 pessoas).\n\nEscopo: `campaigns:read`.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Consultar público",
"content": {
"application/json": {
"example": {
"data": {
"id": 17,
"platform_audience_id": "23859876543210987",
"name": "Visitantes do site — 30 dias",
"description": null,
"type": "website",
"type_label": "Visitantes do site",
"source": "user",
"purpose": null,
"status": "ready",
"rule": {
"pixel_id": "123456789012345",
"retention_days": 30,
"url_contains": "/produtos"
},
"country": null,
"approximate_size": 4800,
"can_delete": true,
"last_synced_at": "2026-10-28T15:00:00+00:00",
"created_at": "2026-10-28T15:00:00+00:00"
}
}
}
}
},
"404": {
"description": "O recurso não existe nesta conta.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Token ausente, inválido, revogado ou vencido.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Limite de requisições.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
},
"delete": {
"operationId": "api.v1.audiences.destroy",
"tags": [
"Públicos"
],
"externalDocs": {
"url": "https://leadgo.com.br/docs/api/referencia/publicos#audiences-destroy"
},
"summary": "Excluir público",
"description": "Exclui o público na Meta e aqui. Só os que têm can_delete true: os do sistema são mantidos pelas vendas dos leads, e os criados direto na Meta se excluem pelo Gerenciador de Anúncios. Campanhas que usavam o público perdem essa parte da segmentação.\n\nEscopo: `campaigns:write`.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"204": {
"description": "Excluir público"
},
"404": {
"description": "O recurso não existe nesta conta.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "Público do sistema (compradores) ou criado direto na Meta: não se exclui pela API.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Muitas consultas novas à plataforma (buscas e métricas fora do cache).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"422": {
"description": "A Meta (via Zernio) recusou o pedido; o motivo vem em message.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Token ausente, inválido, revogado ou vencido.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/audiences/sync": {
"post": {
"operationId": "api.v1.audiences.sync",
"tags": [
"Públicos"
],
"externalDocs": {
"url": "https://leadgo.com.br/docs/api/referencia/publicos#audiences-sync"
},
"summary": "Sincronizar públicos com a Meta",
"description": "Traz na hora a lista da conta de anúncio: os criados direto na Meta entram como imported, os conhecidos atualizam tamanho e situação, e os que sumiram de lá saem daqui. As rotinas já fazem isso todo dia; aqui, no máximo uma vez por minuto.\n\nEscopo: `campaigns:write`.",
"responses": {
"200": {
"description": "Sincronizar públicos com a Meta",
"content": {
"application/json": {
"example": {
"data": {
"created": 2,
"updated": 5,
"removed": 0
}
}
}
}
},
"409": {
"description": "A conta ainda não vinculou uma conta de anúncio da Meta.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Uma sincronização foi pedida há pouco (campanhas: 5 minutos; públicos: 1 minuto). Espere o Retry-After.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"422": {
"description": "Uma regra do painel impediu a operação; o motivo vem em message.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"502": {
"description": "A plataforma de anúncios não respondeu. Tente de novo.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Token ausente, inválido, revogado ou vencido.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/campaigns/{id}/metrics": {
"get": {
"operationId": "api.v1.campaigns.metrics",
"tags": [
"Métricas e relatórios"
],
"externalDocs": {
"url": "https://leadgo.com.br/docs/api/referencia/metricas#campaigns-metrics"
},
"summary": "Métricas da campanha",
"description": "Resumo, série diária e quebras (idade, gênero, plataforma) do período, no fuso da conta, mais o resultado de cada conjunto (ad_sets) e de cada anúncio (ads), para comparar criativos. Valores de dinheiro na moeda da conta, em unidades (312.5 = R$ 312,50). results segue o objetivo (compras, leads do formulário, conversas do WhatsApp...). Até 90 dias por consulta; sem datas, os últimos 7 dias. Cache de 10 minutos.\n\nEscopo: `reports:read`.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "from",
"in": "query",
"required": false,
"description": "Data inicial (AAAA-MM-DD).",
"schema": {
"type": "string"
}
},
{
"name": "to",
"in": "query",
"required": false,
"description": "Data final (AAAA-MM-DD), inclusive.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Métricas da campanha",
"content": {
"application/json": {
"example": {
"data": {
"campaign_id": "01jby0q4c8m2d6t9v3k7w5r1xa",
"from": "2026-10-01",
"to": "2026-10-27",
"currency": "BRL",
"result_goal": "conversions",
"summary": {
"spend": 312.5,
"impressions": 48000,
"reach": 21000,
"clicks": 960,
"results": 24,
"purchase_value": 1890,
"ctr": 2,
"cpc": 0.3255,
"cpm": 6.5104,
"cost_per_result": 13.0208,
"roas": 6.048
},
"daily": [
{
"date": "2026-10-27",
"spend": 12.3,
"impressions": 1900,
"reach": 1500,
"clicks": 41,
"results": 1,
"purchase_value": 89.9,
"ctr": 2.1579,
"cpc": 0.3,
"cpm": 6.4737,
"cost_per_result": 12.3,
"roas": 7.309
}
],
"breakdowns": {
"age": [
{
"age": "25-34",
"spend": 200
}
]
},
"backfill_pending": false,
"ad_sets": [
{
"id": 88,
"name": "Mulheres 25-45 SP",
"spend": 312.5,
"impressions": 48000,
"reach": 21000,
"clicks": 960,
"results": 24,
"purchase_value": 1890,
"ctr": 2,
"cpc": 0.3255,
"cpm": 6.5104,
"cost_per_result": 13.0208,
"roas": 6.048
}
],
"ads": [
{
"id": 140,
"ad_set_id": 88,
"name": "Promoção de outubro - Anúncio 1",
"spend": 312.5,
"impressions": 48000,
"reach": 21000,
"clicks": 960,
"results": 24,
"purchase_value": 1890,
"ctr": 2,
"cpc": 0.3255,
"cpm": 6.5104,
"cost_per_result": 13.0208,
"roas": 6.048
}
]
}
}
}
}
},
"422": {
"description": "Campos inválidos; o detalhe de cada um vem em errors.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "A campanha ainda não está na plataforma.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Muitas consultas novas à plataforma (buscas e métricas fora do cache).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"502": {
"description": "A plataforma de anúncios não respondeu. Tente de novo.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Token ausente, inválido, revogado ou vencido.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/ads/{id}/metrics": {
"get": {
"operationId": "api.v1.ads.metrics",
"tags": [
"Métricas e relatórios"
],
"externalDocs": {
"url": "https://leadgo.com.br/docs/api/referencia/metricas#ads-metrics"
},
"summary": "Métricas do anúncio",
"description": "Resumo, série diária e quebras de um anúncio, no mesmo formato das métricas da campanha (results segue o objetivo dela). Até 90 dias por consulta; sem datas, os últimos 7 dias. Cache de 10 minutos.\n\nEscopo: `reports:read`.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "from",
"in": "query",
"required": false,
"description": "Data inicial (AAAA-MM-DD).",
"schema": {
"type": "string"
}
},
{
"name": "to",
"in": "query",
"required": false,
"description": "Data final (AAAA-MM-DD), inclusive.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Métricas do anúncio",
"content": {
"application/json": {
"example": {
"data": {
"ad_id": 140,
"campaign_id": "01jby0q4c8m2d6t9v3k7w5r1xa",
"from": "2026-10-01",
"to": "2026-10-27",
"currency": "BRL",
"result_goal": "conversions",
"summary": {
"spend": 312.5,
"impressions": 48000,
"reach": 21000,
"clicks": 960,
"results": 24,
"purchase_value": 1890,
"ctr": 2,
"cpc": 0.3255,
"cpm": 6.5104,
"cost_per_result": 13.0208,
"roas": 6.048
},
"daily": [
{
"date": "2026-10-27",
"spend": 12.3,
"impressions": 1900,
"reach": 1500,
"clicks": 41,
"results": 1,
"purchase_value": 89.9,
"ctr": 2.1579,
"cpc": 0.3,
"cpm": 6.4737,
"cost_per_result": 12.3,
"roas": 7.309
}
],
"breakdowns": {
"publisher_platform": [
{
"publisher_platform": "instagram",
"spend": 180
}
]
},
"backfill_pending": false
}
}
}
}
},
"422": {
"description": "Campos inválidos; o detalhe de cada um vem em errors.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "O recurso não existe nesta conta.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "O anúncio ainda não está na plataforma.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Muitas consultas novas à plataforma (buscas e métricas fora do cache).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"502": {
"description": "A plataforma de anúncios não respondeu. Tente de novo.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Token ausente, inválido, revogado ou vencido.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/reports/account": {
"get": {
"operationId": "api.v1.reports.account",
"tags": [
"Métricas e relatórios"
],
"externalDocs": {
"url": "https://leadgo.com.br/docs/api/referencia/metricas#reports-account"
},
"summary": "Relatório da conta",
"description": "Totais e série diária da conta de anúncio inteira (todas as campanhas, inclusive as criadas fora do LeadGo), como na tela Relatórios do painel. results soma os resultados de cada campanha pelo objetivo dela. Até 90 dias por consulta; sem datas, os últimos 7 dias. Cache de 10 minutos.\n\nEscopo: `reports:read`.",
"parameters": [
{
"name": "from",
"in": "query",
"required": false,
"description": "Data inicial (AAAA-MM-DD).",
"schema": {
"type": "string"
}
},
{
"name": "to",
"in": "query",
"required": false,
"description": "Data final (AAAA-MM-DD), inclusive.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Relatório da conta",
"content": {
"application/json": {
"example": {
"data": {
"period": {
"from": "2026-10-01",
"to": "2026-10-27"
},
"currency": "BRL",
"summary": {
"spend": 312.5,
"impressions": 48000,
"reach": 21000,
"clicks": 960,
"results": 24,
"purchase_value": 1890,
"ctr": 2,
"cpc": 0.3255,
"cpm": 6.5104,
"cost_per_result": 13.0208,
"roas": 6.048
},
"daily": [
{
"date": "2026-10-27",
"spend": 12.3,
"impressions": 1900,
"reach": 1500,
"clicks": 41,
"results": 1,
"purchase_value": 89.9,
"ctr": 2.1579,
"cpc": 0.3,
"cpm": 6.4737,
"cost_per_result": 12.3,
"roas": 7.309
}
],
"backfill_pending": false
}
}
}
}
},
"422": {
"description": "Campos inválidos; o detalhe de cada um vem em errors.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "A conta ainda não vinculou uma conta de anúncio da Meta.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Muitas consultas novas à plataforma (buscas e métricas fora do cache).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"502": {
"description": "A plataforma de anúncios não respondeu. Tente de novo.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Token ausente, inválido, revogado ou vencido.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/reports/campaigns": {
"get": {
"operationId": "api.v1.reports.campaigns",
"tags": [
"Métricas e relatórios"
],
"externalDocs": {
"url": "https://leadgo.com.br/docs/api/referencia/metricas#reports-campaigns"
},
"summary": "Resultado por campanha",
"description": "Uma linha por campanha que rodou no período, do maior gasto para o menor, com o id daqui (campaign_id) para cruzar com GET /campaigns. Campanhas criadas fora do LeadGo e ainda não sincronizadas vêm com campaign_id null. Até 90 dias por consulta; sem datas, os últimos 7 dias. Cache de 10 minutos.\n\nEscopo: `reports:read`.",
"parameters": [
{
"name": "from",
"in": "query",
"required": false,
"description": "Data inicial (AAAA-MM-DD).",
"schema": {
"type": "string"
}
},
{
"name": "to",
"in": "query",
"required": false,
"description": "Data final (AAAA-MM-DD), inclusive.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Resultado por campanha",
"content": {
"application/json": {
"example": {
"data": {
"period": {
"from": "2026-10-01",
"to": "2026-10-27"
},
"currency": "BRL",
"campaigns": [
{
"campaign_id": "01jby0q4c8m2d6t9v3k7w5r1xa",
"platform_campaign_id": "120212345678900001",
"name": "Promoção de outubro",
"status": "active",
"metrics": {
"spend": 312.5,
"impressions": 48000,
"reach": 21000,
"clicks": 960,
"results": 24,
"purchase_value": 1890,
"ctr": 2,
"cpc": 0.3255,
"cpm": 6.5104,
"cost_per_result": 13.0208,
"roas": 6.048
}
}
],
"backfill_pending": false
}
}
}
}
},
"422": {
"description": "Campos inválidos; o detalhe de cada um vem em errors.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "A conta ainda não vinculou uma conta de anúncio da Meta.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Muitas consultas novas à plataforma (buscas e métricas fora do cache).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"502": {
"description": "A plataforma de anúncios não respondeu. Tente de novo.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Token ausente, inválido, revogado ou vencido.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/leads": {
"get": {
"operationId": "api.v1.leads.index",
"tags": [
"Leads"
],
"externalDocs": {
"url": "https://leadgo.com.br/docs/api/referencia/leads#leads-index"
},
"summary": "Listar leads",
"description": "Leads dos formulários instantâneos, dos mais novos para os mais antigos, com as respostas, a nota da IA e a campanha de origem. Pagine com cursor (meta.next_cursor). Para manter um CRM em dia, prefira os webhooks lead.created, lead.scored e lead.status_changed e use esta rota para a carga inicial ou para conferir. Dados pessoais: guarde só o que precisar.\n\nEscopo: `leads:read`.",
"parameters": [
{
"name": "status",
"in": "query",
"required": false,
"description": "new, contacted, qualified, won, lost ou spam.",
"schema": {
"type": "string"
}
},
{
"name": "campaign_id",
"in": "query",
"required": false,
"description": "Só os leads de uma campanha.",
"schema": {
"type": "string"
}
},
{
"name": "score",
"in": "query",
"required": false,
"description": "Nota da IA: hot, warm ou cold.",
"schema": {
"type": "string"
}
},
{
"name": "received_from",
"in": "query",
"required": false,
"description": "Recebidos a partir deste dia (AAAA-MM-DD, no fuso da conta).",
"schema": {
"type": "string"
}
},
{
"name": "received_to",
"in": "query",
"required": false,
"description": "Recebidos até este dia, inclusive (AAAA-MM-DD).",
"schema": {
"type": "string"
}
},
{
"name": "search",
"in": "query",
"required": false,
"description": "Nome, e-mail ou parte do telefone (4 dígitos ou mais).",
"schema": {
"type": "string"
}
},
{
"name": "limit",
"in": "query",
"required": false,
"description": "Itens por página, de 1 a 100 (padrão 25).",
"schema": {
"type": "integer"
}
},
{
"name": "cursor",
"in": "query",
"required": false,
"description": "meta.next_cursor da página anterior.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Listar leads",
"content": {
"application/json": {
"example": {
"data": [
{
"id": "01jbz2k8m4q0t6w2y8b4e0h6na",
"platform_lead_id": "1234567890123456",
"name": "Mariana Lima",
"email": "mariana@exemplo.com.br",
"phone": "+5511987654321",
"answers": {
"Qual o melhor horário para contato?": "Depois das 18h",
"Qual produto você procura?": "Kit verão"
},
"status": "new",
"status_label": "Novo",
"value_cents": null,
"lost_reason": null,
"score": "hot",
"score_label": "Quente",
"score_reason": "Respondeu o produto e o horário; quer comprar já.",
"suggested_message": "Oi, Mariana! Vi que você procura o Kit verão. Posso te mandar as opções depois das 18h?",
"whatsapp_url": "https://wa.me/5511987654321?text=Oi%2C%20Mariana%21",
"campaign": {
"id": "01jby0q4c8m2d6t9v3k7w5r1xa",
"name": "Cadastro kit verão"
},
"ad_set": {
"id": 88,
"name": "Mulheres 25-45 SP"
},
"ad": {
"id": 140,
"name": "Anúncio 1"
},
"form_id": "987654321098765",
"received_at": "2026-10-28T14:20:00+00:00",
"first_contact_at": null,
"qualified_at": null,
"won_at": null,
"scored_at": "2026-10-28T14:20:09+00:00",
"links": {
"panel": "https://app.leadgo.com.br/app/leads/01jbz2k8m4q0t6w2y8b4e0h6na"
}
}
],
"links": {
"first": null,
"last": null,
"prev": null,
"next": "https://app.leadgo.com.br/api/v1/leads?cursor=eyJpZCI6..."
},
"meta": {
"path": "https://app.leadgo.com.br/api/v1/leads",
"per_page": 25,
"next_cursor": "eyJpZCI6...",
"prev_cursor": null
}
}
}
}
},
"422": {
"description": "Campos inválidos; o detalhe de cada um vem em errors.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Token ausente, inválido, revogado ou vencido.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Limite de requisições.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/leads/stats": {
"get": {
"operationId": "api.v1.leads.stats",
"tags": [
"Leads"
],
"externalDocs": {
"url": "https://leadgo.com.br/docs/api/referencia/leads#leads-stats"
},
"summary": "Indicadores do funil",
"description": "Os mesmos números da central de leads do painel no período: leads (sem spam), qualificados, vendas, faturamento em centavos, taxa de qualificação (%), minutos até o primeiro contato e custo por qualificado (na moeda da conta, com o gasto das campanhas de origem).\n\nEscopo: `leads:read`.",
"parameters": [
{
"name": "days",
"in": "query",
"required": false,
"description": "7, 30 (padrão), 90 ou 0 (todo o período).",
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Indicadores do funil",
"content": {
"application/json": {
"example": {
"data": {
"days": 30,
"today": 4,
"total": 182,
"qualified": 61,
"won": 23,
"revenue_cents": 1873400,
"qualification_rate": 41.2,
"avg_first_contact_minutes": 37,
"cost_per_qualified": 18.4,
"currency": "BRL"
}
}
}
}
},
"422": {
"description": "Campos inválidos; o detalhe de cada um vem em errors.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Token ausente, inválido, revogado ou vencido.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Limite de requisições.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/leads/{id}": {
"get": {
"operationId": "api.v1.leads.show",
"tags": [
"Leads"
],
"externalDocs": {
"url": "https://leadgo.com.br/docs/api/referencia/leads#leads-show"
},
"summary": "Consultar lead",
"description": "Um lead com o histórico (events, do mais novo ao mais antigo): recebido, nota da IA, mudanças de etapa, notas, contatos e envios ao CRM e à Meta.\n\nEscopo: `leads:read`.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Consultar lead",
"content": {
"application/json": {
"example": {
"data": {
"id": "01jbz2k8m4q0t6w2y8b4e0h6na",
"platform_lead_id": "1234567890123456",
"name": "Mariana Lima",
"email": "mariana@exemplo.com.br",
"phone": "+5511987654321",
"answers": {
"Qual o melhor horário para contato?": "Depois das 18h",
"Qual produto você procura?": "Kit verão"
},
"status": "won",
"status_label": "Vendeu",
"value_cents": 25900,
"lost_reason": null,
"score": "hot",
"score_label": "Quente",
"score_reason": "Respondeu o produto e o horário; quer comprar já.",
"suggested_message": "Oi, Mariana! Vi que você procura o Kit verão. Posso te mandar as opções depois das 18h?",
"whatsapp_url": "https://wa.me/5511987654321?text=Oi%2C%20Mariana%21",
"campaign": {
"id": "01jby0q4c8m2d6t9v3k7w5r1xa",
"name": "Cadastro kit verão"
},
"ad_set": {
"id": 88,
"name": "Mulheres 25-45 SP"
},
"ad": {
"id": 140,
"name": "Anúncio 1"
},
"form_id": "987654321098765",
"received_at": "2026-10-28T14:20:00+00:00",
"first_contact_at": "2026-10-28T14:35:00+00:00",
"qualified_at": "2026-10-28T16:00:00+00:00",
"won_at": "2026-10-28T16:00:00+00:00",
"scored_at": "2026-10-28T14:20:09+00:00",
"events": [
{
"id": 902,
"type": "status_changed",
"label": "Status alterado",
"data": {
"from": "contacted",
"to": "won",
"value_cents": 25900
},
"user": {
"id": 42,
"name": "Ana Souza"
},
"created_at": "2026-10-28T16:00:00+00:00"
},
{
"id": 901,
"type": "scored",
"label": "Qualificado pela IA",
"data": {
"score": "hot"
},
"user": null,
"created_at": "2026-10-28T14:20:09+00:00"
},
{
"id": 900,
"type": "received",
"label": "Lead recebido",
"data": null,
"user": null,
"created_at": "2026-10-28T14:20:01+00:00"
}
],
"links": {
"panel": "https://app.leadgo.com.br/app/leads/01jbz2k8m4q0t6w2y8b4e0h6na"
}
}
}
}
}
},
"404": {
"description": "O recurso não existe nesta conta.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Token ausente, inválido, revogado ou vencido.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Limite de requisições.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
},
"patch": {
"operationId": "api.v1.leads.update",
"tags": [
"Leads"
],
"externalDocs": {
"url": "https://leadgo.com.br/docs/api/referencia/leads#leads-update"
},
"summary": "Mudar a etapa do lead",
"description": "Move o lead no funil, como no painel. A mudança entra no histórico, dispara o webhook lead.status_changed e, nos planos com inteligência de leads, manda a qualificação e a venda para a Meta (a Meta passa a buscar mais gente parecida com quem compra). Venda (won) pode levar o valor; perda (lost), o motivo.\n\nEscopo: `leads:write`.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "string",
"description": "new, contacted, qualified, won, lost ou spam."
},
"value_cents": {
"type": "integer",
"description": "Só com won: valor da venda em centavos (maior que zero)."
},
"lost_reason": {
"type": "string",
"description": "Só com lost: motivo (até 255 caracteres)."
}
},
"required": [
"status"
]
},
"example": {
"status": "won",
"value_cents": 25900
}
}
}
},
"responses": {
"200": {
"description": "Mudar a etapa do lead",
"content": {
"application/json": {
"example": {
"data": {
"id": "01jbz2k8m4q0t6w2y8b4e0h6na",
"platform_lead_id": "1234567890123456",
"name": "Mariana Lima",
"email": "mariana@exemplo.com.br",
"phone": "+5511987654321",
"answers": {
"Qual o melhor horário para contato?": "Depois das 18h",
"Qual produto você procura?": "Kit verão"
},
"status": "won",
"status_label": "Vendeu",
"value_cents": 25900,
"lost_reason": null,
"score": "hot",
"score_label": "Quente",
"score_reason": "Respondeu o produto e o horário; quer comprar já.",
"suggested_message": "Oi, Mariana! Vi que você procura o Kit verão. Posso te mandar as opções depois das 18h?",
"whatsapp_url": "https://wa.me/5511987654321?text=Oi%2C%20Mariana%21",
"campaign": {
"id": "01jby0q4c8m2d6t9v3k7w5r1xa",
"name": "Cadastro kit verão"
},
"ad_set": {
"id": 88,
"name": "Mulheres 25-45 SP"
},
"ad": {
"id": 140,
"name": "Anúncio 1"
},
"form_id": "987654321098765",
"received_at": "2026-10-28T14:20:00+00:00",
"first_contact_at": "2026-10-28T14:35:00+00:00",
"qualified_at": "2026-10-28T16:00:00+00:00",
"won_at": "2026-10-28T16:00:00+00:00",
"scored_at": "2026-10-28T14:20:09+00:00",
"events": [
{
"id": 902,
"type": "status_changed",
"label": "Status alterado",
"data": {
"from": "contacted",
"to": "won",
"value_cents": 25900
},
"user": {
"id": 42,
"name": "Ana Souza"
},
"created_at": "2026-10-28T16:00:00+00:00"
},
{
"id": 901,
"type": "scored",
"label": "Qualificado pela IA",
"data": {
"score": "hot"
},
"user": null,
"created_at": "2026-10-28T14:20:09+00:00"
},
{
"id": 900,
"type": "received",
"label": "Lead recebido",
"data": null,
"user": null,
"created_at": "2026-10-28T14:20:01+00:00"
}
],
"links": {
"panel": "https://app.leadgo.com.br/app/leads/01jbz2k8m4q0t6w2y8b4e0h6na"
}
}
}
}
}
},
"422": {
"description": "Campos inválidos; o detalhe de cada um vem em errors.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "O recurso não existe nesta conta.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Token ausente, inválido, revogado ou vencido.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Limite de requisições.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
},
"delete": {
"operationId": "api.v1.leads.destroy",
"tags": [
"Leads"
],
"externalDocs": {
"url": "https://leadgo.com.br/docs/api/referencia/leads#leads-destroy"
},
"summary": "Excluir lead (LGPD)",
"description": "Apaga de vez o lead e o histórico, para atender ao pedido do titular dos dados. Não apaga na Meta: os leads ficam lá por 90 dias, conforme a política deles.\n\nEscopo: `leads:write`.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"204": {
"description": "Excluir lead (LGPD)"
},
"404": {
"description": "O recurso não existe nesta conta.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Token ausente, inválido, revogado ou vencido.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Limite de requisições.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/leads/{id}/contacted": {
"post": {
"operationId": "api.v1.leads.contacted",
"tags": [
"Leads"
],
"externalDocs": {
"url": "https://leadgo.com.br/docs/api/referencia/leads#leads-contacted"
},
"summary": "Registrar contato",
"description": "O vendedor falou com o lead: grava o primeiro contato (que entra no tempo médio de resposta) e, se o lead ainda era new, passa para contacted.\n\nEscopo: `leads:write`.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Registrar contato",
"content": {
"application/json": {
"example": {
"data": {
"id": "01jbz2k8m4q0t6w2y8b4e0h6na",
"platform_lead_id": "1234567890123456",
"name": "Mariana Lima",
"email": "mariana@exemplo.com.br",
"phone": "+5511987654321",
"answers": {
"Qual o melhor horário para contato?": "Depois das 18h",
"Qual produto você procura?": "Kit verão"
},
"status": "contacted",
"status_label": "Contatado",
"value_cents": null,
"lost_reason": null,
"score": "hot",
"score_label": "Quente",
"score_reason": "Respondeu o produto e o horário; quer comprar já.",
"suggested_message": "Oi, Mariana! Vi que você procura o Kit verão. Posso te mandar as opções depois das 18h?",
"whatsapp_url": "https://wa.me/5511987654321?text=Oi%2C%20Mariana%21",
"campaign": {
"id": "01jby0q4c8m2d6t9v3k7w5r1xa",
"name": "Cadastro kit verão"
},
"ad_set": {
"id": 88,
"name": "Mulheres 25-45 SP"
},
"ad": {
"id": 140,
"name": "Anúncio 1"
},
"form_id": "987654321098765",
"received_at": "2026-10-28T14:20:00+00:00",
"first_contact_at": "2026-10-28T14:35:00+00:00",
"qualified_at": null,
"won_at": null,
"scored_at": "2026-10-28T14:20:09+00:00",
"links": {
"panel": "https://app.leadgo.com.br/app/leads/01jbz2k8m4q0t6w2y8b4e0h6na"
}
}
}
}
}
},
"404": {
"description": "O recurso não existe nesta conta.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Token ausente, inválido, revogado ou vencido.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Limite de requisições.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/leads/{id}/notes": {
"post": {
"operationId": "api.v1.leads.notes.store",
"tags": [
"Leads"
],
"externalDocs": {
"url": "https://leadgo.com.br/docs/api/referencia/leads#leads-notes-store"
},
"summary": "Adicionar nota",
"description": "Uma anotação no histórico do lead, em nome de quem criou o token.\n\nEscopo: `leads:write`.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"text": {
"type": "string",
"description": "Até 2000 caracteres."
}
},
"required": [
"text"
]
},
"example": {
"text": "Pediu orçamento do kit com 3 peças. Retornar na sexta."
}
}
}
},
"responses": {
"201": {
"description": "Adicionar nota",
"content": {
"application/json": {
"example": {
"data": {
"id": "01jbz2k8m4q0t6w2y8b4e0h6na",
"platform_lead_id": "1234567890123456",
"name": "Mariana Lima",
"email": "mariana@exemplo.com.br",
"phone": "+5511987654321",
"answers": {
"Qual o melhor horário para contato?": "Depois das 18h",
"Qual produto você procura?": "Kit verão"
},
"status": "contacted",
"status_label": "Contatado",
"value_cents": null,
"lost_reason": null,
"score": "hot",
"score_label": "Quente",
"score_reason": "Respondeu o produto e o horário; quer comprar já.",
"suggested_message": "Oi, Mariana! Vi que você procura o Kit verão. Posso te mandar as opções depois das 18h?",
"whatsapp_url": "https://wa.me/5511987654321?text=Oi%2C%20Mariana%21",
"campaign": {
"id": "01jby0q4c8m2d6t9v3k7w5r1xa",
"name": "Cadastro kit verão"
},
"ad_set": {
"id": 88,
"name": "Mulheres 25-45 SP"
},
"ad": {
"id": 140,
"name": "Anúncio 1"
},
"form_id": "987654321098765",
"received_at": "2026-10-28T14:20:00+00:00",
"first_contact_at": "2026-10-28T14:35:00+00:00",
"qualified_at": null,
"won_at": null,
"scored_at": "2026-10-28T14:20:09+00:00",
"events": [
{
"id": 902,
"type": "status_changed",
"label": "Status alterado",
"data": {
"from": "contacted",
"to": "won",
"value_cents": 25900
},
"user": {
"id": 42,
"name": "Ana Souza"
},
"created_at": "2026-10-28T16:00:00+00:00"
},
{
"id": 901,
"type": "scored",
"label": "Qualificado pela IA",
"data": {
"score": "hot"
},
"user": null,
"created_at": "2026-10-28T14:20:09+00:00"
},
{
"id": 900,
"type": "received",
"label": "Lead recebido",
"data": null,
"user": null,
"created_at": "2026-10-28T14:20:01+00:00"
}
],
"links": {
"panel": "https://app.leadgo.com.br/app/leads/01jbz2k8m4q0t6w2y8b4e0h6na"
}
}
}
}
}
},
"422": {
"description": "Campos inválidos; o detalhe de cada um vem em errors.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "O recurso não existe nesta conta.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Token ausente, inválido, revogado ou vencido.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Limite de requisições.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/brain/reports": {
"get": {
"operationId": "api.v1.brain.reports.index",
"tags": [
"Gestor IA"
],
"externalDocs": {
"url": "https://leadgo.com.br/docs/api/referencia/gestor-ia#brain-reports-index"
},
"summary": "Listar relatórios do Gestor IA",
"description": "Os relatórios da conta, do mais novo para o mais antigo: diários, checagens da tarde, análises pedidas e resumos semanais. pending_actions diz quantas ações esperam decisão. Pagine com cursor (meta.next_cursor).\n\nEscopo: `brain:read`.",
"parameters": [
{
"name": "limit",
"in": "query",
"required": false,
"description": "Itens por página, de 1 a 50 (padrão 15).",
"schema": {
"type": "integer"
}
},
{
"name": "cursor",
"in": "query",
"required": false,
"description": "meta.next_cursor da página anterior.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Listar relatórios do Gestor IA",
"content": {
"application/json": {
"example": {
"data": [
{
"id": "01jbz6a0c6f2j8m4q0t6w2y8b4",
"kind": "daily",
"kind_label": "Relatório diário",
"mode": "manual",
"status": "pending_review",
"status_label": "Aguardando aprovação",
"health": "good",
"health_label": "Saudável",
"report_date": "2026-10-28",
"period": {
"from": "2026-10-21",
"to": "2026-10-27"
},
"diagnosis": "A conta está saudável: o custo por compra caiu 12% na semana. A campanha Promoção de outubro tem espaço para crescer.",
"yesterday_summary": "Ontem: R$ 312,50 gastos, 24 compras a R$ 13,02 cada.",
"yesterday": {
"spend": 312.5,
"conversions": 24
},
"highlights": [
"CPA 12% abaixo da meta"
],
"error": null,
"can_decide": true,
"started_at": "2026-10-28T09:00:02+00:00",
"generated_at": "2026-10-28T09:01:40+00:00",
"expires_at": "2026-10-30T09:01:40+00:00",
"reviewed_at": null,
"created_at": "2026-10-28T09:00:00+00:00",
"links": {
"panel": "https://app.leadgo.com.br/app/brain/reports/01jbz6a0c6f2j8m4q0t6w2y8b4"
},
"pending_actions": 1
}
],
"meta": {
"per_page": 15,
"next_cursor": null,
"prev_cursor": null
}
}
}
}
},
"422": {
"description": "Campos inválidos; o detalhe de cada um vem em errors.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Token ausente, inválido, revogado ou vencido.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Limite de requisições.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
},
"post": {
"operationId": "api.v1.brain.reports.store",
"tags": [
"Gestor IA"
],
"externalDocs": {
"url": "https://leadgo.com.br/docs/api/referencia/gestor-ia#brain-reports-store"
},
"summary": "Pedir uma análise agora",
"description": "O \"Analisar agora\" do painel: abre o relatório (status generating) e a IA analisa a conta pela fila em 1 a 3 minutos. Uma por conta por hora (a que falhou não conta). Responde 202 com Location; acompanhe pelo GET ou pelo webhook brain.report_ready.\n\nEscopo: `brain:manage`.",
"responses": {
"202": {
"description": "Pedir uma análise agora",
"content": {
"application/json": {
"example": {
"data": {
"id": "01jbz6a0c6f2j8m4q0t6w2y8b4",
"kind": "manual",
"kind_label": "Análise pedida",
"mode": "manual",
"status": "generating",
"status_label": "Analisando",
"health": null,
"health_label": null,
"report_date": "2026-10-28",
"period": {
"from": "2026-10-21",
"to": "2026-10-27"
},
"diagnosis": null,
"yesterday_summary": null,
"yesterday": null,
"highlights": null,
"error": null,
"can_decide": false,
"started_at": "2026-10-28T09:00:02+00:00",
"generated_at": null,
"expires_at": null,
"reviewed_at": null,
"created_at": "2026-10-28T09:00:00+00:00",
"links": {
"panel": "https://app.leadgo.com.br/app/brain/reports/01jbz6a0c6f2j8m4q0t6w2y8b4"
}
}
}
}
}
},
"409": {
"description": "A conta ainda não vinculou uma conta de anúncio da Meta.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Já houve uma análise pedida nesta conta na última hora.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Token ausente, inválido, revogado ou vencido.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/brain/reports/{id}": {
"get": {
"operationId": "api.v1.brain.reports.show",
"tags": [
"Gestor IA"
],
"externalDocs": {
"url": "https://leadgo.com.br/docs/api/referencia/gestor-ia#brain-reports-show"
},
"summary": "Consultar relatório",
"description": "Um relatório com o diagnóstico e as ações. Em actions, kind action se aprova ou recusa (pausar, ativar, mudar verba, realocar); kind suggestion é só para ler (campanha nova, trocar criativo, corrigir rastreamento, esperar). As duas metades de uma realocação têm o mesmo group_key e seguem juntas. Enquanto status for generating, consulte de novo (ou espere o webhook brain.report_ready).\n\nEscopo: `brain:read`.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Consultar relatório",
"content": {
"application/json": {
"example": {
"data": {
"id": "01jbz6a0c6f2j8m4q0t6w2y8b4",
"kind": "daily",
"kind_label": "Relatório diário",
"mode": "manual",
"status": "pending_review",
"status_label": "Aguardando aprovação",
"health": "good",
"health_label": "Saudável",
"report_date": "2026-10-28",
"period": {
"from": "2026-10-21",
"to": "2026-10-27"
},
"diagnosis": "A conta está saudável: o custo por compra caiu 12% na semana. A campanha Promoção de outubro tem espaço para crescer.",
"yesterday_summary": "Ontem: R$ 312,50 gastos, 24 compras a R$ 13,02 cada.",
"yesterday": {
"spend": 312.5,
"conversions": 24
},
"highlights": [
"CPA 12% abaixo da meta"
],
"error": null,
"can_decide": true,
"started_at": "2026-10-28T09:00:02+00:00",
"generated_at": "2026-10-28T09:01:40+00:00",
"expires_at": "2026-10-30T09:01:40+00:00",
"reviewed_at": null,
"created_at": "2026-10-28T09:00:00+00:00",
"links": {
"panel": "https://app.leadgo.com.br/app/brain/reports/01jbz6a0c6f2j8m4q0t6w2y8b4"
},
"can_retry": false,
"actions": [
{
"id": "01jbz6c2e8h4k0n6q2t8w4z0b6",
"report_id": "01jbz6a0c6f2j8m4q0t6w2y8b4",
"type": "update_campaign_budget",
"type_label": "Mudar orçamento da campanha",
"kind": "action",
"summary": "Mudar orçamento da campanha · Promoção de outubro: R$ 50,00 → R$ 65,00",
"status": "proposed",
"status_label": "Aguardando decisão",
"target": {
"type": "campaign",
"id": "01jby0q4c8m2d6t9v3k7w5r1xa",
"name": "Promoção de outubro"
},
"campaign_id": "01jby0q4c8m2d6t9v3k7w5r1xa",
"params": {
"budget_cents": 6500
},
"before": {
"budget_cents": 5000
},
"after": null,
"reason": "CPA 22% abaixo da meta nos últimos 7 dias, com verba se esgotando antes das 18h.",
"expected_impact": "+25% de conversões mantendo o CPA.",
"confidence": "high",
"priority": 1,
"is_emergency": false,
"guard_notes": null,
"group_key": null,
"can_decide": true,
"can_rollback": false,
"rollback_blocker": "Só ações aplicadas podem ser desfeitas.",
"decided_at": null,
"executor": null,
"executed_at": null,
"error": null,
"rolled_back_at": null,
"evaluation": null
}
]
}
}
}
}
},
"404": {
"description": "O recurso não existe nesta conta.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Token ausente, inválido, revogado ou vencido.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Limite de requisições.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/brain/reports/{id}/retry": {
"post": {
"operationId": "api.v1.brain.reports.retry",
"tags": [
"Gestor IA"
],
"externalDocs": {
"url": "https://leadgo.com.br/docs/api/referencia/gestor-ia#brain-reports-retry"
},
"summary": "Refazer análise que falhou",
"description": "Refaz a análise de um relatório com status failed (só a mais recente da conta; can_retry diz se dá). Abre um relatório novo e responde 202.\n\nEscopo: `brain:manage`.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"202": {
"description": "Refazer análise que falhou",
"content": {
"application/json": {
"example": {
"data": {
"id": "01jbz6a0c6f2j8m4q0t6w2y8b4",
"kind": "daily",
"kind_label": "Relatório diário",
"mode": "manual",
"status": "generating",
"status_label": "Analisando",
"health": "good",
"health_label": "Saudável",
"report_date": "2026-10-28",
"period": {
"from": "2026-10-21",
"to": "2026-10-27"
},
"diagnosis": "A conta está saudável: o custo por compra caiu 12% na semana. A campanha Promoção de outubro tem espaço para crescer.",
"yesterday_summary": "Ontem: R$ 312,50 gastos, 24 compras a R$ 13,02 cada.",
"yesterday": {
"spend": 312.5,
"conversions": 24
},
"highlights": [
"CPA 12% abaixo da meta"
],
"error": null,
"can_decide": true,
"started_at": "2026-10-28T09:00:02+00:00",
"generated_at": "2026-10-28T09:01:40+00:00",
"expires_at": "2026-10-30T09:01:40+00:00",
"reviewed_at": null,
"created_at": "2026-10-28T09:00:00+00:00",
"links": {
"panel": "https://app.leadgo.com.br/app/brain/reports/01jbz6a0c6f2j8m4q0t6w2y8b4"
}
}
}
}
}
},
"404": {
"description": "O recurso não existe nesta conta.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "Só a análise mais recente da conta, quando falhou, pode ser refeita.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Token ausente, inválido, revogado ou vencido.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Limite de requisições.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/brain/reports/{id}/approve": {
"post": {
"operationId": "api.v1.brain.reports.approve",
"tags": [
"Gestor IA"
],
"externalDocs": {
"url": "https://leadgo.com.br/docs/api/referencia/gestor-ia#brain-reports-approve"
},
"summary": "Aprovar todas as ações",
"description": "Aprova as ações ainda pendentes do relatório e manda aplicar na Meta pela fila (as já decididas ficam como estão). O relatório espera decisão por 48 horas; depois, expira.\n\nEscopo: `brain:manage`.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Aprovar todas as ações",
"content": {
"application/json": {
"example": {
"data": {
"id": "01jbz6a0c6f2j8m4q0t6w2y8b4",
"kind": "daily",
"kind_label": "Relatório diário",
"mode": "manual",
"status": "approved",
"status_label": "Aprovado",
"health": "good",
"health_label": "Saudável",
"report_date": "2026-10-28",
"period": {
"from": "2026-10-21",
"to": "2026-10-27"
},
"diagnosis": "A conta está saudável: o custo por compra caiu 12% na semana. A campanha Promoção de outubro tem espaço para crescer.",
"yesterday_summary": "Ontem: R$ 312,50 gastos, 24 compras a R$ 13,02 cada.",
"yesterday": {
"spend": 312.5,
"conversions": 24
},
"highlights": [
"CPA 12% abaixo da meta"
],
"error": null,
"can_decide": false,
"started_at": "2026-10-28T09:00:02+00:00",
"generated_at": "2026-10-28T09:01:40+00:00",
"expires_at": "2026-10-30T09:01:40+00:00",
"reviewed_at": null,
"created_at": "2026-10-28T09:00:00+00:00",
"links": {
"panel": "https://app.leadgo.com.br/app/brain/reports/01jbz6a0c6f2j8m4q0t6w2y8b4"
},
"can_retry": false,
"actions": [
{
"id": "01jbz6c2e8h4k0n6q2t8w4z0b6",
"report_id": "01jbz6a0c6f2j8m4q0t6w2y8b4",
"type": "update_campaign_budget",
"type_label": "Mudar orçamento da campanha",
"kind": "action",
"summary": "Mudar orçamento da campanha · Promoção de outubro: R$ 50,00 → R$ 65,00",
"status": "queued",
"status_label": "Na fila",
"target": {
"type": "campaign",
"id": "01jby0q4c8m2d6t9v3k7w5r1xa",
"name": "Promoção de outubro"
},
"campaign_id": "01jby0q4c8m2d6t9v3k7w5r1xa",
"params": {
"budget_cents": 6500
},
"before": {
"budget_cents": 5000
},
"after": null,
"reason": "CPA 22% abaixo da meta nos últimos 7 dias, com verba se esgotando antes das 18h.",
"expected_impact": "+25% de conversões mantendo o CPA.",
"confidence": "high",
"priority": 1,
"is_emergency": false,
"guard_notes": null,
"group_key": null,
"can_decide": false,
"can_rollback": false,
"rollback_blocker": "Só ações aplicadas podem ser desfeitas.",
"decided_at": null,
"executor": null,
"executed_at": null,
"error": null,
"rolled_back_at": null,
"evaluation": null
}
]
}
}
}
}
},
"404": {
"description": "O recurso não existe nesta conta.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "O relatório não aceita mais decisões (já decidido, expirado ou substituído).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Token ausente, inválido, revogado ou vencido.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Limite de requisições.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/brain/reports/{id}/reject": {
"post": {
"operationId": "api.v1.brain.reports.reject",
"tags": [
"Gestor IA"
],
"externalDocs": {
"url": "https://leadgo.com.br/docs/api/referencia/gestor-ia#brain-reports-reject"
},
"summary": "Recusar todas as ações",
"description": "Recusa as ações ainda pendentes do relatório. Nada muda na Meta.\n\nEscopo: `brain:manage`.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Recusar todas as ações",
"content": {
"application/json": {
"example": {
"data": {
"id": "01jbz6a0c6f2j8m4q0t6w2y8b4",
"kind": "daily",
"kind_label": "Relatório diário",
"mode": "manual",
"status": "rejected",
"status_label": "Recusado",
"health": "good",
"health_label": "Saudável",
"report_date": "2026-10-28",
"period": {
"from": "2026-10-21",
"to": "2026-10-27"
},
"diagnosis": "A conta está saudável: o custo por compra caiu 12% na semana. A campanha Promoção de outubro tem espaço para crescer.",
"yesterday_summary": "Ontem: R$ 312,50 gastos, 24 compras a R$ 13,02 cada.",
"yesterday": {
"spend": 312.5,
"conversions": 24
},
"highlights": [
"CPA 12% abaixo da meta"
],
"error": null,
"can_decide": false,
"started_at": "2026-10-28T09:00:02+00:00",
"generated_at": "2026-10-28T09:01:40+00:00",
"expires_at": "2026-10-30T09:01:40+00:00",
"reviewed_at": null,
"created_at": "2026-10-28T09:00:00+00:00",
"links": {
"panel": "https://app.leadgo.com.br/app/brain/reports/01jbz6a0c6f2j8m4q0t6w2y8b4"
},
"can_retry": false,
"actions": [
{
"id": "01jbz6c2e8h4k0n6q2t8w4z0b6",
"report_id": "01jbz6a0c6f2j8m4q0t6w2y8b4",
"type": "update_campaign_budget",
"type_label": "Mudar orçamento da campanha",
"kind": "action",
"summary": "Mudar orçamento da campanha · Promoção de outubro: R$ 50,00 → R$ 65,00",
"status": "rejected",
"status_label": "Recusada",
"target": {
"type": "campaign",
"id": "01jby0q4c8m2d6t9v3k7w5r1xa",
"name": "Promoção de outubro"
},
"campaign_id": "01jby0q4c8m2d6t9v3k7w5r1xa",
"params": {
"budget_cents": 6500
},
"before": {
"budget_cents": 5000
},
"after": null,
"reason": "CPA 22% abaixo da meta nos últimos 7 dias, com verba se esgotando antes das 18h.",
"expected_impact": "+25% de conversões mantendo o CPA.",
"confidence": "high",
"priority": 1,
"is_emergency": false,
"guard_notes": null,
"group_key": null,
"can_decide": false,
"can_rollback": false,
"rollback_blocker": "Só ações aplicadas podem ser desfeitas.",
"decided_at": null,
"executor": null,
"executed_at": null,
"error": null,
"rolled_back_at": null,
"evaluation": null
}
]
}
}
}
}
},
"404": {
"description": "O recurso não existe nesta conta.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "O relatório não aceita mais decisões (já decidido, expirado ou substituído).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Token ausente, inválido, revogado ou vencido.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Limite de requisições.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/brain/actions/{id}/approve": {
"post": {
"operationId": "api.v1.brain.actions.approve",
"tags": [
"Gestor IA"
],
"externalDocs": {
"url": "https://leadgo.com.br/docs/api/referencia/gestor-ia#brain-actions-approve"
},
"summary": "Aprovar uma ação",
"description": "Aprova a ação e manda aplicar na Meta pela fila. Numa realocação, a aplicação só sai quando as duas metades (mesmo group_key) estão aprovadas.\n\nEscopo: `brain:manage`.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Aprovar uma ação",
"content": {
"application/json": {
"example": {
"data": {
"id": "01jbz6c2e8h4k0n6q2t8w4z0b6",
"report_id": "01jbz6a0c6f2j8m4q0t6w2y8b4",
"type": "update_campaign_budget",
"type_label": "Mudar orçamento da campanha",
"kind": "action",
"summary": "Mudar orçamento da campanha · Promoção de outubro: R$ 50,00 → R$ 65,00",
"status": "queued",
"status_label": "Na fila",
"target": {
"type": "campaign",
"id": "01jby0q4c8m2d6t9v3k7w5r1xa",
"name": "Promoção de outubro"
},
"campaign_id": "01jby0q4c8m2d6t9v3k7w5r1xa",
"params": {
"budget_cents": 6500
},
"before": {
"budget_cents": 5000
},
"after": null,
"reason": "CPA 22% abaixo da meta nos últimos 7 dias, com verba se esgotando antes das 18h.",
"expected_impact": "+25% de conversões mantendo o CPA.",
"confidence": "high",
"priority": 1,
"is_emergency": false,
"guard_notes": null,
"group_key": null,
"can_decide": false,
"can_rollback": false,
"rollback_blocker": "Só ações aplicadas podem ser desfeitas.",
"decided_at": "2026-10-28T10:15:00+00:00",
"executor": "user",
"executed_at": null,
"error": null,
"rolled_back_at": null,
"evaluation": null
}
}
}
}
},
"404": {
"description": "O recurso não existe nesta conta.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "A ação já foi decidida ou é só uma sugestão.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Token ausente, inválido, revogado ou vencido.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Limite de requisições.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/brain/actions/{id}/reject": {
"post": {
"operationId": "api.v1.brain.actions.reject",
"tags": [
"Gestor IA"
],
"externalDocs": {
"url": "https://leadgo.com.br/docs/api/referencia/gestor-ia#brain-actions-reject"
},
"summary": "Recusar uma ação",
"description": "Recusa a ação; numa realocação, a outra metade é recusada junto.\n\nEscopo: `brain:manage`.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Recusar uma ação",
"content": {
"application/json": {
"example": {
"data": {
"id": "01jbz6c2e8h4k0n6q2t8w4z0b6",
"report_id": "01jbz6a0c6f2j8m4q0t6w2y8b4",
"type": "update_campaign_budget",
"type_label": "Mudar orçamento da campanha",
"kind": "action",
"summary": "Mudar orçamento da campanha · Promoção de outubro: R$ 50,00 → R$ 65,00",
"status": "rejected",
"status_label": "Recusada",
"target": {
"type": "campaign",
"id": "01jby0q4c8m2d6t9v3k7w5r1xa",
"name": "Promoção de outubro"
},
"campaign_id": "01jby0q4c8m2d6t9v3k7w5r1xa",
"params": {
"budget_cents": 6500
},
"before": {
"budget_cents": 5000
},
"after": null,
"reason": "CPA 22% abaixo da meta nos últimos 7 dias, com verba se esgotando antes das 18h.",
"expected_impact": "+25% de conversões mantendo o CPA.",
"confidence": "high",
"priority": 1,
"is_emergency": false,
"guard_notes": null,
"group_key": null,
"can_decide": false,
"can_rollback": false,
"rollback_blocker": "Só ações aplicadas podem ser desfeitas.",
"decided_at": "2026-10-28T10:15:00+00:00",
"executor": null,
"executed_at": null,
"error": null,
"rolled_back_at": null,
"evaluation": null
}
}
}
}
},
"404": {
"description": "O recurso não existe nesta conta.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "A ação já foi decidida ou é só uma sugestão.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Token ausente, inválido, revogado ou vencido.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Limite de requisições.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/brain/actions/{id}/rollback": {
"post": {
"operationId": "api.v1.brain.actions.rollback",
"tags": [
"Gestor IA"
],
"externalDocs": {
"url": "https://leadgo.com.br/docs/api/referencia/gestor-ia#brain-actions-rollback"
},
"summary": "Desfazer uma ação aplicada",
"description": "Volta ao estado anterior (verba ou status) uma ação aplicada há menos de 24 horas, se ninguém mexeu no alvo depois. can_rollback e rollback_blocker dizem se dá e por quê.\n\nEscopo: `brain:manage`.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Desfazer uma ação aplicada",
"content": {
"application/json": {
"example": {
"data": {
"id": "01jbz6c2e8h4k0n6q2t8w4z0b6",
"report_id": "01jbz6a0c6f2j8m4q0t6w2y8b4",
"type": "update_campaign_budget",
"type_label": "Mudar orçamento da campanha",
"kind": "action",
"summary": "Mudar orçamento da campanha · Promoção de outubro: R$ 50,00 → R$ 65,00",
"status": "executed",
"status_label": "Aplicada",
"target": {
"type": "campaign",
"id": "01jby0q4c8m2d6t9v3k7w5r1xa",
"name": "Promoção de outubro"
},
"campaign_id": "01jby0q4c8m2d6t9v3k7w5r1xa",
"params": {
"budget_cents": 6500
},
"before": {
"budget_cents": 5000
},
"after": null,
"reason": "CPA 22% abaixo da meta nos últimos 7 dias, com verba se esgotando antes das 18h.",
"expected_impact": "+25% de conversões mantendo o CPA.",
"confidence": "high",
"priority": 1,
"is_emergency": false,
"guard_notes": null,
"group_key": null,
"can_decide": false,
"can_rollback": false,
"rollback_blocker": "Esta ação já foi desfeita.",
"decided_at": null,
"executor": null,
"executed_at": null,
"error": null,
"rolled_back_at": "2026-10-28T12:00:00+00:00",
"evaluation": null
}
}
}
}
},
"404": {
"description": "O recurso não existe nesta conta.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "A ação não pode ser desfeita; o motivo vem em message.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"422": {
"description": "Uma regra do painel impediu a operação; o motivo vem em message.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Token ausente, inválido, revogado ou vencido.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Limite de requisições.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/campaign-briefs": {
"post": {
"operationId": "api.v1.campaign-briefs.store",
"tags": [
"Rascunho pela IA"
],
"externalDocs": {
"url": "https://leadgo.com.br/docs/api/referencia/ia#campaign-briefs-store"
},
"summary": "Montar campanha com a IA",
"description": "O mesmo \"Criar com a IA\" do painel: a partir do objetivo, da verba, da região, do link, da descrição livre e das mídias, a IA escreve nome, público, interesses e a copy de cada anúncio. Nada é publicado: a resposta traz data.campaign, pronto para revisar e enviar em POST /campaigns. Leva até ~2 minutos (configure o timeout do seu cliente para 180 s). Limite de 15 por hora por pessoa, somado ao painel.\n\nEscopo: `ai:draft`.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"objective": {
"type": "string",
"description": "sales, leads, lead_form, traffic, awareness, whatsapp."
},
"description": {
"type": "string",
"description": "O que é anunciado, para quem e o diferencial (10 a 2000 caracteres)."
},
"budget": {
"type": "object",
"properties": {
"amount_cents": {
"type": "integer",
"description": "Verba diária em centavos."
}
}
},
"link_url": {
"type": "string",
"description": "Obrigatório nos objetivos com link (sales, leads, traffic, awareness)."
},
"media_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Mídias prontas (1 a 10); a IA escreve uma copy para cada."
},
"persona_id": {
"type": "integer",
"description": "Com persona, o público é o dela e a IA escreve para ela."
},
"targeting": {
"type": "object",
"properties": {
"countries": {
"type": "array",
"items": {
"type": "string"
},
"description": "Países (padrão BR)."
},
"cities": {
"type": "array",
"items": {
"type": "object"
},
"description": "Cidades (de GET /targeting/cities)."
}
}
},
"tracking": {
"type": "object",
"properties": {
"pixel_id": {
"type": "string",
"description": "Pixel, nos objetivos sales e leads (sem ele, o padrão da conta)."
}
}
},
"whatsapp": {
"type": "object",
"properties": {
"phone_number": {
"type": "string",
"description": "Número do WhatsApp (E.164), no objetivo whatsapp."
}
}
},
"lead_form": {
"type": "object",
"properties": {
"privacy_policy_url": {
"type": "string",
"description": "Política de privacidade, no objetivo lead_form (sem ela, a de Leads › Configurações)."
}
}
}
},
"required": [
"objective",
"description",
"budget",
"media_ids"
]
},
"example": {
"objective": "sales",
"description": "Loja de suplementos para mulheres que treinam. Whey e creatina com 30% off e frete grátis acima de R$ 199.",
"budget": {
"amount_cents": 5000
},
"link_url": "https://loja.exemplo.com.br/suplementos",
"media_ids": [
"01jbx3m7k2q8f5v9w4n6c0r1ht"
]
}
}
}
},
"responses": {
"200": {
"description": "Montar campanha com a IA",
"content": {
"application/json": {
"example": {
"data": {
"campaign": {
"name": "Vendas | Suplementos | Outubro",
"goal": "conversions",
"status": "paused",
"budget": {
"type": "daily",
"amount_cents": 5000
},
"tracking": {
"conversion_event": "PURCHASE"
},
"targeting": {
"countries": [
"BR"
],
"age_min": 25,
"age_max": 45,
"gender": "female",
"interests": [
{
"id": "6003107902433",
"name": "Fitness"
}
]
},
"link_url": "https://loja.exemplo.com.br/suplementos",
"creatives": [
{
"media_id": "01jbx3m7k2q8f5v9w4n6c0r1ht",
"headline": "Whey com 30% off",
"body": "Treine melhor com o whey que cabe no bolso.",
"description": "Frete grátis",
"call_to_action": "SHOP_NOW"
}
]
},
"rationale": "Público feminino fitness com interesse em suplementos.",
"unresolved_interests": []
}
}
}
}
},
"422": {
"description": "Campos inválidos; o detalhe de cada um vem em errors.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Limite de rascunhos pela IA por hora (somado ao painel).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "A IA não respondeu; tente de novo em instantes.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "A conta ainda não vinculou uma conta de anúncio da Meta.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Token ausente, inválido, revogado ou vencido.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/webhooks": {
"get": {
"operationId": "api.v1.webhooks.index",
"tags": [
"Webhooks"
],
"externalDocs": {
"url": "https://leadgo.com.br/docs/api/referencia/webhooks#webhooks-index"
},
"summary": "Listar webhooks",
"description": "Webhooks da conta (até 5). O segredo não aparece aqui.\n\nEscopo: `webhooks:manage`.",
"responses": {
"200": {
"description": "Listar webhooks",
"content": {
"application/json": {
"example": {
"data": [
{
"id": "01jbz8e2h6k0n4r8u2x6b0f4jm",
"url": "https://erp.loja.exemplo.com.br/hooks/leadgo",
"description": "ERP",
"events": [
"campaign.published",
"campaign.failed",
"campaign.status_changed"
],
"is_active": true,
"failure_count": 0,
"last_error": null,
"last_delivered_at": "2026-10-28T15:10:00+00:00",
"created_at": "2026-10-28T15:00:00+00:00"
}
]
}
}
}
},
"401": {
"description": "Token ausente, inválido, revogado ou vencido.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Limite de requisições.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
},
"post": {
"operationId": "api.v1.webhooks.store",
"tags": [
"Webhooks"
],
"externalDocs": {
"url": "https://leadgo.com.br/docs/api/referencia/webhooks#webhooks-store"
},
"summary": "Criar webhook",
"description": "A URL https pública que recebe os avisos. O segredo para conferir a assinatura vem só nesta resposta (secret). Sem events, assina todos.\n\nEscopo: `webhooks:manage`.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "URL https pública (sem redirecionamento)."
},
"description": {
"type": "string",
"description": "Para reconhecer na lista."
},
"events": {
"type": "array",
"items": {
"type": "string"
},
"description": "campaign.published, campaign.failed, campaign.status_changed, campaign.deleted, ad.approved, ad.rejected, alert.created, ad_account.status_changed, lead.created, lead.status_changed, lead.scored, brain.report_ready, media.ready, media.failed. Sem o campo, todos os que quem criou o token pode assinar: os lead.* pedem a permissão de ver leads e o brain.report_ready a de ver o Gestor IA."
}
},
"required": [
"url"
]
},
"example": {
"url": "https://erp.loja.exemplo.com.br/hooks/leadgo",
"description": "ERP",
"events": [
"campaign.published",
"campaign.failed",
"campaign.status_changed"
]
}
}
}
},
"responses": {
"201": {
"description": "Criar webhook",
"content": {
"application/json": {
"example": {
"data": {
"id": "01jbz8e2h6k0n4r8u2x6b0f4jm",
"url": "https://erp.loja.exemplo.com.br/hooks/leadgo",
"description": "ERP",
"events": [
"campaign.published",
"campaign.failed",
"campaign.status_changed"
],
"is_active": true,
"failure_count": 0,
"last_error": null,
"last_delivered_at": null,
"created_at": "2026-10-28T15:00:00+00:00",
"secret": "whsec_8hJ2kL9mN3pQ5rS7tV1wX4yZ6aB0cD2eF4gH6jK8"
}
}
}
}
},
"422": {
"description": "Campos inválidos; o detalhe de cada um vem em errors.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Token ausente, inválido, revogado ou vencido.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Limite de requisições.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/webhooks/{id}": {
"get": {
"operationId": "api.v1.webhooks.show",
"tags": [
"Webhooks"
],
"externalDocs": {
"url": "https://leadgo.com.br/docs/api/referencia/webhooks#webhooks-show"
},
"summary": "Consultar webhook",
"description": "Um webhook, com a última entrega e o último erro.\n\nEscopo: `webhooks:manage`.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Consultar webhook",
"content": {
"application/json": {
"example": {
"data": {
"id": "01jbz8e2h6k0n4r8u2x6b0f4jm",
"url": "https://erp.loja.exemplo.com.br/hooks/leadgo",
"description": "ERP",
"events": [
"campaign.published",
"campaign.failed",
"campaign.status_changed"
],
"is_active": true,
"failure_count": 0,
"last_error": null,
"last_delivered_at": "2026-10-28T15:10:00+00:00",
"created_at": "2026-10-28T15:00:00+00:00"
}
}
}
}
},
"404": {
"description": "O recurso não existe nesta conta.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Token ausente, inválido, revogado ou vencido.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Limite de requisições.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
},
"patch": {
"operationId": "api.v1.webhooks.update",
"tags": [
"Webhooks"
],
"externalDocs": {
"url": "https://leadgo.com.br/docs/api/referencia/webhooks#webhooks-update"
},
"summary": "Alterar webhook",
"description": "URL, eventos, ligar/desligar (is_active) e troca do segredo (rotate_secret: o novo vem só nesta resposta). Religar zera a contagem de falhas.\n\nEscopo: `webhooks:manage`.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "Nova URL."
},
"description": {
"type": "string",
"description": "Nova descrição."
},
"events": {
"type": "array",
"items": {
"type": "string"
},
"description": "Eventos assinados."
},
"is_active": {
"type": "boolean",
"description": "Liga ou desliga os avisos."
},
"rotate_secret": {
"type": "boolean",
"description": "Gera um segredo novo."
}
}
},
"example": {
"is_active": true,
"rotate_secret": true
}
}
}
},
"responses": {
"200": {
"description": "Alterar webhook",
"content": {
"application/json": {
"example": {
"data": {
"id": "01jbz8e2h6k0n4r8u2x6b0f4jm",
"url": "https://erp.loja.exemplo.com.br/hooks/leadgo",
"description": "ERP",
"events": [
"campaign.published",
"campaign.failed",
"campaign.status_changed"
],
"is_active": true,
"failure_count": 0,
"last_error": null,
"last_delivered_at": "2026-10-28T15:10:00+00:00",
"created_at": "2026-10-28T15:00:00+00:00",
"secret": "whsec_3nM5pQ7rS9tV1wX3yZ5aB7cD9eF1gH3jK5mN7pQ9"
}
}
}
}
},
"422": {
"description": "Campos inválidos; o detalhe de cada um vem em errors.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "O recurso não existe nesta conta.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Token ausente, inválido, revogado ou vencido.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Limite de requisições.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
},
"delete": {
"operationId": "api.v1.webhooks.destroy",
"tags": [
"Webhooks"
],
"externalDocs": {
"url": "https://leadgo.com.br/docs/api/referencia/webhooks#webhooks-destroy"
},
"summary": "Excluir webhook",
"description": "Os avisos para esta URL param na hora.\n\nEscopo: `webhooks:manage`.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"204": {
"description": "Excluir webhook"
},
"404": {
"description": "O recurso não existe nesta conta.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Token ausente, inválido, revogado ou vencido.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Limite de requisições.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/webhooks/{id}/test": {
"post": {
"operationId": "api.v1.webhooks.test",
"tags": [
"Webhooks"
],
"externalDocs": {
"url": "https://leadgo.com.br/docs/api/referencia/webhooks#webhooks-test"
},
"summary": "Testar webhook",
"description": "Envia agora um aviso webhook.test, assinado, e diz o que a URL respondeu. Não conta para desligar o webhook.\n\nEscopo: `webhooks:manage`.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Testar webhook",
"content": {
"application/json": {
"example": {
"data": {
"delivered": true,
"status": 200,
"error": null,
"event_id": "evt_01jbz9a1c5f9j3m7q1t5x9b3e7"
}
}
}
}
},
"404": {
"description": "O recurso não existe nesta conta.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Token ausente, inválido, revogado ou vencido.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Limite de requisições.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
}
},
"components": {
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer",
"description": "Token da conta (lgo_...), criado no painel em API."
}
},
"schemas": {
"Error": {
"type": "object",
"required": [
"message",
"code",
"request_id"
],
"properties": {
"message": {
"type": "string"
},
"code": {
"type": "string",
"enum": [
"token_invalid",
"token_revoked",
"token_expired",
"tenant_suspended",
"subscription_inactive",
"payment_overdue",
"token_owner_lost_access",
"missing_ability",
"permission_denied",
"not_found",
"validation_failed",
"rate_limited",
"platform_quota_exceeded",
"ad_account_not_linked",
"campaign_not_published",
"campaign_not_toggleable",
"not_toggleable",
"ad_not_published",
"ad_media_not_supported",
"boost_creative_locked",
"preview_unavailable",
"campaign_publishing",
"campaign_not_duplicable",
"ad_account_changed",
"too_many_publishing",
"campaign_creation_limit",
"idempotency_key_invalid",
"idempotency_key_reused",
"idempotency_in_progress",
"media_rejected",
"too_many_imports",
"sync_too_soon",
"campaign_not_templatable",
"brain_disabled",
"analysis_in_progress",
"analysis_too_soon",
"report_not_retryable",
"report_not_decidable",
"action_not_decidable",
"rollback_unavailable",
"audience_not_deletable",
"ai_rate_limited",
"ai_unavailable",
"webhook_limit_reached",
"operation_failed",
"platform_rejected",
"platform_unavailable",
"platform_rate_limited",
"server_error"
]
},
"errors": {
"type": "object",
"additionalProperties": {
"type": "array",
"items": {
"type": "string"
}
}
},
"details": {
"type": "object"
},
"request_id": {
"type": "string"
}
}
}
}
}
}