Visão Geral

A API do Facebook Ads do V4MOS.AI permite que você acesse e gerencie dados de contas, campanhas, conjuntos de anúncios, anúncios e dimensões como plataformas, regiões, demografia e configurações.

Endpoints DisponíveisCopiar link da seção

• getContas/v1/facebook/accountsRetorna dados de contas do Facebook Ads, incluindo status da conta, saldo, informações de investimento e detalhes de configuração.
• getCampanhas/v1/facebook/ads/campaignsRetorna dados de campanhas do Facebook Ads com métricas de desempenho abrangentes.
• getConjuntos de anúncios/v1/facebook/ads/adsetRetorna dados de conjuntos de anúncios do Facebook Ads com métricas de desempenho detalhadas.
• getAnúncios/v1/facebook/adsRetorna dados do Facebook Ads com métricas de desempenho abrangentes agregadas em nível de anúncio.
• getAnúncios/v1/facebook/ads/adRetorna métricas detalhadas de desempenho em nível de anúncio do Facebook, com indicadores avançados de qualidade e ranking.
• getAções/v1/facebook/ads/actionsRetorna dados de ações do Facebook Ads com métricas detalhadas de conversão e engajamento.
• getDados demográficos/v1/facebook/ads/demographicRetorna dados demográficos do Facebook Ads com métricas de desempenho detalhadas, segmentadas por idade e gênero.
• getPlataformas/v1/facebook/ads/platformRetorna dados de plataformas do Facebook Ads com métricas de desempenho segmentadas por plataforma de publicação e posição do anúncio.
• getRegiões/v1/facebook/ads/regionRetorna dados de regiões do Facebook Ads com métricas de desempenho segmentadas por localização geográfica.
• getCriativos/v1/facebook/creativesRetorna dados de criativos do Facebook Ads, incluindo configurações de criativos, ativos de mídia e metadados em nível de criativo.
• getConfiguração de conjuntos de anúncios/v1/facebook/ads/adset-configRetorna dados de configuração de conjuntos de anúncios do Facebook Ads, incluindo configurações de segmentação, de orçamento e demais…
• getConfiguração de anúncios/v1/facebook/ads/ad-configRetorna dados de configuração do Facebook Ads em nível de anúncio, incluindo ajustes do anúncio, configurações de orçamento e metadados em…
• getConfiguração de campanhas/v1/facebook/ads/campaigns-configRetorna dados de configuração de campanhas do Facebook Ads, incluindo ajustes da campanha, objetivo, configurações de orçamento e…
• getCriativos de anúncios/v1/facebook/ads/creativesRetorna dados de criativos do Facebook Ads agrupados por anúncio, com informações abrangentes sobre o criativo e sua associação ao anúncio.

Estrutura HierárquicaCopiar link da seção

O Facebook Ads segue uma estrutura hierárquica:

Campanha (Campaign)
├── Conjunto de Anúncios (Ad Set)
│   ├── Anúncio (Ad)
│   ├── Anúncio (Ad)
│   └── Anúncio (Ad)
└── Conjunto de Anúncios (Ad Set)
    ├── Anúncio (Ad)
    └── Anúncio (Ad)

AutenticaçãoCopiar link da seção

Todos os endpoints exigem os headers x-client-id e x-client-secret, além do query parameter organizationId. Veja Autenticação.

Parâmetros ComunsCopiar link da seção

• organizationId - ID da organização (obrigatório)
• userId - ID do usuário
• page - Número da página (padrão: 1)
• limit - Limite por página (padrão: 500, máximo: 5000)
• orderBy - Campo para ordenação
• orderDirection - Direção da ordenação (ASC/DESC)
• dateStart - Data de início para filtro (YYYY-MM-DD)
• dateEnd - Data de fim para filtro (YYYY-MM-DD)

Detalhes por EndpointCopiar link da seção

GET /v1/facebook/accountsCopiar link da seção

curl -G 'https://data.v4mos.ai/v1/facebook/accounts' \
  -H 'x-client-id: SEU_CLIENT_ID' \
  -H 'x-client-secret: SEU_CLIENT_SECRET' \
  --data-urlencode 'organizationId=organization_123' \
  --data-urlencode 'dateStart=2024-01-01' \
  --data-urlencode 'dateEnd=2024-12-31' \
  --data-urlencode 'page=1' \
  --data-urlencode 'limit=100'

{
  "data": [
    {
      "account_id": "act_123",
      "account_name": "Marca Brasil",
      "account_status": "ACTIVE",
      "organization_id": "organization_123",
      "inserted_at": "2024-03-10T10:20:30Z"
    }
  ],
  "meta": { "page": 1, "limit": 100, "hasNextPage": false, "hasPreviousPage": false }
}

GET /v1/facebook/ads/campaignsCopiar link da seção

curl -G 'https://data.v4mos.ai/v1/facebook/ads/campaigns' \
  -H 'x-client-id: SEU_CLIENT_ID' \
  -H 'x-client-secret: SEU_CLIENT_SECRET' \
  --data-urlencode 'organizationId=organization_123' \
  --data-urlencode 'dateStart=2024-01-01' \
  --data-urlencode 'dateEnd=2024-12-31'

{
  "data": [
    {
      "campaign_id": "cmp_111",
      "campaign_name": "Lançamento App",
      "impressions": 120000,
      "clicks": 3400,
      "ctr": 2.83,
      "spend": 9500.25,
      "objective": "CONVERSIONS",
      "website_purchase_roas": 3.1,
      "date_start": "2024-01-01",
      "date_stop": "2024-01-31"
    }
  ],
  "meta": { "page": 1, "limit": 500,  "hasNextPage": false, "hasPreviousPage": false }
}

GET /v1/facebook/ads/adsetCopiar link da seção

GET /v1/facebook/ads/adCopiar link da seção

GET /v1/facebook/ads/actionsCopiar link da seção

GET /v1/facebook/ads/demographicCopiar link da seção

GET /v1/facebook/ads/platformCopiar link da seção

GET /v1/facebook/ads/regionCopiar link da seção

GET /v1/facebook/creativesCopiar link da seção

GET /v1/facebook/ads/adset-configCopiar link da seção

GET /v1/facebook/ads/campaigns-configCopiar link da seção

Campos Específicos do FacebookCopiar link da seção

CampanhasCopiar link da seção

• campaign_name - Nome da campanha
• objective - Objetivo da campanha (ex: CONVERSIONS, REACH, etc.)
• status - Status da campanha
• date_start - Data de início
• date_stop - Data de fim

Conjuntos de Anúncios (Ad Sets)Copiar link da seção

• adset_name - Nome do conjunto de anúncios
• campaign_id - ID da campanha pai
• status - Status do conjunto de anúncios

AnúnciosCopiar link da seção

• ad_name - Nome do anúncio
• adset_id - ID do conjunto de anúncios pai
• campaign_id - ID da campanha pai

Métricas DisponíveisCopiar link da seção

• clicks - Número de cliques
• reach - Alcance
• impressions - Número de impressões
• spend - Valor gasto

RespostasCopiar link da seção

Todas as respostas seguem o padrão:

{
  "data": [...],
  "meta": {
    "page": 1,
    "limit": 500,
    "hasNextPage": true,
    "hasPreviousPage": false
  }
}