Skip to main content
As operações de anúncios recebem a plataforma de anúncios como argumento, então a mesma operação funciona em todas as plataformas de anúncios suportadas pela Ayrshare. Hoje, são FACEBOOK e INSTAGRAM. Cada operação chama o endpoint REST de anúncios correspondente e retorna sua resposta sem alterações. Autenticação e limites são os mesmos do REST. Uma chamada com falha retorna um erro GraphQL: extensions.status traz o status do REST, e extensions.code traz o código de erro da Ayrshare quando o erro REST tiver um. Veja Erros. As operações de anúncios exigem o complemento Ads. Sem ele, toda chamada retorna um erro com extensions.status 403 e extensions.code 399.

​
Operações

Toda operação também aceita um profileKey opcional para agir em nome de um User Profile (perfil de usuário). Todas retornam a resposta REST como JSON, então não aceitam seleção de campos.

​
Listar contas de anúncios

Comece por aqui. Use os valores de accountId da resposta sempre que uma operação pedir accountId.

​
Buscar opções de segmentação

kind define a busca: INTERESTS para segmentação de público, REGIONS ou CITIES para localizações. Cada tipo aceita apenas seus próprios argumentos. Por exemplo, countryCode e regionId funcionam apenas com CITIES, e INTERESTS exige search.

​
Listar anúncios

Informe pelo menos um entre campaignId, accountId, adId, postId ou socialPostId. socialPostId é o id da publicação na própria rede, para publicações que não foram feitas via Ayrshare.

​
Ver quanto um anúncio custou

​
Pausar ou retomar um anúncio

updateAd altera o gasto real com anúncios. PAUSED interrompe o gasto, ACTIVE o retoma, e DELETED ou ARCHIVED encerra o anúncio. O mesmo status também é aplicado ao conjunto de anúncios e à campanha do anúncio, então quaisquer outros anúncios nesse conjunto de anúncios ou campanha mudam junto. Uma campanha ou um conjunto de anúncios ao qual o impulsionamento foi anexado com attachTo mantém o próprio status, e o anúncio só é veiculado enquanto a campanha e o conjunto de anúncios acima dele estiverem ativos.

​
Impulsionar uma publicação

boostPost gasta dinheiro real da conta de anúncios. Ele transforma uma publicação já publicada em um anúncio.
  • Informe postId (o id da publicação na Ayrshare) ou socialPostId (o id da publicação na própria rede).
  • Obtenha accountId em adAccounts.
  • budget.amount está na moeda da conta de anúncios. Omita budget somente quando attachTo.adSetId adicionar o anúncio a um conjunto de anúncios que você já executa, que mantém o próprio orçamento. Nesse caso, omita também targeting: o conjunto de anúncios mantém a sua própria. Consulte Impulsionar em uma campanha ou conjunto de anúncios existente.
  • schedule, targeting, callToAction, attachTo e status são opcionais. Se você omitir status e schedule, o anúncio fica ativo, começa imediatamente e não tem data de término, então continua gastando até você pausá-lo. Defina status: PAUSED ou schedule.end para limitá-lo.
  • Coloque as configurações exclusivas de uma plataforma em platformOptions, usando a plataforma como chave. No Facebook e no Instagram, adName e bidAmount são obrigatórios ali, por exemplo platformOptions: { facebook: { adName: "Autumn sale", bidAmount: 2 } }. Sem eles, o impulsionamento retorna um erro de campos ausentes. Com attachTo.adSetId, omita bidAmount: o conjunto de anúncios mantém o próprio lance.
Alguns argumentos aceitam mais de um formato, por isso usam o tipo JSON:
  • accountId aceita uma string ou um número.
  • As datas de schedule aceitam uma data ou data e hora ISO 8601, como "2026-10-10T09:00:00Z". Use esse formato em vez de um número. schedule.end também aceita 0 para indicar sem data de término.
  • As chaves de localização aceitam um valor ou uma lista.
  • targeting.interests aceita ids como strings ou números.
  • platformOptions aceita um objeto.
Envie um idempotencyKey novo, como um UUID, a cada impulsionamento. Se uma chamada expirar ou falhar, tente novamente com a mesma chave e os mesmos argumentos.
  • Se o primeiro impulsionamento foi concluído, a nova tentativa retorna a resposta dele em vez de criar e pagar por um segundo anúncio.
  • Se o primeiro impulsionamento ainda estiver em andamento, a nova tentativa retorna um erro com extensions.status 409. Aguarde e tente novamente com a mesma chave. Não troque para uma chave nova.
  • Reutilizar uma chave com argumentos diferentes também retorna 409.
Para interromper o gasto do anúncio, chame updateAd com status: PAUSED. boostFacebookPost e instagramBoostPost continuam funcionando. As operações por plataforma, como facebookAdAccounts e instagramAds, continuam funcionando e não foram alteradas.