Descripción general de la API Post - Ayrshare API Documentation

El endpoint post te permite publicar en las siguientes redes sociales: Bluesky, Facebook, Google Business Profile, Instagram, LinkedIn, Pinterest, Reddit, Snapchat, Telegram, TikTok, X/Twitter y YouTube. Existen muchas opciones para personalizar tu publicación, como programar publicaciones, añadir hashtags automáticos (Auto Hashtag), programación automática de publicaciones (Auto Schedule) y más. Suelen utilizarla las agencias cuando varios interesados deben aprobar una publicación antes de publicarla. Empieza a publicar con el endpoint POST /post.

Flujo de aprobación

Si tu flujo de publicación requiere aprobación antes de enviar una publicación, establece el campo requiresApproval a true. Esto equivale a pausar la publicación hasta que el parámetro approved se establezca en true.

Ejemplo de flujo de aprobación

La publicación tendrá el estado “awaiting approval” hasta que el parámetro approved se establezca en true mediante el endpoint PATCH /post.

Publicar con parámetros

Publica usando el endpoint /post con el campo requiresApproval en true. También puedes incluir parámetros estándar como scheduleDate.

Estado: awaiting approval

La publicación estará en estado “awaiting approval” y se mantendrá en espera hasta que se conceda la aprobación.

Aprobar la publicación

Actualiza la publicación con la operación PATCH /post estableciendo el campo approved en true. Ahora la publicación se enviará a la hora programada.

Usar notas

Opcional: establece notes en la publicación como referencia, por ejemplo indicando quién debe aprobar la publicación.

Publish the Post with Approval

{
  "requiresApproval": true,
  "notes": "need approval by John Smith" // optional
}

Si se incluye scheduleDate y la fecha está en el pasado, la publicación se publicará inmediatamente al ser aprobada.

Video del flujo de aprobación

Consulta el video de abajo para ver un ejemplo del flujo de aprobación.

Hashtags automáticos (Auto Hashtags)

Añade los hashtags más relevantes a tu publicación. autoHashtag es un objeto o un Boolean (ver abajo) con los siguientes parámetros:

max: (opcional) Número entero de hashtags a añadir, rango 1-10. Por defecto 2.
position: (opcional) String “auto” o “end”. “auto” añade los hashtags dentro de la publicación o al final. “end” añade los hashtags solo al final.

Se requiere un plan de pago.

{
  "hashtags": {
    "max": 3, // optional: Integer range 1-10
    "position": "auto" // optional: String "auto" or "end"
  }
}

Si no quieres enviar ninguna de las opciones anteriores, pasa el valor booleano true en vez de un objeto.

{
  "autoHashtag": true
}

Auto Repost

Vuelve a publicar automáticamente tu contenido varias veces a intervalos regulares, creando contenido evergreen que se mantiene fresco y visible para tu audiencia. Se requiere un plan de pago. Parámetros:

repeat: (obligatorio) Número de veces que se volverá a publicar el contenido. Debe estar entre 1 y 10.
days: (obligatorio) Número de días entre cada repetición. Debe ser al menos 2 días.
startDate: (opcional) Cuándo iniciar la programación de reposts, en formato ISO-8601 UTC. Si no se especifica, la primera publicación se publicará inmediatamente. Debes usar el parámetro startDate en lugar del parámetro scheduleDate de nivel superior.

Auto Repost

{
  "repeat": 2, // min 2, max 10
  "days": 5, // min 2
  "startDate": "2021-07-08T12:30:00Z"
}

La respuesta incluirá todos los reposts programados y un autoRepostId para cada uno.

Auto Repost Response

{
  "status": "scheduled",
  "scheduleDate": "2025-06-13T12:30:00.000Z",
  "id": "eIT96IYEodNuzU4oMmwG",
  "refId": "9abf1426d6ce9122ef11c72bd",
  "autoRepostId": "F5wdoaOAAGtDQVciExSxL",
  "post": "The most important things are the hardest to say - Stephen King"
}

