> ## Documentation Index
> Fetch the complete documentation index at: https://docs.steerai.autos/llms.txt
> Use this file to discover all available pages before exploring further.

# API de campanas en redes sociales

> Automatiza campanas de marketing en Facebook, Instagram y TikTok

## Resumen

La API de campanas en redes sociales permite automatizar campañas para tus listados de vehiculos en plataformas sociales. Lanza campañas multi-plataforma, monitorea rendimiento y gestiona gasto publicitario desde Steer AI.

## Plataformas soportadas

<CardGroup cols={3}>
  <Card title="Facebook" icon="facebook">
    Facebook Marketplace y anuncios en News Feed
  </Card>

  <Card title="Instagram" icon="instagram">
    Anuncios en Feed y Stories
  </Card>

  <Card title="TikTok" icon="tiktok">
    Anuncios en For You (Proximamente)
  </Card>
</CardGroup>

## Prerrequisitos

Antes de usar la API, debes:

1. Conectar tus cuentas sociales via el servicio upload-post
2. Tener una cuenta activa de Facebook Business Manager
3. Configurar metodos de pago en cuentas publicitarias

## Endpoints

### Obtener paginas de Facebook

<ParamField path="GET" type="endpoint">
  /ads/facebook/pages
</ParamField>

Obtiene paginas disponibles para publicidad vinculadas a tu cuenta.

**Response:**

```json theme={null}
{
  "success": true,
  "pages": [
    {
      "id": "123456789",
      "name": "Prime Auto Dealership",
      "picture": "https://...",
      "account_id": "act_9876543210"
    }
  ]
}
```

**Campos de respuesta:**

<ResponseField name="id" type="string">
  ID de pagina de Facebook
</ResponseField>

<ResponseField name="name" type="string">
  Nombre visible de la pagina
</ResponseField>

<ResponseField name="picture" type="string">
  URL de la foto de perfil
</ResponseField>

<ResponseField name="account_id" type="string">
  ID de cuenta publicitaria asociada
</ResponseField>

<Info>
  Este endpoint se cachea por 5 minutos para mejorar rendimiento.
</Info>

***

### Activar campana

<ParamField path="POST" type="endpoint">
  /ads/campaigns/activate
</ParamField>

Lanza una campana en una o mas plataformas sociales.

**Request Body:**

```json theme={null}
{
  "campaignId": "campaign_uuid",
  "platforms": ["facebook", "instagram"]
}
```

<ParamField body="campaignId" type="string" required>
  Campaign UUID del sistema de marketing
</ParamField>

<ParamField body="platforms" type="array" required>
  Plataformas: `facebook`, `instagram`, `tiktok`. Al menos una plataforma.
</ParamField>

**Response:**

```json theme={null}
{
  "results": [
    {
      "success": true,
      "campaign_id": "fb_campaign_123",
      "ad_set_id": "fb_adset_456",
      "ad_id": "fb_ad_789",
      "platform": "facebook",
      "message": "Campaign activated successfully"
    },
    {
      "success": true,
      "campaign_id": "ig_campaign_123",
      "ad_set_id": "ig_adset_456",
      "ad_id": "ig_ad_789",
      "platform": "instagram",
      "message": "Campaign activated successfully"
    }
  ],
  "summary": {
    "total": 2,
    "successes": 2,
    "errors": 0,
    "successful_platforms": ["facebook", "instagram"],
    "error_messages": []
  }
}
```

**Campos de respuesta:**

<ResponseField name="results" type="array">
  Arreglo de resultados por plataforma
</ResponseField>

<ResponseField name="success" type="boolean">
  Si la campana se lanzo con exito
</ResponseField>

<ResponseField name="campaign_id" type="string">
  ID de campana en la plataforma
</ResponseField>

<ResponseField name="ad_set_id" type="string">
  ID de ad set en la plataforma
</ResponseField>

<ResponseField name="ad_id" type="string">
  ID de anuncio en la plataforma
</ResponseField>

<ResponseField name="platform" type="string">
  Plataforma (facebook, instagram, tiktok)
</ResponseField>

<ResponseField name="error" type="string">
  Mensaje de error si fallo
</ResponseField>

***

### Obtener metricas de campana

<ParamField path="GET" type="endpoint">
  /ads/campaigns/{campaignId}/metrics
</ParamField>

Obtiene metricas de rendimiento para una campana activa.

**Path Parameters:**

<ParamField path="campaignId" type="string" required>
  Campaign UUID
</ParamField>

**Query Parameters:**

<ParamField query="platformType" type="enum" required>
  Plataforma: `facebook`, `instagram`, `tiktok`
</ParamField>

**Response:**

