API de campagne publicitaire CPAlead : créer et gérer des offres

L’API Campaign CPAlead permet à un annonceur self-serve vérifié d’utiliser du code, un agent IA, un serveur MCP ou un plugin pour travailler avec des campagnes CPA, CPI et CPC. Un client autorisé peut lire les exigences actuelles de campagne, valider une campagne complète avant de l’enregistrer, téléverser une création, créer une campagne, lister et récupérer des campagnes, modifier une campagne avec protection de version, et démarrer ou mettre en pause explicitement une campagne éligible.

Il s’agit du compagnon d’automatisation du tableau de bord annonceur normal. Si vous voulez d’abord une explication champ par champ des types de campagnes, du tracking, du ciblage, des payouts, des plafonds, du financement, de la validation et du lancement, lisez Comment faire de la publicité sur CPAlead en 2026 : ajouter et lancer votre première offre. Utilisez cet article lorsque vous êtes prêt à exprimer cette configuration sous forme de JSON structuré et d’actions API contrôlées.

Ce que l’API Campaign peut faire

L’API ne fournit pas actuellement d’opération d’archivage, de suppression, de création en lot ou de bascule générique. Les opérations d’archivage ou de suppression restent un flux du tableau de bord. Les actions de démarrage et de pause sont séparées afin qu’une personne ou un client IA puisse demander une confirmation claire avant de modifier la diffusion.

L’API Campaign et l’importation via Offer API sont différentes

• API Campaign : Une API bearer token à portée limitée qui valide, crée, lit, modifie, démarre et met en pause des campagnes dans votre compte annonceur.
• Importation via Offer API : Un flux séparé du tableau de bord annonceur qui lit des offres depuis un flux externe compatible et mappe ses champs dans CPAlead.

Le centre Advertiser API garde ces outils sur des pages séparées. Connectez-vous, ouvrez Setup → API, puis choisissez l’outil qui correspond à votre tâche. Utilisez l’API Campaign lorsque votre propre application, agent, serveur MCP ou plugin possède déjà les données de l’offre et a besoin d’un moyen structuré de travailler avec CPAlead. Utilisez l’importateur lorsque CPAlead doit récupérer et mapper un flux d’offres pris en charge. Ne donnez pas à une intégration un jeton plus large que nécessaire à sa mission.

Créer un jeton Campaign API

1. Connectez-vous à un compte annonceur self-serve vérifié.
2. Ouvrez Setup → API, puis sélectionnez Campaign API.
3. Donnez au jeton un nom reconnaissable, comme « Campaign validator » ou « My MCP agent ».
4. Choisissez une expiration. L’option 48 heures est recommandée pour la configuration IA ; les options 30 jours, 90 jours et 365 jours sont aussi disponibles.
5. Sélectionnez uniquement les permissions dont le client a besoin.
6. Créez le jeton et copiez-le immédiatement. CPAlead ne peut plus afficher le jeton complet après le rechargement de la page.
7. Stockez-le dans la configuration secrète du client de confiance et révoquez-le lorsque la tâche se termine.

Un annonceur peut avoir jusqu’à 10 jetons Campaign API actifs. Utilisez des jetons séparés pour des intégrations distinctes afin de limiter les permissions, examiner l’utilisation et révoquer une intégration sans en interrompre une autre.

Où créer votre jeton Campaign API

Un jeton Campaign API est l’identifiant API privé envoyé dans l’en-tête Authorization. Ce n’est pas votre mot de passe CPAlead, et il ne peut pas être utilisé pour se connecter au tableau de bord CPAlead. Après vous être connecté, ouvrez Setup → API, sélectionnez Campaign API, puis utilisez le formulaire Créer un jeton.

URL de base, authentification et format de réponse

Les requêtes authentifiées envoient le jeton une seule fois dans l’en-tête HTTP authorization. Ne le mettez jamais dans l’URL ni dans la chaîne de requête.

Authorization: Bearer YOUR_TOKEN
Accept: application/json