Al crear un auto repost se asigna un autoRepostId para hacer seguimiento de esa serie de publicaciones. Puedes obtener todos los reposts de una publicación mediante la llamada History usando el autoRepostId. Si necesitas eliminar un repost, puedes usar la llamada DELETE con el ID de la publicación.

Importante: cuando uses auto-repost, asegúrate de seguir las pautas de frecuencia de publicación de cada red social para evitar restricciones en la cuenta.Nota: la funcionalidad autoRepost no se puede usar junto con scheduleDate. Si incluyes ambos parámetros, scheduleDate tendrá prioridad y autoRepost se ignorará. Usa el parámetro startDate en su lugar.

Primer comentario

Añade automáticamente un primer comentario, con contenido multimedia, después de publicar la publicación. En TikTok el comentario se difiere hasta que el video termine de procesarse (consulta Tiempo de procesamiento del primer comentario). Publicar el primer comentario en tu propia publicación puede ayudar a impulsar la interacción y marcar el tono de la conversación posterior.

{
  "firstComment": {
    "comment": "My first comment", // required
    "mediaUrls": ["https://..."] // Facebook, LinkedIn, and X/Twitter only
  }
}

Tiempo de procesamiento del primer comentario

Para la mayoría de redes sociales, la respuesta de la API se retrasa porque nuestro sistema debe (1) esperar a que la publicación original esté totalmente publicada y luego (2) añadir el comentario a esa publicación ya publicada. Este proceso secuencial añade aproximadamente 20 segundos de retraso. TikTok se gestiona de forma diferente. TikTok procesa los videos de forma asíncrona, por lo que el id de la publicación es "pending" hasta que el webhook post.publish.publicly_available de TikTok resuelve el id real del video (consulta Procesamiento en TikTok). Por eso la respuesta de /post devuelve el primer comentario de TikTok con status: "pending" de inmediato, y el comentario se publica automáticamente una vez que TikTok termina de procesar y se dispara el webhook de Scheduled Action tikTokPublished. TikTok no garantiza un tiempo de procesamiento, por lo que no hay un retraso fijo. Nota importante sobre TikTok: para que los primeros comentarios funcionen correctamente en TikTok, el parámetro visibility de la publicación debe estar en public. Un video que no sea público nunca recibe el webhook publicly_available, por lo que su primer comentario no puede publicarse; en ese caso Ayrshare devuelve un error de comentario en lugar de dejarlo pendiente.

Publicaciones idempotentes

La idempotencia es una funcionalidad opcional que garantiza que una petición solo se ejecute una vez, incluso si se envía varias veces por accidente. Al publicar contenido con la API, puedes incluir un parámetro opcional idempotencyKey en el cuerpo de la petición para identificar la operación de forma única. Esto te permite reintentar de forma segura la petición sin riesgo de crear publicaciones duplicadas. Para usar la idempotencia, añade el parámetro idempotencyKey al cuerpo JSON de la petición POST a /post:

Idempotency Key

{
  "idempotencyKey": "Unique Key"
}

El valor de idempotencyKey debe ser una cadena única por User Profile. Si se hace una petición con el mismo idempotencyKey para un User Profile determinado, independientemente del estado de la publicación (success, error, pending o eliminada), se devolverá un error indicando que se encontró una clave duplicada.

La API debe primero aceptar y procesar la petición POST para almacenar la clave de idempotencia y comprobar duplicados. Sin embargo, si se envían varias peticiones POST con el mismo idempotencyKey simultáneamente o si están programadas para la misma hora de publicación, la API puede no detectar las claves duplicadas. Esto se debe a que la API procesa esas peticiones concurrentes o programadas para el mismo instante en paralelo, antes de tener oportunidad de registrar la clave de idempotencia de cualquiera de ellas. Como resultado, no hay garantía de que se detecten claves idempotentes duplicadas en esos escenarios de envío simultáneo o ejecución simultánea de publicaciones programadas.

