> ## 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 für Social-Media-Kampagnen

> Marketingkampagnen über Facebook, Instagram und TikTok automatisieren

## Überblick

Die Social-Media-Kampagnen-API ermöglicht automatisierte Marketingkampagnen für Ihre Fahrzeuginserate auf den wichtigsten sozialen Plattformen. Starten Sie Multi-Platform-Kampagnen, verfolgen Sie Performance-Metriken und verwalten Sie das Werbebudget direkt in Steer AI.

## Unterstützte Plattformen

<CardGroup cols={3}>
  <Card title="Facebook" icon="facebook">
    Facebook Marketplace- und News-Feed-Anzeigen
  </Card>

  <Card title="Instagram" icon="instagram">
    Instagram-Feed- und Stories-Anzeigen
  </Card>

  <Card title="TikTok" icon="tiktok">
    TikTok For You-Page-Anzeigen (in Kürze)
  </Card>
</CardGroup>

## Voraussetzungen

Bevor Sie die Campaigns-API nutzen, müssen Sie:

1. Ihre Social-Media-Konten über den upload-post-Service verbinden
2. Ein aktives Facebook Business Manager-Konto haben
3. Zahlungsmethoden für Werbekonten einrichten

## Endpunkte

### Facebook-Seiten abrufen

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

Ruft Facebook-Seiten ab, die mit Ihrem Konto verknüpft sind und für Werbung verfügbar sind.

**Antwort:**

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

**Antwortfelder:**

<ResponseField name="id" type="string">
  Facebook-Seiten-ID
</ResponseField>

<ResponseField name="name" type="string">
  Anzeigename der Seite
</ResponseField>

<ResponseField name="picture" type="string">
  URL des Profilbilds
</ResponseField>

<ResponseField name="account_id" type="string">
  Zugehörige Facebook-Werbekonto-ID
</ResponseField>

<Info>
  Dieser Endpunkt ist 5 Minuten gecacht, um die Performance zu verbessern.
</Info>

***

### Kampagne aktivieren

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

Startet eine Marketingkampagne auf einer oder mehreren Social-Media-Plattformen.

**Anfrage-Body:**

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

<ParamField body="campaignId" type="string" required>
  Kampagnen-UUID aus Ihrem Marketing-System
</ParamField>

<ParamField body="platforms" type="array" required>
  Array der Plattformnamen: `facebook`, `instagram`, `tiktok`. Mindestens eine Plattform erforderlich.
</ParamField>

**Antwort:**

```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": []
  }
}
```

**Antwortfelder:**

<ResponseField name="results" type="array">
  Array plattformspezifischer Ergebnisse
</ResponseField>

<ResponseField name="success" type="boolean">
  Ob die Kampagne auf dieser Plattform erfolgreich gestartet wurde
</ResponseField>

<ResponseField name="campaign_id" type="string">
  Plattform-spezifische Kampagnen-ID
</ResponseField>

<ResponseField name="ad_set_id" type="string">
  Plattform-spezifische Anzeigengruppen-ID
</ResponseField>

<ResponseField name="ad_id" type="string">
  Plattform-spezifische Anzeigen-ID
</ResponseField>

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

<ResponseField name="error" type="string">
  Fehlermeldung, falls die Kampagne fehlschlug
</ResponseField>

***

### Kampagnenmetriken abrufen

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

Ruft Performance-Metriken für eine aktive Kampagne ab.

**Path-Parameter:**

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

**Query-Parameter:**

<ParamField query="platformType" type="enum" required>
  Plattform für die Metriken: `facebook`, `instagram`, `tiktok`
</ParamField>

**Antwort:**

```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
  }
}
```

**Metriken erklärt:**

<ResponseField name="impressions" type="number">
  Anzahl der Anzeigen-Impressionen
</ResponseField>

<ResponseField name="clicks" type="number">
  Anzahl der Klicks
</ResponseField>

<ResponseField name="conversions" type="number">
  Anzahl erfolgreicher Conversions (Leads, Anfragen usw.)
</ResponseField>

<ResponseField name="spent" type="number">
  Gesamtbetrag der Ausgaben (Kontowährung)
</ResponseField>

<ResponseField name="ctr" type="number">
  Klickrate in Prozent
</ResponseField>

<ResponseField name="cpc" type="number">
  Kosten pro Klick
</ResponseField>

<ResponseField name="cpm" type="number">
  Kosten pro tausend Impressionen (Mille)
</ResponseField>

<ResponseField name="reach" type="number">
  Einzigartige Nutzer, die die Anzeige gesehen haben
</ResponseField>

<ResponseField name="frequency" type="number">
  Durchschnittliche Anzeigenhäufigkeit pro Nutzer
</ResponseField>

<ResponseField name="conversion_rate" type="number">
  Prozentsatz der Klicks, die konvertiert haben
</ResponseField>

<Info>
  Metriken sind 1 Minute gecacht. Daten können 24–48 Stunden benötigen, um sich auf Plattformseite zu stabilisieren.
</Info>

***

### Kampagne pausieren

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