Pour les exemples curl ci-dessous, une configuration plus sûre consiste à stocker l’en-tête d’autorisation dans un fichier de configuration curl local, exclu du contrôle source et lisible uniquement par vous :

# cpalead-auth.cfg
header = "Authorization: Bearer YOUR_TOKEN"
header = "Accept: application/json"

# Restrict the file before using it:
chmod 600 cpalead-auth.cfg

Une réponse réussie contient un objet data ou une liste, plus meta. Les métadonnées incluent un request_id et la version actuelle du schéma, et peuvent inclure la pagination, une version de ressource ou un indicateur de relecture idempotente. Une réponse d’erreur contient un objet error plus meta. Conservez le request_id public pour le dépannage avec le support, mais n’envoyez jamais votre jeton bearer au support.

Étape 1 : lire les exigences en direct

Les exigences sont la source de vérité pour ce que le compte peut soumettre à présent. Elles incluent la version actuelle du schéma et des conditions, l’éligibilité à la création de compte, les pays et appareils pris en charge, les limites de champs, les règles de type de campagne, les plages tarifaires, les plannings, les packages de lancement, les exigences de tracking, les règles d’image et le flux de travail recommandé.

curl --config cpalead-auth.cfg \
  "https://www.cpalead.com/api/v1/advertiser/requirements?type=CPA"

Utilisez type=CPA, type=CPI ou type=CPC pour limiter la réponse. Ne codez pas en dur une version de schéma, une version des conditions, une limite de payout, une enchère, un budget, un package de lancement, un pays, un appareil ou une version minimale d’application provenant d’un ancien exemple. Récupérez de nouveau les exigences lorsque le serveur signale qu’une valeur ou une version n’est plus à jour.

Les trois types de campagnes

• CPA : Paiement pour une action déclarée. L’URL de tracking doit contenir {CLICK_ID}, et une URL de prévisualisation, un objectif de conversion, un plafond quotidien et un package de lancement font partie de la forme de création.
• CPI : Paiement pour une installation ou un événement d’application configuré. Il utilise {CLICK_ID} et ajoute des choix orientés application tels que la plateforme de l’appareil, la méthode de tracking, la version iOS prise en charge et la gestion du proxy.
• CPC : Paiement pour un clic valide. Il utilise une enchère et un budget quotidien au lieu d’un payout de conversion, d’un plafond quotidien et d’un package de lancement.

Toutes les valeurs monétaires de l’API Campaign sont en USD, et les plannings de l’API utilisent UTC. Lisez les exigences retournées et présentez ces faits à la personne qui approuve la requête.

Étape 2 : téléverser une image de campagne

Les requêtes de création n’acceptent pas une URL d’image distante. Téléversez d’abord le fichier en multipart form data, puis placez l’ID temporaire d’image retourné dans image_upload_id.

curl --config cpalead-auth.cfg \
  --request POST \
  --form "[email protected]" \
  "https://www.cpalead.com/api/v1/advertiser/images"

• Sources acceptées : JPG, JPEG, PNG, GIF, BMP et WebP.
• Taille maximale du fichier : 2 Mio.
• Largeur et hauteur de la source : chacune doit être comprise entre 200 et 4096 pixels.
• Résultat stocké : un recadrage WebP 200×200 non animé et sans métadonnées.
• Durée de vie du téléversement inutilisé : 24 heures.
• Limite de téléversements en attente : jusqu’à 25 téléversements d’image inutilisés actuels.
• Utilisation : une création de campagne ou une mise à jour d’image. Téléversez à nouveau pour une campagne différente.

La validation peut vérifier qu’un ID d’image appartient à votre compte et reste utilisable sans le consommer. L’écriture réussie de la campagne le consomme. Le renvoi de la même création terminée avec la même clé d’idempotence retourne le résultat stocké ; il ne crée pas une deuxième campagne à partir de l’image consommée.

Étape 3 : construire un JSON de campagne complet