Usar idempotencia ayuda a evitar la creación accidental de publicaciones duplicadas al reintentar peticiones fallidas o gestionar problemas de red. Aun así, sigue siendo recomendable implementar un manejo de errores y mecanismos de reintento adecuados en tu aplicación para gestionar posibles fallos con elegancia.

Requisitos de imagen y video

La publicación de imágenes y videos tiene requisitos distintos para cada red, pero no te preocupes. Nuestro sistema verifica tu publicación antes de enviarla, por lo que recibirás una respuesta de error si algo no está bien. Consulta el siguiente enlace con los detalles sobre las pautas de imagen y video.

Pautas de imagen y video

URL válida

Asegúrate de que tu(s) URL(s) de medios sean válidas y accedan directamente al archivo multimedia. Una primera prueba es abrir la URL en un navegador. Si la imagen no carga o no se puede descargar en un navegador, es muy probable que falle. Por ejemplo, una URL de DropBox que abre la aplicación web de DropBox no funcionará.

Si tienes una URL de compartir de Google Drive o una URL de compartir de Dropbox, puedes usar simplemente esa URL en el parámetro mediaUrls al publicar una publicación o un comentario. Ayrshare convertirá automáticamente la URL de compartir en un enlace de descarga.

Verificamos la URL del medio realizando una petición HEAD. Asegúrate de que el proveedor de alojamiento no esté bloqueando la petición HEAD o la publicación fallará con un error 403. Por ejemplo, aquí tienes una petición HEAD a la URL del medio:

Fetch HEAD Request

const run = async () => {
  const url = "https://img.ayrshare.com/012/gb.jpg";
  return await fetch(url, {
    method: "HEAD"
  })
    .then((res) => {
      if (res.ok) {
        return console.log("Success:", res.status, res.statusText);
      } else {
        return console.error("Error:", res.status, res.statusText, res);
      }
    })
    .catch((error) => {
      return console.error("Error Catch:", error);
    });
};

run();

Protección automática de medios

Ayrshare incluye una protección de medios integrada que puede detectar y resolver ciertos problemas de entrega de medios durante la publicación. Cuando una publicación tiene éxito pero se detectó y resolvió algún problema con el contenido, cada entrada afectada en postIds[] incluye un objeto opcional contentIssues para que puedas identificar y arreglar el problema subyacente:

{
    "postIds": [
        {
            "status": "success",
            "platform": "instagram",
            "id": "17878176260289172",
            "postUrl": "https://www.instagram.com/p/CP1dI9Hp_WO/",
            "contentIssues": {
                "originMediaHostFailed": true,
                "details": ["Media URL could not be retrieved by the social network. Successfully posted using Ayrshare automated media protection."]
            }
        }
    ]
}

Si ves originMediaHostFailed en tus respuestas, revisa la configuración de tu alojamiento de medios. Consulta Meta Media Crawler Blocked para conocer causas y soluciones habituales.

Espacios y caracteres especiales

Te recomendamos evitar lo siguiente en tus URLs de medios:

Espacios en la URL.
Espacios codificados como URL en la URL.
Caracteres especiales en la URL aunque estén codificados como URL, como acentos, p. ej. é.

Por ejemplo:

https://img.ayrshare.com/012/test .webp

Esta URL falla por el espacio en test .webp. Tampoco recomendamos usar espacios codificados como URL, como %20, en la URL; esto también puede causar problemas con algunas redes sociales. Y esta imagen de Unsplash:

https://unsplash.com/photos/a-house-in-the-middle-of-a-field-with-trees-in-the-background-znbmh2-cIj0

Esta imagen de Unsplash falla porque no accede directamente a la imagen, sino que muestra una aplicación web.

Sanea los nombres de archivo y las URLs

Puedes sanear los nombres de archivo con una expresión regular como /[^a-z0-9\/\.]/gi.

const sanitizeFileName = (url) => url.replace(/[^a-z0-9\/\.]/gi, "_");
sanitizeFileName("tést .webp"); // t_st_.webp

o sanear una URL

