Skip to main content
Les opérations d’annonces prennent la plateforme publicitaire en argument : la même opération fonctionne donc sur toutes les plateformes publicitaires prises en charge par Ayrshare. Actuellement, il s’agit de FACEBOOK et INSTAGRAM. Chaque opération appelle le point de terminaison REST d’annonces correspondant et renvoie sa réponse telle quelle. L’authentification et les limites sont identiques à REST. Un appel en échec renvoie une erreur GraphQL : extensions.status contient le statut REST, et extensions.code le code d’erreur Ayrshare lorsque l’erreur REST en comporte un. Consultez Erreurs. Les opérations d’annonces nécessitent le module complémentaire Ads. Sans lui, chaque appel renvoie une erreur avec extensions.status 403 et extensions.code 399.

​
Opérations

Chaque opération accepte également un profileKey facultatif pour agir sur un User Profile (profil utilisateur). Toutes renvoient la réponse REST sous forme de JSON : elles n’acceptent donc aucune sélection de champs.

​
Lister les comptes publicitaires

Commencez ici. Utilisez les valeurs accountId de la réponse partout où une opération demande un accountId.

​
Rechercher des options de ciblage

kind détermine la recherche : INTERESTS pour le ciblage d’audience, REGIONS ou CITIES pour les zones géographiques. Chaque type n’accepte que ses propres arguments. Par exemple, countryCode et regionId ne fonctionnent qu’avec CITIES, et INTERESTS nécessite search.

​
Lister les annonces

Transmettez au moins l’un des arguments campaignId, accountId, adId, postId ou socialPostId. socialPostId est l’identifiant de publication propre au réseau, pour les publications qui n’ont pas été publiées via Ayrshare.

​
Voir ce qu’une annonce a coûté

​
Mettre en pause ou réactiver une annonce

updateAd modifie des dépenses publicitaires réelles. PAUSED arrête les dépenses, ACTIVE les reprend, et DELETED ou ARCHIVED retire l’annonce. Le même statut est également appliqué à l’ensemble d’annonces et à la campagne de l’annonce : toutes les autres annonces de cet ensemble d’annonces ou de cette campagne sont donc modifiées en même temps. Une campagne ou un ensemble d’annonces auquel le boost a été rattaché avec attachTo conserve son propre statut, et l’annonce n’est diffusée que tant que la campagne et l’ensemble d’annonces dont elle dépend sont actifs.

​
Sponsoriser une publication

boostPost dépense de l’argent réel sur le compte publicitaire. Elle transforme une publication déjà publiée en annonce.
  • Transmettez postId (l’identifiant de publication Ayrshare) ou socialPostId (l’identifiant de publication propre au réseau).
  • Récupérez accountId depuis adAccounts.
  • budget.amount est exprimé dans la devise du compte publicitaire. Omettez budget uniquement lorsque attachTo.adSetId ajoute l’annonce à un ensemble d’annonces que vous gérez déjà, qui conserve son propre budget. Omettez alors aussi targeting : l’ensemble d’annonces conserve le sien. Consultez Sponsoriser dans une campagne ou un ensemble d’annonces existant.
  • schedule, targeting, callToAction, attachTo et status sont facultatifs. Si vous omettez status et schedule, l’annonce est active, démarre immédiatement et n’a pas de date de fin : elle continue donc de dépenser jusqu’à ce que vous la mettiez en pause. Définissez status: PAUSED ou schedule.end pour la limiter.
  • Placez les paramètres propres à une seule plateforme sous platformOptions, avec la plateforme comme clé. Sur Facebook et Instagram, adName et bidAmount y sont obligatoires, par exemple platformOptions: { facebook: { adName: "Autumn sale", bidAmount: 2 } }. Sans eux, la sponsorisation renvoie une erreur de champs manquants. Avec attachTo.adSetId, omettez bidAmount : l’ensemble d’annonces conserve sa propre enchère.
Certains arguments acceptent plusieurs formes : ils utilisent donc le type JSON :
  • accountId accepte une chaîne ou un nombre.
  • Les dates de schedule acceptent une date ou une date-heure ISO 8601, comme "2026-10-10T09:00:00Z". Utilisez cette forme plutôt qu’un nombre. schedule.end accepte aussi 0 pour indiquer l’absence de date de fin.
  • Les clés de localisation acceptent une valeur ou une liste.
  • targeting.interests accepte des identifiants sous forme de chaînes ou de nombres.
  • platformOptions accepte un objet.
Envoyez un nouvel idempotencyKey, par exemple un UUID, à chaque sponsorisation. Si un appel expire ou échoue, réessayez avec la même clé et les mêmes arguments.
  • Si la première sponsorisation s’est terminée, la nouvelle tentative renvoie sa réponse au lieu de créer et de payer une seconde annonce.
  • Si la première sponsorisation est toujours en cours, la nouvelle tentative renvoie une erreur avec extensions.status 409. Patientez, puis réessayez avec la même clé. Ne passez pas à une nouvelle clé.
  • Réutiliser une clé avec des arguments différents renvoie également 409.
Pour arrêter les dépenses de l’annonce, appelez updateAd avec status: PAUSED. boostFacebookPost et instagramBoostPost fonctionnent toujours. Les opérations propres à chaque plateforme, comme facebookAdAccounts et instagramAds, fonctionnent toujours et restent inchangées.