L’API utilise des objets JSON stricts. Les champs inconnus sont rejetés au lieu d’être ignorés silencieusement. Cela rend une intégration IA plus sûre : une propriété mal orthographiée ou inventée devient un problème de validation visible plutôt qu’un paramètre de campagne accidentel.

L’exemple CPA suivant est un modèle, pas une campagne prête à soumettre. Remplacez chaque valeur COPY_FROM_REQUIREMENTS, ID d’image, URL, payout, pays, plafond et description publique par des valeurs relues pour votre vraie offre.

{
  "schema_version": "COPY_FROM_REQUIREMENTS",
  "external_id": "signup-campaign-us-001",
  "type": "CPA",
  "name": "US Account Signup",
  "creative": {
    "title": "Create Your Free Account",
    "description": "Register and confirm your email",
    "conversion_goal": "Create an account"
  },
  "tracking": {
    "url": "https://tracker.example.com/click?click_id={CLICK_ID}",
    "preview_url": "https://www.example.com/signup",
    "gaid_idfa_filler": false
  },
  "targeting": {
    "countries": ["US"],
    "device": "all_devices",
    "tools_only": false
  },
  "pricing": {
    "payout": "0.50",
    "daily_cap": 20,
    "currency": "USD"
  },
  "schedule": {
    "mode": "always",
    "start_time": "00:00",
    "end_time": "23:59",
    "timezone": "UTC"
  },
  "publisher_access": {
    "mode": "all",
    "publisher_ids": []
  },
  "launch_package": {
    "amount": "COPY_FROM_REQUIREMENTS"
  },
  "image_upload_id": "cimg_COPY_FROM_IMAGE_UPLOAD",
  "terms": {
    "version": "COPY_FROM_REQUIREMENTS",
    "accepted": true
  }
}

Règle de tracking importante pour CPA et CPI

L’URL de tracking doit contenir la macro exacte {CLICK_ID}. Votre tracker ou plateforme d’affiliation doit enregistrer la valeur numérique que CPAlead y insère et renvoyer cet ID de clic enregistré au postback annonceur CPAlead après la conversion. Ne placez pas l’URL de postback de CPAlead dans l’URL de tracking de la campagne. Pour l’explication complète du clic au postback, utilisez le guide public de postback annonceur.

Étape 4 : valider avant de créer

curl --config cpalead-auth.cfg \
  --request POST \
  --header "Content-Type: application/json" \
  --data-binary @campaign.json \
  "https://www.cpalead.com/api/v1/advertiser/campaigns/validate"

La validation renvoie HTTP 200 avec data.valid, une liste errors et une liste warnings. Une réponse 200 peut toujours contenir valid: false, donc un client doit inspecter cette valeur au lieu de considérer le seul statut HTTP comme une approbation. Chaque problème utilise un chemin JSON Pointer tel que /tracking/url, /pricing/payout ou /image_upload_id. Un agent IA doit corriger uniquement le champ indiqué, valider à nouveau et montrer le JSON final au propriétaire du compte avant de demander la permission de créer.

Une réponse valide signifie que la charge utile passe la validation actuelle et la pré-vérification de persistance. Ce n’est pas une promesse d’approbation, d’activation, de trafic, de conversions ou d’éligibilité future. Les contrôles en temps réel de review, de financement, d’accès au compte, de blocage, de planning, de plafond et d’état s’appliquent toujours aux écritures et aux actions du cycle de vie.

Étape 5 : créer de façon sûre avec l’idempotence

curl --config cpalead-auth.cfg \
  --request POST \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: create-signup-campaign-us-001" \
  --data-binary @campaign.json \
  "https://www.cpalead.com/api/v1/advertiser/campaigns"

Créer, démarrer et mettre en pause nécessitent une Idempotency-Key contenant 8 à 200 caractères ASCII visibles. Utilisez une nouvelle clé pour chaque action voulue. Si la connexion échoue et que vous ne savez pas si l’action s’est terminée, réessayez l’action identique avec la même clé. CPAlead peut rejouer la réponse terminée au lieu de créer ou facturer deux fois.