const sanitizeUrl = (url) => {
  const [protocol, rest] = url.split("://");
  const [domain, ...path] = rest.split("/");
  const sanitizedPath = path.join("/").replace(/[^a-z0-9\/\.]/gi, "_");
  return `${protocol}://${domain}/${sanitizedPath}`;
};

// Output: https://img.ayrshare.com/012/t_st_.webp
sanitizeUrl("https://img.ayrshare.com/012/tést .webp");

Información adicional

Si haces alojamiento propio, asegúrate de que la URL sea accesible externamente y no requiera permisos especiales.
A continuación verás cómo gestionar videos con extensiones desconocidas, como suele pasar con URLs firmadas de AWS S3.
Si usas una URL firmada, como S3, recomendamos establecer una caducidad de al menos 7 días. Esto permite a nuestro equipo ayudarte con cualquier duda al publicar.
Prueba si la URL del medio existe con nuestras herramientas de verificación de medios.

Velocidad de descarga

Asegúrate de que tu alojamiento de medios tenga una conexión rápida, especialmente en descarga. Puedes probar el rendimiento de tu alojamiento en pingdom. Recomendamos al menos una calificación B.

Extensión de video

Si tu URL no termina con una extensión de video conocida como mp4, puedes usar el campo isVideo: true en la publicación para especificar que mediaUrl es un video. Ayrshare intentará determinar el tipo de archivo, como MOV. Sin embargo, recomendamos terminar explícitamente el archivo de video con una extensión conocida, como mp4, ya que tiene una mayor tasa de éxito con las redes sociales.

Solo imagen o video

Algunas redes sociales admiten enviar contenido multimedia sin texto en la publicación. Si no quieres incluir texto en la publicación, envía una cadena vacía: post: "" Las siguientes redes sociales admiten publicaciones sin texto: Facebook, Instagram, LinkedIn, Threads, TikTok y X/Twitter.

Pruebas con imágenes y videos

Considera usar generar texto aleatorio e imagen o video aleatorios para acelerar tus pruebas. ¡Deja de intentar pensar en algo distinto para cada publicación de prueba!

Saltos de línea

Si quieres saltos de línea (nuevas líneas) en una publicación, usa el salto de línea invisible \u2063\n. Por ejemplo, This is a new\u2063\nline.También recomendamos probarlo en Postman para ver cómo se traduce el salto de línea en tu lenguaje preferido. Por ejemplo, PHP suele usar solo \n.Algunas redes sociales no admiten actualmente saltos de línea en el texto de la publicación.

Publicaciones multiplataforma y medios

Esta funcionalidad te permite personalizar el contenido y los medios de tu publicación para diferentes redes sociales en una sola llamada a la API. Puedes especificar texto e imágenes únicos para cada plataforma usando objetos en los campos post y mediaUrls.

Usa una estructura de objeto para los campos post y/o mediaUrls.
Especifica contenido por plataforma usando los nombres de plataforma como claves.
Incluye una clave default para el contenido que se usará en las plataformas no especificadas explícitamente.

{
  "post": {
    "instagram": "Great IG pic!",
    "facebook": "Great FB pic!",
    "default": "Great default pic!"
  },
  "platforms": ["instagram", "facebook", "linkedin"],
  "mediaUrls": {
    "instagram": "https://img.ayrshare.com/012/gb.jpg",
    "linkedin": "https://img.ayrshare.com/012/gb.jpg",
    "default": "https://img.ayrshare.com/012/gb.jpg"
  }
}

En el ejemplo anterior:

Instagram usará su texto y URL de imagen específicos.
Facebook usará su texto específico y la URL de imagen por defecto.
LinkedIn usará el texto por defecto y su URL de imagen específica.

Si necesitas publicar varias imágenes en distintas plataformas, crea publicaciones separadas para cada plataforma en lugar de usar esta estructura multiplataforma.

Profile Keys

Publica en nombre del usuario proporcionando las Profile Keys de los usuarios como parámetro del cuerpo y los datos adicionales en la respuesta. Se requiere el Business Plan o el Enterprise Plan.