Pausiert eine aktive Kampagne auf einer bestimmten Plattform.

**Path-Parameter:**

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

**Anfrage-Body:**

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

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

**Antwort:**

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

<Warning>
  Das Pausieren stoppt die Auslieferung sofort, löscht die Kampagne aber nicht. Sie können sie später reaktivieren.
</Warning>

***

## Kampagnen-Workflow

```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
```

## Best Practices für Kampagnen

### Zielgruppen-Targeting

Konfigurieren Sie Kampagnen für optimale Reichweite:

* **Standort:** Zielstädte oder Regionen, in denen Sie aktiv sind
* **Altersbereich:** Typischerweise 25–54 für Autokäufe
* **Interessen:** Autoenthusiasten, Neuwagenkäufer, Premiumfahrzeuge
* **Verhalten:** In-market für Fahrzeuge, kürzlich umgezogen, neuer Job

### Budget-Empfehlungen

| Kampagnentyp           | Tagesbudget | Laufzeit   | Erwartete Ergebnisse    |
| ---------------------- | ----------- | ---------- | ----------------------- |
| **Lokale Bekanntheit** | \$20-50     | 7-14 Tage  | 5.000-15.000 Reichweite |
| **Lead-Generierung**   | \$50-100    | 14-30 Tage | 50-150 Leads            |
| **Bestands-Showcase**  | \$100-200   | 30-60 Tage | 100-300 Anfragen        |
| **Sonderaktion**       | \$200-500   | 7-14 Tage  | 200-500 Leads           |

### Kreativ-Richtlinien

**Bilder:**

* Hochwertige Fahrzeugfotos (1080x1080 empfohlen)
* Mehrere Winkel von außen und innen
* Professionelle Beleuchtung und saubere Hintergründe
* Preis oder Sonderangebot als Overlay

**Copy:**

* Klare, prägnante Botschaft (125 Zeichen oder weniger)
* Marke, Modell, Jahr nennen
* Wichtige Features oder Vorteile hervorheben
* Starker Call-to-Action ("Testfahrt vereinbaren", "Details ansehen")

**Video (falls zutreffend):**

* 15-30 Sekunden optimale Länge
* Fahrzeug in Bewegung und Details zeigen
* Untertitel hinzufügen (80% schauen ohne Ton)
* Branding am Anfang und Ende

## Anwendungsfälle

### Beispiel 1: Multi-Platform-Kampagne starten

```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"]
  }'
```

### Beispiel 2: Kampagnen-Performance überwachen

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

### Beispiel 3: Schwache Kampagne pausieren

```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"
  }'
```

## Fehlercodes

| Code                      | Status | Beschreibung                                        |
| ------------------------- | ------ | --------------------------------------------------- |
| `USER_NOT_REGISTERED`     | 400    | Nutzer nicht beim upload-post-Service registriert   |
| `ACCOUNT_NOT_CONNECTED`   | 400    | Social-Media-Konto nicht verbunden                  |
| `CAMPAIGN_NOT_FOUND`      | 404    | Kampagnen-ID existiert nicht                        |
| `INVALID_PLATFORM`        | 400    | Nicht unterstützte Plattform angegeben              |
| `INSUFFICIENT_AD_CREDIT`  | 402    | Nicht genug Guthaben im Werbekonto                  |
| `PAGE_NOT_FOUND`          | 404    | Facebook-Seite nicht gefunden oder nicht zugänglich |
| `PERMISSION_DENIED`       | 403    | Fehlende erforderliche Berechtigungen               |
| `CAMPAIGN_ALREADY_ACTIVE` | 400    | Kampagne läuft bereits                              |

## Plattform-spezifische Hinweise

### Facebook/Instagram

* Erfordert Facebook Business Manager-Konto
* Werbekonto muss eine Zahlungsmethode eingerichtet haben
* Seite benötigt mindestens 30 Follower für Boosted Posts
* Review-Zeiten: typischerweise 24 Stunden, bis zu 48 Stunden bei komplexen Anzeigen
* Mindest-Tagesbudget: \$5 USD äquivalent

### TikTok

* Derzeit in Entwicklung
* Erfordert TikTok Business-Konto
* Mindest-Tagesbudget: \$20 USD äquivalent
* Review-Zeiten: bis zu 24 Stunden

## Integrationsbeispiel

```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 };
  }
}
```

## Verwandte Ressourcen

<CardGroup cols={2}>
  <Card title="Marketing-Strategie-Leitfaden" icon="bullhorn" href="/de/guides/marketing-strategy">
    Effektive Automotive-Marketing-Strategien
  </Card>

  <Card title="Fahrzeuge-API" icon="car" href="/de/api-reference/vehicles/overview">
    Bestand für Kampagnen verwalten
  </Card>

  <Card title="Analytics-Dashboard" icon="chart-line" href="/de/api-reference/analytics/dashboard-statistics">
    ROI und Performance von Kampagnen verfolgen
  </Card>

  <Card title="Best Practices" icon="star" href="/de/guides/best-practices">
    Marketing- und API-Best-Practices
  </Card>
</CardGroup>