• Même clé et même intention : La réponse terminée peut être rejouée avec meta.idempotent_replay=true.
• Même clé avec détails modifiés : L’API renvoie un conflit d’idempotence.
• Même ID externe avec détails modifiés : L’API renvoie aussi un conflit.
• Requête précédente encore en cours : Attendez l’intervalle indiqué, puis réessayez la même intention avec la même clé.

L’external_id optionnel est votre propre référence stable pour l’opération de création. Il peut faciliter le rapprochement, mais il ne doit pas être réutilisé pour une campagne différente.

Trois campagnes avant un dépôt

Un compte annonceur peut créer jusqu’à trois campagnes self-serve CPA, CPI ou CPC au total avant son premier dépôt annonceur réussi. Les campagnes en pause, refusées et archivées comptent toujours, car créer et archiver des campagnes jetables ne doit pas contourner la limite. Après un dépôt réussi, cette limite de création spécifique ne s’applique plus ; les règles normales de review, de solde, de payout, de budget et d’activation s’appliquent toujours.

Lire et filtrer les campagnes

curl --config cpalead-auth.cfg \
  "https://www.cpalead.com/api/v1/advertiser/campaigns?type=CPA&state=paused&page=1&per_page=25"

Le point de terminaison de liste prend en charge le type de campagne, l’état public, un horodatage updated_since, la page et des filtres par page. La pagination par défaut est de 25 campagnes et permet jusqu’à 100 par page. Les états publics possibles sont active, paused, pending_review, paused_for_funding, cap_reached, outside_schedule, denied, archived et unavailable. Les campagnes archivées n’apparaissent que lorsque vous filtrez explicitement avec state=archived.

Une ressource de campagne inclut son ID, son ID externe optionnel, sa version, son type, son nom, sa création, son tracking, son ciblage, son pricing, son planning, son paramètre d’accès publisher, son URL d’image, ses horodatages et son état public. L’état inclut aussi des indices de review, de diffusion souhaitée, de raison de diffusion et de capacité. Les indices de capacité sont indicatifs : récupérez la dernière campagne et traitez la vraie réponse opérationnelle, car les conditions de compte, de financement, de review, de blocage et de planning peuvent changer.

Mise à jour avec protection de version ETag

Les modifications de campagne utilisent le contrôle de concurrence optimiste. Récupérez d’abord la campagne et enregistrez l’en-tête de réponse exact entre guillemets ETag. Envoyez ensuite cette valeur dans If-Match avec la requête PATCH. Cela empêche un navigateur, un agent ou une intégration d’écraser silencieusement un changement plus récent effectué ailleurs.

# First retrieve the latest campaign and its ETag.
curl --config cpalead-auth.cfg \
  --dump-header campaign-headers.txt \
  "https://www.cpalead.com/api/v1/advertiser/campaigns/12345"

# Then send a reviewed partial update with that exact quoted ETag.
curl --config cpalead-auth.cfg \
  --request PATCH \
  --header "Content-Type: application/json" \
  --header 'If-Match: "COPY_THE_LATEST_ETAG"' \
  --data-binary '{"creative":{"description":"Updated public description"}}' \
  "https://www.cpalead.com/api/v1/advertiser/campaigns/12345"

• Sans If-Match : L’API renvoie HTTP 428.
• If-Match obsolète : L’API renvoie HTTP 412 avec les métadonnées de version actuelles.
• Après un 412 : Récupérez à nouveau la campagne, comparez les modifications, demandez approbation et réessayez avec le nouvel ETag.
• Après un résultat réseau incertain : Récupérez la campagne avant d’envoyer une autre mise à jour.

PATCH n’accepte que les champs publics de campagne. Il fusionne l’objet partiel fourni avec la campagne actuelle et valide le résultat complet. Certaines modifications peuvent nécessiter une nouvelle review ou changer la diffusion, alors lisez l’état de la réponse à chaque fois.

Le démarrage et la pause sont des actions explicites sans corps

