CPAlead Full Campaign API : créer et gérer des offres

La Full Campaign API de CPAlead permet à un annonceur self-serve vérifié d'utiliser du code, un API-capable AI agent, un MCP server, une GPT Action ou un plugin pour travailler avec des campagnes CPA, CPI et CPC. Selon les permissions accordées, un authorized client peut lire les requirements actuels, valider une campagne complète avant de l'enregistrer, importer un creative, créer une campagne, lister et récupérer des campagnes, modifier une campagne avec version protection, et démarrer ou mettre en pause explicitement une eligible campaign.

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 Full Campaign API 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.

Choisissez entre Temporary AI Campaign Draft Access, Full Campaign API et Offer API Import

• Temporary AI Campaign Draft Access: Pour ChatGPT ordinaire et les chats IA similaires. Avant le premier dépôt annonceur réussi, un private link valable quatre heures peut valider et enregistrer jusqu'à trois brouillons de campagne inactifs. Après un dépôt annonceur réussi, le lien n'a plus de limite totale de brouillons de campagne. Chaque compte peut avoir jusqu'à 10 brouillons de campagne non terminés en attente en même temps. Il ne peut pas voir ni gérer les campagnes existantes, importer, accepter les conditions ou les packages, dépenser des fonds, soumettre, démarrer, mettre en pause ou activer. Ouvrez Temporary AI Campaign Draft Access.
• Full Campaign API: Pour un API-capable agent, une GPT Action, un MCP server, un plugin ou une intégration capable de protéger un bearer token. Selon les scopes accordés, elle peut valider, importer, créer, lire, modifier, démarrer et mettre en pause des campagnes. Ouvrez Full Campaign API.
• Offer API Import: Un workflow distinct du advertiser dashboard qui récupère des offres depuis un compatible external feed et mappe ses champs dans CPAlead. Ouvrez Offer API Import.

Utilisez l'option protégée de brouillon de campagne lorsqu'un chat IA ordinaire vous aide à préparer une nouvelle offre. Utilisez Full Campaign API lorsqu'un authenticated client a besoin de structured campaign-management abilities. Utilisez Offer API Import lorsque CPAlead doit récupérer un compatible feed. Ne donnez à aucun outil un accès plus large que celui nécessaire à sa tâche.

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: Rémunère une seule action ou plusieurs événements. L’URL de suivi doit contenir {CLICK_ID}. Une URL d’aperçu, un plafond quotidien et un forfait de lancement font partie de la requête de création. Un objectif de conversion est obligatoire pour une campagne à paiement unique ; une campagne à événements définit chaque action rémunérée dans sa liste d’événements.
• CPI: Rémunère une installation ou une action dans l’application, ou plusieurs événements. Utilise {CLICK_ID} et ajoute des options propres aux applications, comme la plateforme de l’appareil, la méthode de suivi, les versions de système d’exploitation prises en charge et la gestion des proxys. Ajoutez un événement d’installation explicite si les installations doivent être rémunérées dans une campagne à événements.
• 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.

Tous les montants de l’API des campagnes sont en USD et les horaires de l’API utilisent UTC. Pour les campagnes CPA et CPI, un paiement inférieur à $10.00 exige un plafond quotidien d’au moins 20. Un paiement de $10.00 ou plus permet un plafond quotidien aussi bas que 5. Pour une campagne à événements, utilisez la somme de tous les paiements des événements pour appliquer ces règles de plafond minimum. Consultez les exigences actuelles avant de choisir les prix et les plafonds.

É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.

Choisissez un paiement unique ou plusieurs événements rémunérés

CPA et CPI prennent en charge conversion_mode avec les valeurs single et events. Consultez conversion_modes et event_rules dans les exigences avant de choisir. CPC rémunère les clics et ne prend pas en charge les événements rémunérés.

Avec une seule action rémunérée, le participant reçoit un paiement de conversion. Avec plusieurs événements rémunérés, vous définissez un paiement fixe distinct en USD pour chaque action. Par exemple, payez $0.50 pour la création d’un compte et $1.25 pour la réalisation du tutoriel. Le total maximum est de $1.75 par participant ; il ne s’agit pas d’un paiement supplémentaire.

Pour une requête CPA complète comme dans l’exemple ci-dessus, utilisez ces champs d’événement et ces tarifs. Conservez les autres champs obligatoires de la campagne. Pour CPI, choisissez également une plateforme d’application et une méthode de suivi prises en charge. Remplacez toutes les actions, tous les prix et tous les paramètres de ciblage de l’exemple par vos propres choix vérifiés.

{
  "conversion_mode": "events",
  "events": [
    {"id": 1, "name": "Create an account", "description": "Finish registration.", "payout": "0.50"},
    {"id": 2, "name": "Complete the tutorial", "description": "Finish all tutorial steps.", "payout": "1.25"}
  ],
  "pricing": {"currency": "USD", "payout": "1.75", "daily_cap": 20}
}

Un programme comprend 1–10 événements. Chacun doit avoir un nom et un paiement positif comportant au maximum deux décimales ; les instructions de réalisation sont facultatives. Les identifiants des nouveaux événements peuvent être omis pour que CPAlead les attribue. Conservez les identifiants numériques renvoyés pour les mises à jour et les postbacks ultérieurs. Lors de l’enregistrement d’événements, pricing.payout peut être omis ; s’il est fourni, il doit être égal à la somme de tous les paiements des événements. creative.conversion_goal est facultatif pour les campagnes à événements, et targeting.tools_only doit être false.