```json theme={null}
{
  "success": true,
  "data": {
    "impressions": 125430,
    "clicks": 3421,
    "conversions": 87,
    "spent": 1250.50,
    "ctr": 2.73,
    "cpc": 0.37,
    "cpm": 9.97,
    "reach": 98234,
    "frequency": 1.28,
    "conversion_rate": 2.54
  }
}
```

**Metricas explicadas:**

<ResponseField name="impressions" type="number">
  Numero de veces que se mostro el anuncio
</ResponseField>

<ResponseField name="clicks" type="number">
  Numero de clics en el anuncio
</ResponseField>

<ResponseField name="conversions" type="number">
  Numero de conversiones exitosas (leads, consultas, etc.)
</ResponseField>

<ResponseField name="spent" type="number">
  Monto total gastado (en moneda de la cuenta)
</ResponseField>

<ResponseField name="ctr" type="number">
  Porcentaje de click-through rate
</ResponseField>

<ResponseField name="cpc" type="number">
  Costo por clic
</ResponseField>

<ResponseField name="cpm" type="number">
  Costo por mil impresiones
</ResponseField>

<ResponseField name="reach" type="number">
  Usuarios unicos que vieron el anuncio
</ResponseField>

<ResponseField name="frequency" type="number">
  Promedio de veces que cada usuario vio el anuncio
</ResponseField>

<ResponseField name="conversion_rate" type="number">
  Porcentaje de clics que convierten
</ResponseField>

<Info>
  Las metricas se cachean por 1 minuto. Los datos pueden tardar 24-48 horas en estabilizarse.
</Info>

***

### Pausar campana

<ParamField path="POST" type="endpoint">
  /ads/campaigns/{campaignId}/pause
</ParamField>

Pausa una campana activa en una plataforma.

**Path Parameters:**

<ParamField path="campaignId" type="string" required>
  Campaign UUID
</ParamField>

**Request Body:**

```json theme={null}
{
  "platformType": "facebook"
}
```

<ParamField body="platformType" type="enum" required>
  Plataforma: `facebook`, `instagram`, `tiktok`
</ParamField>

**Response:**

```json theme={null}
{
  "success": true,
  "campaign_id": "fb_campaign_123",
  "platform": "facebook",
  "message": "Campaign paused successfully"
}
```

<Warning>
  Pausar detiene la entrega de anuncios inmediatamente pero no elimina la campana. Puedes reactivarla despues.
</Warning>

***

## Flujo de campana

```mermaid theme={null}
graph TD
    A[Create Campaign] --> B{Connect Accounts?}
    B -->|No| C[Connect Facebook/Instagram]
    B -->|Yes| D[Get Facebook Pages]
    C --> D
    D --> E[Select Target Pages]
    E --> F[Configure Campaign]
    F --> G[Activate Campaign]
    G --> H{Launch Success?}
    H -->|Yes| I[Monitor Metrics]
    H -->|No| J[Review Errors]
    I --> K{Performance OK?}
    K -->|Yes| L[Continue]
    K -->|No| M[Optimize Campaign]
    M --> I
    L --> N{Campaign Complete?}
    N -->|No| I
    N -->|Yes| O[Pause/Archive]
    J --> F

    style G fill:#282F75
    style I fill:#4360B1
    style O fill:#28a745
```

## Mejores practicas de campana

### Segmentacion de audiencia

Configura campanas para alcance optimo:

* **Ubicacion:** Segmenta ciudades o regiones donde operas
* **Rango de edad:** Normalmente 25-54 para compras de autos
* **Intereses:** Enthusiasts, compradores de autos nuevos, lujo
* **Comportamientos:** In-market, recien mudados, nuevo empleo

### Recomendaciones de presupuesto

| Tipo de campana            | Presupuesto diario | Duracion   | Resultados esperados |
| -------------------------- | ------------------ | ---------- | -------------------- |
| **Awareness local**        | \$20-50            | 7-14 dias  | 5,000-15,000 alcance |
| **Generacion de leads**    | \$50-100           | 14-30 dias | 50-150 leads         |
| **Showcase de inventario** | \$100-200          | 30-60 dias | 100-300 consultas    |
| **Promocion especial**     | \$200-500          | 7-14 dias  | 200-500 leads        |

### Guías creativas

**Imagenes:**

* Fotos de alta calidad (1080x1080 recomendado)
* Multiples angulos exterior e interior
* Iluminacion profesional y fondos limpios
* Incluir precio o promociones

**Copy:**

* Mensajes claros y concisos (125 caracteres o menos)
* Incluir marca, modelo, ano
* Resaltar features clave o beneficios
* Call-to-action fuerte ("Schedule Test Drive", "View Details")