# Start an eligible campaign.
curl --config cpalead-auth.cfg \
  --request POST \
  --header "Idempotency-Key: start-campaign-12345-001" \
  "https://www.cpalead.com/api/v1/advertiser/campaigns/12345/actions/start"

# Pause an eligible campaign.
curl --config cpalead-auth.cfg \
  --request POST \
  --header "Idempotency-Key: pause-campaign-12345-001" \
  "https://www.cpalead.com/api/v1/advertiser/campaigns/12345/actions/pause"

N’envoyez pas de corps JSON — pas même {} — pour démarrer ou mettre en pause. Avant de démarrer, confirmez la campagne, le solde, le payout ou l’enchère, l’effet du package de lancement, les pays, les appareils, le planning, le plafond ou le budget, la page de destination et le tracking. Après la réponse, inspectez l’état public ; une campagne peut être activée mais hors de son planning quotidien, en pause pour financement, au plafond, ou autrement incapable de diffuser.

Statuts HTTP et erreurs qu’une intégration doit comprendre

Automatisez en vous basant sur le statut HTTP et sur error.code stable, pas seulement sur le libellé du message. Les détails de validation incluent un chemin, un code et un message en langage clair. Incluez le request_id de la réponse lorsque vous contactez le support.

Limites de débit et reprises responsables

Les requêtes et l’authentification de l’API Campaign sont soumises à des limites de débit pour protéger les annonceurs et le service. Les limites peuvent changer, alors utilisez le schéma OpenAPI en direct et les en-têtes de réponse plutôt que de coder en dur un nombre de requêtes. Lorsque l’API renvoie HTTP 429, attendez Retry-After au lieu de répéter immédiatement les requêtes. Utilisez la pagination, updated_since et la mise en cache locale des exigences publiques inchangées pour éviter des appels inutiles.

Un prompt que vous pouvez donner à un agent IA de confiance

Partagez d’abord le guide et l’URL OpenAPI. Configurez le jeton dans les paramètres secrets privés de la plateforme de l’agent ; n’insérez pas de vrai jeton dans ce prompt.

Read this CPAlead Campaign API guide and the public OpenAPI schema.

Do not ask me to paste a bearer token into chat. Use only the token configured
privately in the integration. Begin with read and validate operations.

1. Ask whether I am creating CPA, CPI, or CPC.
2. Call the matching requirements endpoint.
3. Ask me for every missing business value and explain any financial,
   tracking, targeting, schedule, review, or delivery effect.
4. Draft strict campaign JSON and validate it.
5. Repair validation errors by their JSON Pointer paths.
6. Show me the final normalized intent and ask for confirmation before
   uploading, creating, updating, starting, or pausing anything.
7. Use a unique idempotency key for create, start, and pause.
8. Retrieve the latest campaign and ETag before an update.
9. After every write, report the campaign ID, public state, request ID,
   warnings, and recommended next step.
10. Never attempt archive or delete because those operations are not in
    the Campaign API.

Liste de vérification de sécurité pour l’IA, MCP, les plugins et le code

• Moindre privilège : Commencez par la lecture et la validation. Ajoutez une seule permission d’écriture uniquement lorsque c’est nécessaire.
• Expiration courte : Préférez l’option 48 heures pour une tâche de configuration IA ponctuelle.
• Jetons séparés : Donnez à chaque agent ou intégration son propre jeton nommé.
• Stockage privé : Conservez les jetons dans les paramètres secrets, pas dans les URL, prompts, logs, analyses, captures d’écran ou dépôts.
• Confirmation humaine : Exigez un résumé avant create, update, start ou pause.
• Reprises sûres : Conservez la même clé et la même charge utile après un résultat idempotent incertain.
• Contrôles de version : Ne mettez jamais à jour sans récupérer le dernier ETag.
• Contrôles de réponse : Lisez l’état public et le request ID après chaque écriture.
• Révoquez rapidement : Supprimez l’accès depuis la page Advertising API lorsque la tâche est terminée ou qu’un jeton a pu fuiter.

