Vue d'ensemble
Vue d'ensemble
L'API annonceurs agit pour une seule organisation : celle qui possède la clé. Elle liste et met à jour les campagnes, les annonces, les stats et le portefeuille. Les conversions côté serveur passent par un endpoint séparé. Un serveur MCP appelle cette même API.
Il n'y a pas d'accès staff ni d'accès inter-organisations. Une ressource d'une autre organisation est introuvable.
URL de base
https://tyfrhxfejrawgdlhryfu.supabase.co/functions/v1/advertiser-api
Les chemins sont ajoutés directement. Il n'y a pas de préfixe /v1.
curl 'https://tyfrhxfejrawgdlhryfu.supabase.co/functions/v1/advertiser-api/campaigns' \
-H 'Authorization: Bearer idl_adv_xxx'
| Fonction | URL |
|---|---|
| API annonceurs | https://tyfrhxfejrawgdlhryfu.supabase.co/functions/v1/advertiser-api |
| API conversions | https://tyfrhxfejrawgdlhryfu.supabase.co/functions/v1/conversions-api |
| Serveur MCP | https://tyfrhxfejrawgdlhryfu.supabase.co/functions/v1/advertiser-mcp |
Le document OpenAPI liste chaque champ et chaque code HTTP : advertiser-api.yaml.
Clés API
Créez une clé dans Ads Manager, sous Paramètres → Clés API. Seul un propriétaire ou un admin de l'organisation peut créer ou révoquer une clé. Une organisation peut avoir 25 clés actives.
La clé complète n'est affichée qu'une fois, à la création. Elle commence par idl_adv_. Ensuite, le tableau de bord ne montre que le préfixe.
Envoyez-la à chaque requête, de l'une des deux façons :
-H 'Authorization: Bearer idl_adv_xxx'
-H 'x-api-key: idl_adv_xxx'
Une clé absente, mal formée ou révoquée renvoie 401.
{
"error": {
"code": "unauthorized",
"message": "Invalid API key"
}
}
Droits
Une clé a un ou plusieurs droits parmi conversions, read et write. write n'inclut pas read. Une clé créée sans liste de droits explicite n'a que conversions.
| Droit | Autorise |
|---|---|
read | GET campagnes, annonces, stats, portefeuille, transactions |
write | POST et PATCH campagnes, annonces, pause, reprise, lien Checkout de dépôt |
conversions | POST sur l'endpoint de conversions uniquement |
Le mauvais droit renvoie 403 avec insufficient_scope.
Limite de débit
advertiser-api autorise 120 requêtes par clé et par 60 secondes. La fenêtre est fixe. Un 429 inclut Retry-After (secondes) et :
| En-tête | Sens |
|---|---|
X-RateLimit-Limit | Requêtes autorisées dans la fenêtre (120) |
X-RateLimit-Remaining | Requêtes restantes après celle-ci |
X-RateLimit-Reset | Heure Unix de fin de fenêtre |
L'endpoint de conversions n'utilise pas ce budget. POST /ads/from-url partage aussi la limite de l'extracteur de pages : 10 requêtes par organisation et par heure.
Le serveur MCP utilise les mêmes 120 requêtes par minute. Il authentifie une fois par appel HTTP et ne compte pas cet appel deux fois.
Idempotency-Key
Les requêtes POST acceptent Idempotency-Key (1 à 255 caractères ASCII imprimables). La même clé et le même corps rejouent la première réponse pendant 24 heures. La clé est limitée à la clé API.
| Situation | Statut | error.code |
|---|---|---|
| Même clé, corps différent | 409 | idempotency_key_reused |
| Même clé, première requête encore en cours | 409 | idempotency_in_progress |
| Clé hors du format | 400 | invalid_request |
PATCH n'utilise pas cet en-tête.
Erreurs
Les erreurs de l'API annonceurs ont cette forme :
{
"error": {
"code": "not_found",
"message": "Campaign not found"
}
}
Les erreurs d'activation peuvent aussi inclure campaign_id et dashboard_url.
| Statut | code | Quand |
|---|---|---|
400 | invalid_request | Requête, corps ou id invalide |
401 | unauthorized | Clé absente ou inconnue |
403 | insufficient_scope | La clé n'a pas read ou write |
404 | not_found | Chemin inconnu, ou ressource hors de cette organisation |
405 | method_not_allowed | Verbe refusé. L'en-tête Allow liste les verbes |
409 | first_campaign_requires_dashboard_validation | La première campagne API de l'organisation ne peut pas être activée ici |
409 | insufficient_balance | Solde du portefeuille à zéro |
409 | ads_pending_moderation | Aucune annonce n'est encore approuvée |
409 | ad_required | La campagne n'a pas d'annonce livrable |
409 | no_active_ad_set | La campagne n'a pas d'ensemble d'annonces activable |
429 | rate_limited | Plus de 120 requêtes dans la fenêtre, ou limite de pages |
500 | internal_error | Erreur serveur |
503 | not_ready | L'API, Checkout ou l'extraction n'est pas configurée |
Les jours et les filtres de dates sont en UTC. Les montants du portefeuille, des transactions, des stats, des budgets et des enchères sont des centimes de la devise du portefeuille. Cette devise est EUR, sauf si la ligne du portefeuille stocke un autre code à trois lettres. Les transactions et les jours de stats n'incluent pas de champ devise.