**Video (si aplica):**

* 15-30 segundos ideal
* Muestra vehiculo en movimiento y detalles
* Agrega subtitulos (80% sin sonido)
* Incluye branding al inicio y al final

## Casos de uso

### Ejemplo 1: Lanzar campana multi-plataforma

```bash theme={null}
# Activate campaign on Facebook and Instagram
curl -X POST "https://api.steerai.autos/v1/ads/campaigns/activate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "campaignId": "campaign_uuid",
    "platforms": ["facebook", "instagram"]
  }'
```

### Ejemplo 2: Monitorear rendimiento

```bash theme={null}
# Get Facebook campaign metrics
curl -X GET "https://api.steerai.autos/v1/ads/campaigns/{campaignId}/metrics?platformType=facebook" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Ejemplo 3: Pausar campana con bajo rendimiento

```bash theme={null}
# Pause campaign if metrics don't meet targets
curl -X POST "https://api.steerai.autos/v1/ads/campaigns/{campaignId}/pause" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "platformType": "facebook"
  }'
```

## Codigos de error

| Code                      | Status | Description                          |
| ------------------------- | ------ | ------------------------------------ |
| `USER_NOT_REGISTERED`     | 400    | Usuario no registrado en upload-post |
| `ACCOUNT_NOT_CONNECTED`   | 400    | Cuenta social no conectada           |
| `CAMPAIGN_NOT_FOUND`      | 404    | Campaign ID no existe                |
| `INVALID_PLATFORM`        | 400    | Plataforma no soportada              |
| `INSUFFICIENT_AD_CREDIT`  | 402    | No hay credito suficiente            |
| `PAGE_NOT_FOUND`          | 404    | Pagina de Facebook no accesible      |
| `PERMISSION_DENIED`       | 403    | Faltan permisos requeridos           |
| `CAMPAIGN_ALREADY_ACTIVE` | 400    | Campana ya activa                    |

## Notas por plataforma

### Facebook/Instagram

* Requiere cuenta de Facebook Business Manager
* Cuenta de anuncios con metodo de pago configurado
* Pagina debe tener al menos 30 seguidores para boosted posts
* Tiempo de revision: 24h tipico, hasta 48h para anuncios complejos
* Presupuesto diario minimo: \$5 USD equivalente

### TikTok

* Actualmente en desarrollo
* Requiere cuenta TikTok Business
* Presupuesto diario minimo: \$20 USD equivalente
* Tiempo de revision: hasta 24h

## Ejemplo de integracion

```javascript theme={null}
class CampaignManager {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.baseURL = 'https://api.steerai.autos/v1';
  }

  async activateCampaign(campaignId, platforms) {
    const response = await fetch(`${this.baseURL}/ads/campaigns/activate`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ campaignId, platforms })
    });
    return response.json();
  }

  async getMetrics(campaignId, platform) {
    const response = await fetch(
      `${this.baseURL}/ads/campaigns/${campaignId}/metrics?platformType=${platform}`,
      {
        headers: { 'Authorization': `Bearer ${this.apiKey}` }
      }
    );
    return response.json();
  }

  async pauseCampaign(campaignId, platform) {
    const response = await fetch(
      `${this.baseURL}/ads/campaigns/${campaignId}/pause`,
      {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${this.apiKey}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({ platformType: platform })
      }
    );
    return response.json();
  }

  // Monitor campaign and auto-pause if CPC exceeds threshold
  async monitorCampaign(campaignId, platform, maxCPC) {
    const metrics = await this.getMetrics(campaignId, platform);

    if (metrics.data.cpc > maxCPC) {
      console.log(`CPC ${metrics.data.cpc} exceeds threshold ${maxCPC}. Pausing campaign.`);
      await this.pauseCampaign(campaignId, platform);
      return { action: 'paused', reason: 'CPC_THRESHOLD_EXCEEDED' };
    }

    return { action: 'continue', metrics: metrics.data };
  }
}
```

## Recursos relacionados

<CardGroup cols={2}>
  <Card title="Guia de estrategia de marketing" icon="bullhorn" href="/es/guides/marketing-strategy">
    Aprende estrategias de marketing automotriz
  </Card>

  <Card title="API de vehiculos" icon="car" href="/es/api-reference/vehicles/overview">
    Gestiona inventario para campanas
  </Card>

  <Card title="Analitica de dashboard" icon="chart-line" href="/es/api-reference/analytics/dashboard-statistics">
    Mide ROI y rendimiento de campanas
  </Card>

  <Card title="Mejores practicas" icon="star" href="/es/guides/best-practices">
    Mejores practicas de marketing y API
  </Card>
</CardGroup>