Foire aux questions

Où trouver ma clé API CPAlead ?

Pour l’API Campaign, l’identifiant s’appelle un jeton Campaign API. Connectez-vous et ouvrez Advertising → Setup → API, puis utilisez Créer un jeton. Copiez le jeton immédiatement car CPAlead affiche la valeur complète une seule fois.

L’API peut-elle créer des campagnes CPA, CPI et CPC ?

Oui. Chaque type a une forme JSON stricte mais différente. Récupérez les exigences de ce type avant de le construire.

Puis-je valider sans autoriser une IA à créer quoi que ce soit ?

Oui. Donnez au jeton uniquement campaigns:validate, et éventuellement campaigns:read. Les exigences et la validation n’ont pas besoin de permission de création.

Une réponse valide signifie-t-elle que la campagne est approuvée ?

Non. Cela signifie que la charge utile actuelle passe la validation et la pré-vérification. La review, le financement, l’accès au compte, les blocages, les plafonds, les plannings et l’état en temps réel s’appliquent toujours.

Create peut-il démarrer immédiatement une campagne ?

Oui, selon le compte et la campagne. Elle peut aussi passer en review. Inspectez toujours l’état public renvoyé. L’activation CPA ou CPI peut aussi facturer un package de lancement sélectionné non payé.

Puis-je téléverser une image depuis une URL distante ?

Non. Téléversez le fichier image via POST /images. CPAlead renvoie un ID d’image temporaire à usage unique.

Puis-je créer plusieurs offres à la fois ?

Il n’existe pas d’opération de création en lot. Validez et créez une campagne par requête, utilisez un ID externe et une clé d’idempotence distincts, et respectez les limites de débit ainsi que les règles de création du compte.

L’API peut-elle archiver ou supprimer une campagne ?

Non. L’API publique actuelle peut démarrer et mettre en pause les campagnes éligibles, mais n’expose pas l’archivage ni la suppression. Utilisez le tableau de bord annonceur pour l’archivage.

Pourquoi ma mise à jour a-t-elle reçu HTTP 412 ?

La campagne a changé après votre récupération. Récupérez-la à nouveau, examinez les données les plus récentes, fusionnez votre changement voulu et réessayez avec le nouvel ETag.

Pourquoi create a-t-il renvoyé HTTP 409 ?

Lisez le code d’erreur stable. Les causes publiques possibles incluent une clé d’idempotence ou un ID externe réutilisé avec des données différentes, une requête antérieure encore en cours de traitement, la limite de trois campagnes avant dépôt, des restrictions de financement ou de compte, un blocage ou un conflit d’état.

Mon application doit-elle copier les limites de champs de cet article ?

Non. Cet article explique le flux de travail. Votre application doit lire les exigences en direct et le schéma OpenAPI afin que les valeurs actuelles restent la référence.

Fiche d’information Campaign API pour machine

Commencez par lire et valider

L’API Campaign est conçue pour qu’un annonceur puisse commencer prudemment. Donnez à un agent de confiance le guide public et le schéma, accordez l’accès en lecture et validation, et laissez-le préparer une requête sans modifier le compte. Lorsque le JSON est correct et que le propriétaire comprend les effets possibles de review, de diffusion et financiers, n’ajoutez que la permission d’écriture nécessaire pour l’action confirmée suivante.

Ouvrez Campaign API dans le centre Advertiser API pour créer un jeton, ou ouvrez le schéma OpenAPI public de l’API Campaign pour inspecter le contrat actuel. La documentation de l’API Publisher est séparée et couvre la récupération d’offres et les rapports pour les publishers. Si une réponse n’est pas claire, gardez le jeton privé et contactez le support annonceur avec le request ID public et l’ID de campagne.

Vous avez remarqué une erreur ou un aspect de cet article qui nécessite une correction ? Merci de fournir le lien de l'article et contactez-nous. Nous apprécions vos commentaires et nous occuperons du problème rapidement.