Profiles

Publicaciones con texto enriquecido

Puedes añadir texto enriquecido como ”𝓗𝓮𝓵𝓵𝓸, how about a little 𝗯𝗼𝗹𝗱 𝘁𝗲𝘅𝘁 and 𝘪𝘵𝘢𝘭𝘪𝘤𝘴 𝘵𝘦𝘹𝘵 and an x₂?”. Puedes usar texto enriquecido en redes como Twitter, Facebook, LinkedIn, Telegram e Instagram. Si publicas en Reddit, usa el formato Markdown de Reddit. Se utilizan elementos HTML para especificar el tipo de texto enriquecido, que se traduce a unicode. Por ejemplo:

{
    "post": "<var>Hello</var>, how about a little <b>bold text</b> and <i>italics text</i> and an x<sub>2</sub>?"
    "platforms": ["twitter"]
}

Elementos HTML

HTML	Ejemplo
<b>Nice One!</b>	Nice One!
<strong>Hello, world!</strong>	Hello, world!
<em>World</em>	World
normal <i>italics <b>bold italics</b></i>	normal italics bold italics
`<b>Hello</b>, world!`	`Hello, world!`
`<b>Hello</b>, world!`	`Hello``, world!`
<samp>123</samp>	𝟷𝟸𝟹
<var>Hello</var>	𝓗𝓮𝓵𝓵𝓸
x<sub>2</sub>	x₂
x<sup>2</sup>	x²

Códigos CSS

Código	Ejemplo	Resultado
\u00B0	It’s 25\u00B0C today!	It’s 25°C today!
\u2063\n	This is a new\u2063\nline.	This is a new line.

Publicaciones programadas

Crear publicaciones programadas

Puedes programar publicaciones futuras especificando el parámetro scheduleDate con la fecha y hora en Zulu/UTC. La hora Zulu, también conocida como Tiempo Universal Coordinado (UTC), es el estándar mundial de tiempo. Por ejemplo, usa el formato YYYY-MM-DDThh:mm:ssZ y envíalo como 2026-07-08T12:30:00Z. Consulta utctime para ver más ejemplos.

{
  "post": "Hello, world!",
  "mediaUrls": ["https://img.ayrshare.com/012/gb.jpg"],
  "platforms": ["facebook", "instagram"],
  "scheduleDate": "2023-07-08T12:30:00Z"
}

Consulta https://www.utctime.net/ para ver cómo convertir tu hora local a la hora Zulu/UTC. Si la fecha programada está en el pasado, la publicación se enviará de inmediato.

Si se incluye un mediaUrl con una publicación programada, el archivo multimedia debe estar disponible en el momento de publicación programado. Por ejemplo, si la publicación está programada para el 5 de marzo de 2026, el archivo multimedia debe estar disponible el 5 de marzo de 2026.

Gestión de errores en publicaciones programadas frente a inmediatasHay una diferencia importante en cómo se manejan los errores de validación entre las publicaciones inmediatas y las programadas:

Publicaciones inmediatas
- Al publicar de forma inmediata (sin scheduleDate), si una plataforma no pasa las comprobaciones de validación, las demás plataformas se seguirán procesando. Por ejemplo, si una publicación supera el límite de caracteres de Twitter pero es válida en Facebook e Instagram, fallará en Twitter pero se publicará igualmente en Facebook e Instagram.
Publicaciones programadas
- Al programar publicaciones para publicación futura (con scheduleDate), todas las plataformas deben superar las comprobaciones de validación iniciales antes de programar la publicación. Si alguna plataforma no supera esas comprobaciones previas, se rechazará la operación completa y se devolverá un error de inmediato.
- Sin embargo, algunos errores específicos de plataforma pueden no detectarse hasta el momento real de la publicación. En esos casos, la publicación programada intentará publicarse en todas las plataformas, y los fallos individuales por plataforma se reportarán en los resultados finales sin afectar a las demás.

Comprobar el estado de una publicación programada

