> ## 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 des campagnes sur les reseaux sociaux

> Automatiser des campagnes marketing sur Facebook, Instagram et TikTok

## Vue d'ensemble

L'API des campagnes sur les reseaux sociaux permet d'automatiser les campagnes marketing pour vos annonces de vehicules sur les principales plateformes sociales. Lancez des campagnes multi-plateformes, suivez les indicateurs de performance et gerez les depenses publicitaires directement depuis la plateforme Steer AI.

## Plateformes prises en charge

<CardGroup cols={3}>
  <Card title="Facebook" icon="facebook">
    Publicites Facebook Marketplace et News Feed
  </Card>

  <Card title="Instagram" icon="instagram">
    Publicites Instagram Feed et Stories
  </Card>

  <Card title="TikTok" icon="tiktok">
    Publicites TikTok For You (bientot disponible)
  </Card>
</CardGroup>

## Prerequis

Avant d'utiliser l'API Campaigns, vous devez :

1. Connecter vos comptes de reseaux sociaux via le service upload-post
2. Disposer d'un compte Facebook Business Manager actif
3. Configurer des moyens de paiement pour les comptes publicitaires

## Endpoints

### Recuperer les pages Facebook

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

Recuperer les pages Facebook disponibles pour la publicite et liees a votre compte.

**Reponse :**

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

**Champs de reponse :**

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

<ResponseField name="name" type="string">
  Nom d'affichage de la page
</ResponseField>

<ResponseField name="picture" type="string">
  URL de la photo de profil de la page
</ResponseField>

<ResponseField name="account_id" type="string">
  ID du compte publicitaire Facebook associe
</ResponseField>

<Info>
  Cet endpoint est mis en cache 5 minutes pour ameliorer les performances.
</Info>

***

### Activer une campagne

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

Lancer une campagne marketing sur une ou plusieurs plateformes sociales.

**Corps de requete :**

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

<ParamField body="campaignId" type="string" required>
  UUID de campagne depuis votre systeme de campagnes marketing
</ParamField>

<ParamField body="platforms" type="array" required>
  Tableau des plateformes : `facebook`, `instagram`, `tiktok`. Au moins une plateforme est requise.
</ParamField>

**Reponse :**

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

**Champs de reponse :**

<ResponseField name="results" type="array">
  Tableau des resultats par plateforme
</ResponseField>

<ResponseField name="success" type="boolean">
  Indique si la campagne a ete lancee sur cette plateforme
</ResponseField>

<ResponseField name="campaign_id" type="string">
  ID de campagne specifique a la plateforme
</ResponseField>

<ResponseField name="ad_set_id" type="string">
  ID de l'ensemble de publicites specifique a la plateforme
</ResponseField>

<ResponseField name="ad_id" type="string">
  ID de la publicite specifique a la plateforme
</ResponseField>

<ResponseField name="platform" type="string">
  Nom de la plateforme (facebook, instagram, tiktok)
</ResponseField>

<ResponseField name="error" type="string">
  Message d'erreur si la campagne a echoue
</ResponseField>

***

### Recuperer les metriques d'une campagne

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

Recuperer les metriques de performance d'une campagne active.

**Parametres de chemin :**

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

**Parametres de requete :**

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

**Reponse :**

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

**Explication des metriques :**

<ResponseField name="impressions" type="number">
  Nombre d'affichages de la publicite
</ResponseField>

<ResponseField name="clicks" type="number">
  Nombre de clics sur la publicite
</ResponseField>

<ResponseField name="conversions" type="number">
  Nombre de conversions reussies (leads, demandes, etc.)
</ResponseField>

<ResponseField name="spent" type="number">
  Montant total depense (dans la devise du compte)
</ResponseField>

<ResponseField name="ctr" type="number">
  Taux de clics en pourcentage
</ResponseField>

<ResponseField name="cpc" type="number">
  Cout par clic
</ResponseField>

<ResponseField name="cpm" type="number">
  Cout pour mille impressions
</ResponseField>

<ResponseField name="reach" type="number">
  Utilisateurs uniques ayant vu la publicite
</ResponseField>

<ResponseField name="frequency" type="number">
  Nombre moyen d'affichages par utilisateur
</ResponseField>

<ResponseField name="conversion_rate" type="number">
  Pourcentage de clics convertis
</ResponseField>

<Info>
  Les metriques sont mises en cache 1 minute. Les donnees peuvent mettre 24 a 48 heures a se stabiliser cote plateforme.
</Info>

***

### Mettre en pause une campagne

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

Mettre en pause une campagne active sur une plateforme specifique.

**Parametres de chemin :**

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

**Corps de requete :**

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

