Skip to main content
Las operaciones de anuncios reciben la plataforma de anuncios como argumento, por lo que la misma operación funciona en todas las plataformas de anuncios que admite Ayrshare. Actualmente son FACEBOOK e INSTAGRAM. Cada operación llama al endpoint REST de anuncios correspondiente y devuelve su respuesta sin cambios. La autenticación y los límites son los mismos que en REST. Una llamada fallida devuelve un error de GraphQL: extensions.status contiene el estado REST y extensions.code el código de error de Ayrshare cuando el error REST tiene uno. Consulta Errores. Las operaciones de anuncios requieren el complemento Ads. Sin él, cada llamada devuelve un error con extensions.status 403 y extensions.code 399.

​
Operaciones

Todas las operaciones aceptan también un profileKey opcional para actuar sobre un User Profile (perfil de usuario). Todas devuelven la respuesta REST como JSON, por lo que no admiten selección de campos.

​
Listar cuentas publicitarias

Empieza por aquí. Usa los valores de accountId de la respuesta siempre que una operación pida accountId.

​
Buscar opciones de segmentación

kind elige la búsqueda: INTERESTS para la segmentación de audiencia, REGIONS o CITIES para ubicaciones. Cada tipo acepta solo sus propios argumentos. Por ejemplo, countryCode y regionId solo funcionan con CITIES, e INTERESTS requiere search.

​
Listar anuncios

Pasa al menos uno de campaignId, accountId, adId, postId o socialPostId. socialPostId es el ID propio de la publicación en la red, para publicaciones que no se publicaron a través de Ayrshare.

​
Ver cuánto ha costado un anuncio

​
Pausar o reanudar un anuncio

updateAd modifica el gasto publicitario real. PAUSED detiene el gasto, ACTIVE lo reanuda, y DELETED o ARCHIVED retira el anuncio. El mismo estado se aplica también al conjunto de anuncios y a la campaña del anuncio, por lo que cualquier otro anuncio de ese conjunto de anuncios o campaña cambia con él. Una campaña o un conjunto de anuncios al que se adjuntó el impulso con attachTo conserva su propio estado, y el anuncio solo se publica mientras la campaña y el conjunto de anuncios que lo contienen estén activos.

​
Impulsar una publicación

boostPost gasta dinero real de la cuenta publicitaria. Convierte una publicación publicada en un anuncio.
  • Pasa postId (el ID de la publicación en Ayrshare) o socialPostId (el ID propio de la publicación en la red).
  • Obtén accountId de adAccounts.
  • budget.amount está en la moneda de la cuenta publicitaria. Omite budget solo cuando attachTo.adSetId añade el anuncio a un conjunto de anuncios que ya gestionas, que conserva su propio presupuesto. En ese caso, omite también targeting: el conjunto de anuncios conserva su propia segmentación. Consulta Impulsar en una campaña o un conjunto de anuncios existente.
  • schedule, targeting, callToAction, attachTo y status son opcionales. Si omites status y schedule, el anuncio queda activo, empieza de inmediato y no tiene fecha de finalización, por lo que sigue gastando hasta que lo pauses. Establece status: PAUSED o schedule.end para limitarlo.
  • Coloca los ajustes exclusivos de una plataforma en platformOptions, con la plataforma como clave. En Facebook e Instagram, adName y bidAmount son obligatorios ahí, por ejemplo platformOptions: { facebook: { adName: "Autumn sale", bidAmount: 2 } }. Sin ellos, el impulso devuelve un error de campos faltantes. Con attachTo.adSetId, omite bidAmount: el conjunto de anuncios conserva su propia puja.
Algunos argumentos admiten más de una forma, por lo que usan el tipo JSON:
  • accountId acepta una cadena o un número.
  • Las fechas de schedule aceptan una fecha o fecha y hora ISO 8601, como "2026-10-10T09:00:00Z". Usa esa forma en lugar de un número. schedule.end también acepta 0 para indicar que no hay fecha de finalización.
  • Las claves de ubicación aceptan un valor o una lista.
  • targeting.interests acepta IDs como cadenas o números.
  • platformOptions acepta un objeto.
Envía un idempotencyKey nuevo, como un UUID, con cada impulso. Si una llamada agota el tiempo de espera o falla, reinténtala con la misma clave y los mismos argumentos.
  • Si el primer impulso terminó, el reintento devuelve su respuesta en lugar de crear y pagar un segundo anuncio.
  • Si el primer impulso sigue en curso, el reintento devuelve un error con extensions.status 409. Espera y vuelve a intentarlo con la misma clave. No cambies a una clave nueva.
  • Reutilizar una clave con argumentos distintos también devuelve 409.
Para detener el gasto del anuncio, llama a updateAd con status: PAUSED. boostFacebookPost e instagramBoostPost siguen funcionando. Las operaciones por plataforma, como facebookAdAccounts e instagramAds, siguen funcionando y no han cambiado.