Puedes comprobar el estado de una publicación programada de varias maneras:

Configura el Webhook Scheduled Action para recibir automáticamente el estado de la publicación programada. Está disponible en el Business Plan y es el método recomendado.
Obtén el estado de una publicación programada con la llamada GET usando el ID de la publicación.
Comprueba el estado en el Dashboard de Ayrshare. Cambia primero al User Profile bajo el que se publicó, ve a la página “Posts” y busca usando el Ayrshare Post ID.

Pausar publicaciones programadas

Puedes pausar publicaciones programadas que aún no se hayan publicado. Al pausar una publicación programada, se impedirá su publicación hasta que se reanude. Usa la llamada PATCH para pausar o reanudar la publicación programada. Ten en cuenta que si se reanuda una publicación y scheduleDate está en el pasado, la publicación se publicará de inmediato. Considera actualizar scheduleDate antes de reanudarla.

Acortar enlaces

Los enlaces de una publicación pueden acortarse usando el acortador de enlaces de Ayrshare. Puedes activar el acortamiento automático de enlaces con el parámetro shortenLinks al enviar una publicación. Requiere Max Pack.

{
  "post": "Hello, world with a link https://www.ayrshare.com",
  "platforms": ["linkedin"],
  "shortenLinks": true
}

Imágenes de Unsplash

Los siguientes valores están disponibles para el parámetro de cuerpo unsplash:

Imagen aleatoria: random devuelve una imagen aleatoria de Unsplash.
Imagen basada en búsqueda: valor de tipo String con el término de búsqueda; p. ej. money seleccionará una imagen aleatoria basada en money.
IDs de imagen: valor Array de IDs; p. ej. [“HubtZZb2fCM”] para la imagen https://unsplash.com/photos/HubtZZb2fCM

{
  "post": "Hello, world!",
  "platforms": ["instagram"],
  "unsplash": "random",
  "unsplash": "search term", // unsplash: "money"
  "unsplash": ["unsplash image ID"] // unsplash: ["HubtZZb2fCM"]
}

Si copias una URL de Unsplash para publicar en mediaUrls, asegúrate de copiar la dirección de la imagen y no solo la URL. Consulta este ejemplo para más información.

​Flujo de aprobación

​Ejemplo de flujo de aprobación

​Video del flujo de aprobación

​Hashtags automáticos (Auto Hashtags)

​Auto Repost

​Primer comentario

​Tiempo de procesamiento del primer comentario

​Publicaciones idempotentes

​Requisitos de imagen y video

Pautas de imagen y video

​URL válida

​Protección automática de medios

​Espacios y caracteres especiales

​Sanea los nombres de archivo y las URLs

​Información adicional

​Velocidad de descarga

​Extensión de video

​Solo imagen o video

​Pruebas con imágenes y videos

​Saltos de línea

​Publicaciones multiplataforma y medios

​Profile Keys

Profiles

​Publicaciones con texto enriquecido

​Elementos HTML

​Códigos CSS

​Publicaciones programadas

​Crear publicaciones programadas

​Comprobar el estado de una publicación programada

​Pausar publicaciones programadas

​Acortar enlaces

​Imágenes de Unsplash

Flujo de aprobación

Ejemplo de flujo de aprobación

Video del flujo de aprobación

Hashtags automáticos (Auto Hashtags)

Auto Repost

Primer comentario

Tiempo de procesamiento del primer comentario

Publicaciones idempotentes

Requisitos de imagen y video

URL válida

Protección automática de medios

Espacios y caracteres especiales

Sanea los nombres de archivo y las URLs

Información adicional

Velocidad de descarga

Extensión de video

Solo imagen o video

Pruebas con imágenes y videos

Saltos de línea

Publicaciones multiplataforma y medios

Profile Keys

Publicaciones con texto enriquecido

Elementos HTML

Códigos CSS

Publicaciones programadas

Crear publicaciones programadas

Comprobar el estado de una publicación programada

Pausar publicaciones programadas

Acortar enlaces

Imágenes de Unsplash