<ParamField body="platformType" type="enum" required>
  Plateforme a mettre en pause : `facebook`, `instagram`, `tiktok`
</ParamField>

**Reponse :**

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

<Warning>
  Mettre en pause arrete immediatement la diffusion, mais ne supprime pas la campagne. Vous pouvez la reactiver plus tard.
</Warning>

***

## Workflow de campagne

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

## Bonnes pratiques de campagne

### Ciblage d'audience

Configurez vos campagnes pour une portee optimale :

* **Localisation :** Ciblez des villes ou regions ou vous operez
* **Tranche d'age :** Typiquement 25-54 pour les achats auto
* **Interets :** Passionnes d'auto, acheteurs de voitures neuves, vehicules de luxe
* **Comportements :** Intention d'achat, demenagement recent, nouvel emploi

### Recommandations de budget

| Type de campagne               | Budget quotidien | Duree       | Resultats attendus     |
| ------------------------------ | ---------------- | ----------- | ---------------------- |
| **Notoriete locale**           | \$20-50          | 7-14 jours  | 5,000-15,000 de portee |
| **Generation de leads**        | \$50-100         | 14-30 jours | 50-150 leads           |
| **Mise en avant d'inventaire** | \$100-200        | 30-60 jours | 100-300 demandes       |
| **Promotion speciale**         | \$200-500        | 7-14 jours  | 200-500 leads          |

### Directives creatives

**Images :**

* Photos de vehicules de haute qualite (1080x1080 recommande)
* Plusieurs angles montrant l'exterieur et l'interieur
* Eclairage professionnel et fond propre
* Inclure le prix ou des offres speciales

**Copy :**

* Message clair et concis (125 caracteres ou moins)
* Inclure marque, modele, annee
* Mettre en avant des caracteristiques ou avantages
* Appel a l'action fort ("Planifier un essai", "Voir les details")

**Video (si applicable) :**

* 15-30 secondes de duree optimale
* Montrer le vehicule en mouvement et les details
* Ajouter des sous-titres (80 % regardent sans son)
* Inclure la marque au debut et a la fin

## Cas d'usage

### Exemple 1 : Lancer une campagne multi-plateformes

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

### Exemple 2 : Suivre la performance d'une campagne

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

### Exemple 3 : Mettre en pause une campagne sous-performante

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

## Codes d'erreur

| Code                      | Statut | Description                                           |
| ------------------------- | ------ | ----------------------------------------------------- |
| `USER_NOT_REGISTERED`     | 400    | Utilisateur non enregistre sur le service upload-post |
| `ACCOUNT_NOT_CONNECTED`   | 400    | Compte reseau social non connecte                     |
| `CAMPAIGN_NOT_FOUND`      | 404    | L'ID de campagne n'existe pas                         |
| `INVALID_PLATFORM`        | 400    | Plateforme non prise en charge                        |
| `INSUFFICIENT_AD_CREDIT`  | 402    | Credit insuffisant sur le compte publicitaire         |
| `PAGE_NOT_FOUND`          | 404    | Page Facebook introuvable ou inaccessible             |
| `PERMISSION_DENIED`       | 403    | Autorisations requises manquantes                     |
| `CAMPAIGN_ALREADY_ACTIVE` | 400    | La campagne est deja active                           |

## Notes specifiques aux plateformes

### Facebook/Instagram

* Necessite un compte Facebook Business Manager
* Le compte publicitaire doit avoir un moyen de paiement configure
* La page doit avoir au moins 30 abonnes pour les posts sponsorises
* Delais de validation : 24 heures en general, jusqu'a 48 heures pour les publicites complexes
* Budget quotidien minimum : \$5 USD equivalent

### TikTok

* Actuellement en developpement
* Necessitera un compte TikTok Business
* Budget quotidien minimum : \$20 USD equivalent
* Delais de validation : jusqu'a 24 heures

## Exemple d'integration

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

## Ressources associees

<CardGroup cols={2}>
  <Card title="Guide de strategie marketing" icon="bullhorn" href="/fr/guides/marketing-strategy">
    Apprendre des strategies marketing automobiles efficaces
  </Card>

  <Card title="API Vehicules" icon="car" href="/fr/api-reference/vehicles/overview">
    Gerer l'inventaire pour les campagnes marketing
  </Card>

  <Card title="Tableau de bord Analytics" icon="chart-line" href="/fr/api-reference/analytics/dashboard-statistics">
    Suivre le ROI et les performances des campagnes
  </Card>

  <Card title="Bonnes pratiques" icon="star" href="/fr/guides/best-practices">
    Bonnes pratiques marketing et API
  </Card>
</CardGroup>