Chaque événement peut être rémunéré une fois par participant, dans n’importe quel ordre, dans les 30 jours suivant le clic initial. Le plafond quotidien comptabilise un participant lors de son premier événement rémunéré. Les événements suivants ne sont pas comptés à nouveau. La mise en pause ou l’atteinte du plafond arrête le nouveau trafic, mais n’annule pas les récompenses admissibles restant à payer. Gardez suffisamment de fonds pour les couvrir ; les réalisations en attente peuvent dépasser le plafond de trafic d’une journée.

Suivez et mettez à jour les campagnes à événements

Pour les postbacks standard, envoyez votre propre identifiant de postback, le click_id d’origine enregistré et une valeur qui identifie la récompense accomplie. Ajoutez campaign_id pour plus de protection ; il doit correspondre à la campagne du clic d’origine. Utilisez l’URL générée pour votre compte et n’inventez jamais d’identifiants.

Un solde insuffisant renvoie HTTP 503 avec low_balance. Ajoutez des fonds, puis réessayez le même événement après le délai Retry-After. Utilisez le test guidé avant d’envoyer du trafic.

Pour les outils de suivi standard, l’API complète de campagnes et l’accès temporaire aux brouillons de campagne par IA acceptent le champ d’événement facultatif postback_event_value lorsque event_rules.event_fields le mentionne. Par exemple, "postback_event_value": "tutorial_complete" ajoute un code de suivi à cette récompense. Le nom de l’événement fonctionne toujours. AppsFlyer conserve son champ distinct appsflyer_event_name.

CPI avec AppsFlyer utilise la configuration de partenaire intégré de CPAlead. Ne collez pas le postback annonceur standard dans AppsFlyer. Associez chaque identifiant numérique d’événement enregistré à l’identifiant d’événement partenaire. Le champ facultatif appsflyer_event_name doit correspondre exactement au nom utilisé dans le SDK ; les noms répétés nécessitent des identifiants partenaires pour identifier la récompense. Une seule récompense peut utiliser install, et son callback doit envoyer explicitement event_type=install. Consultez les modèles dédiés dans la configuration du postback. Enregistrer une campagne via l’API ne configure pas AppsFlyer.

Un PATCH contenant events remplace toute la liste ; si ce champ est omis, la liste est conservée. Gardez chaque numéro d’événement enregistré, récupérez l’ETag actuel et envoyez If-Match. Après une participation réelle ou une conversion, le mode de paiement, la méthode de suivi, l’identité de l’application AppsFlyer et les détails des récompenses restent verrouillés. Seule une valeur de suivi standard supplémentaire peut être corrigée ; cette modification est enregistrée et ne change pas la récompense. Copiez la campagne pour modifier ses récompenses. Les clics de test guidé seuls ne verrouillent pas les événements.

Les campagnes à événements peuvent être diffusées via Offerwall V2, l’API d’offres pour éditeurs et des liens directs. Offerwall V2 nécessite un identifiant utilisateur d’éditeur stable dans subid. Les participants qui reviennent conservent leur clic initial et leur échéance. Les murs d’offres classiques, les lockers et les pixels de suivi ne prennent pas en charge ces campagnes à événements.

Préparez des campagnes à événements avec l’IA ou un flux d’offres

L’accès temporaire aux brouillons de campagnes par IA permet de préparer un programme d’événements complet à vérifier dans le formulaire CPA/CPI habituel. Il ne peut pas créer une campagne active, configurer le suivi, accepter les conditions ou les forfaits de lancement, téléverser une image ni dépenser de l’argent. Un lien privé reste valable quatre heures. Avant un premier dépôt réussi de l’annonceur, il peut enregistrer jusqu’à trois brouillons de campagnes ; après un dépôt réussi, il n’y a plus de limite totale par lien. Chaque compte peut avoir jusqu’à 10 brouillons de campagnes inachevés en attente, et les brouillons inachevés expirent après sept jours.

L’import d’offres par API peut préparer des listes d’événements depuis events, event_payouts ou goals ; la correspondance personnalisée accepte d’autres chemins. Les identifiants numériques valides de la source sont conservés. Les sources utilisant du texte ou des noms nécessitent une valeur de suivi enregistrée et un numéro d’événement CPAlead attribué. Chaque récompense nécessite un nom et un paiement fixe en USD. Vérifiez les numéros, les valeurs de suivi et toute la liste dans l’aperçu. Si l’aperçu ne peut pas préparer la liste complète, corrigez la correspondance avant de continuer. Charger un flux prépare un nouveau formulaire et ne modifie pas les campagnes existantes.

É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.

Prompt pour un API-capable AI agent ou une intégration

Ce prompt suppose que le client peut joindre un private bearer token aux authenticated HTTPS requests. Partagez d'abord le guide et l'OpenAPI URL, puis configurez le token dans les private secret settings de la plateforme du client. N'insérez pas de vrai token dans ce prompt public. Si un chat IA ordinaire indique qu'il ne peut pas envoyer d'authenticated requests, révoquez le token inutile et utilisez plutôt Temporary AI Campaign Draft Access.

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

Puis-je utiliser Full Campaign API dans ChatGPT ordinaire ?

Uniquement lorsque ChatGPT dispose d'une GPT Action configurée ou d'une autre authenticated integration capable d'envoyer le bearer token dans un Authorization header. Un chat ordinaire ne peut généralement pas le faire. Utilisez plutôt Temporary AI Campaign Draft Access. Elle peut uniquement préparer et enregistrer des brouillons de campagne inactifs ; vous les examinez et les terminez dans CPAlead.

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.