Visão geral da API Post - Ayrshare API Documentation

O endpoint post permite publicar em redes sociais: Bluesky, Facebook, Google Business Profile, Instagram, LinkedIn, Pinterest, Reddit, Snapchat, Telegram, TikTok, X/Twitter e YouTube. Há muitas opções para personalizar sua publicação, como agendar publicações, adicionar hashtags automáticas, programação automática de publicações e muito mais. Frequentemente é usado por agências quando várias pessoas precisam aprovar uma publicação antes que ela seja publicada. Comece a publicar com o endpoint POST /post.

Fluxo de aprovação

Se seu fluxo de publicação exigir aprovação antes de enviar uma publicação, defina o campo requiresApproval como true. Isso equivale a pausar a publicação até que o parâmetro approved seja definido como true.

Exemplo de fluxo de aprovação

A publicação terá o status “awaiting approval” até que o parâmetro approved seja definido como true pelo endpoint PATCH /post.

Publicar com parâmetros

Publique sua postagem usando o endpoint /post com o campo requiresApproval como true. Você também pode incluir parâmetros padrão, como scheduleDate.

Status: awaiting approval

A publicação ficará com o status “awaiting approval” e será retida até que a aprovação seja concedida.

Aprovar a publicação

Atualize a publicação com a operação PATCH /post, definindo o campo approved como true. A publicação agora será enviada na data agendada.

Usar notas

Opcional: defina notes na publicação para referência, como quem precisa aprovar a publicação.

Publish the Post with Approval

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

Se scheduleDate estiver incluído e a data estiver no passado, a publicação será publicada imediatamente após a aprovação.

Vídeo do fluxo de aprovação

Veja o vídeo abaixo para um exemplo do fluxo de aprovação.

Hashtags automáticas (Auto Hashtags)

Adicione as hashtags mais relevantes à sua publicação. autoHashtag é um objeto ou um Boolean — veja abaixo — com os seguintes parâmetros:

max: (opcional) Número inteiro de hashtags a adicionar, intervalo 1–10. Padrão: 2.
position: (opcional) String “auto” ou “end”. “auto” adiciona as hashtags dentro da publicação ou ao final. “end” adiciona hashtags somente ao final.

É necessário um plano pago.

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

Se não quiser enviar nenhuma das opções acima, passe o valor booleano true em vez de um objeto.

{
  "autoHashtag": true
}

Repostagem automática (Auto Repost)

Reposta automaticamente seu conteúdo várias vezes em intervalos regulares, criando conteúdo perene que permanece fresco e visível para sua audiência. É necessário um plano pago. Parâmetros:

repeat: (obrigatório) Número de vezes que o conteúdo será repostado. Deve estar entre 1 e 10.
days: (obrigatório) Número de dias entre cada repostagem. Deve ser de no mínimo 2 dias.
startDate: (opcional) Quando iniciar o agendamento de repostagem, no formato UTC ISO-8601. Se não for especificado, a primeira publicação será publicada imediatamente. Você deve usar o parâmetro startDate no lugar do parâmetro scheduleDate de nível superior.

Auto Repost

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

A resposta incluirá todas as futuras repostagens agendadas e um autoRepostId para cada repostagem.

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"
}

Ao criar uma repostagem automática, um ID autoRepostId é atribuído para rastrear essa série de publicações. Você pode obter todas as repostagens automáticas de uma publicação com a chamada History usando o autoRepostId. Se precisar excluir uma repostagem, você pode usar a chamada DELETE com o ID da publicação.

Importante: Ao usar a repostagem automática, certifique-se de seguir as diretrizes de frequência de publicação de cada rede social para evitar restrições na conta.Observação: O recurso autoRepost não pode ser usado em conjunto com scheduleDate. Se você incluir ambos os parâmetros, scheduleDate terá precedência e autoRepost será ignorado. Use o parâmetro startDate em vez disso.

Primeiro comentário

Adicione automaticamente um primeiro comentário, com mídia, após a publicação ser publicada. Para o TikTok, o comentário é adiado até que o vídeo termine de ser processado (veja Tempo de processamento do primeiro comentário). Publicar o primeiro comentário em sua própria publicação de rede social pode ajudar a impulsionar o engajamento e definir o tom para a discussão que se segue.

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

Tempo de processamento do primeiro comentário

Para a maioria das redes sociais, a resposta da API é atrasada porque nosso sistema precisa (1) esperar que a publicação original seja totalmente publicada e, em seguida, (2) adicionar o comentário a essa publicação. Esse processo sequencial adiciona um atraso de aproximadamente 20 segundos. O TikTok é tratado de forma diferente. O TikTok processa vídeos de forma assíncrona, então o id da publicação é "pending" até que o webhook post.publish.publicly_available do TikTok resolva o ID real do vídeo (veja Processamento do TikTok). A resposta do /post, portanto, retorna o primeiro comentário do TikTok com status: "pending" imediatamente, e o comentário é publicado automaticamente assim que o TikTok termina de processar e o webhook tikTokPublished da Scheduled Action é disparado. O TikTok não garante um tempo de processamento, portanto não há um atraso fixo. Observação importante sobre o TikTok: Para que os primeiros comentários funcionem corretamente no TikTok, o parâmetro visibility da publicação deve estar definido como public. Um vídeo não público nunca recebe o webhook publicly_available, então seu primeiro comentário não pode ser publicado; nesse caso, o Ayrshare retorna um erro de comentário em vez de deixá-lo pendente.

Publicações idempotentes

Idempotência é um recurso opcional que garante que uma requisição seja executada apenas uma vez, mesmo que seja enviada acidentalmente várias vezes. Ao publicar conteúdo usando a API, você pode incluir um parâmetro opcional idempotencyKey no corpo da requisição para identificar exclusivamente a operação. Isso permite que você reenvie a requisição de publicação com segurança sem o risco de criar publicações duplicadas. Para usar a idempotência, adicione o parâmetro idempotencyKey ao corpo JSON da requisição POST /post:

Idempotency Key

{
  "idempotencyKey": "Unique Key"
}

O valor de idempotencyKey deve ser uma string única por User Profile. Se uma requisição for feita com o mesmo idempotencyKey para um dado User Profile, independentemente do estado da publicação (sucesso, erro, pendente ou excluída), um erro será retornado indicando que uma chave duplicada foi encontrada.

A API precisa primeiro aceitar e processar a requisição POST para armazenar a chave de idempotência e verificar duplicatas. No entanto, se várias requisições POST com o mesmo idempotencyKey forem enviadas simultaneamente ou agendadas para o mesmo horário de publicação, a API pode não detectar as chaves duplicadas. Isso ocorre porque a API processa essas requisições concorrentes ou simultaneamente agendadas em paralelo, antes que tenha a chance de registrar a chave de idempotência de qualquer requisição individual. Como resultado, não há garantia de que chaves de idempotência duplicadas serão detectadas nesses cenários de envio simultâneo ou execução simultânea de publicações agendadas.

Usar idempotência ajuda a evitar a criação acidental de publicações duplicadas ao reenviar requisições com falha ou lidar com problemas de rede. No entanto, ainda é recomendado implementar tratamento de erros e mecanismos de repetição apropriados em sua aplicação para lidar com possíveis falhas de forma elegante.

Requisitos de imagem e vídeo

Publicar imagens e vídeos tem requisitos diferentes para cada rede, mas não se preocupe. Nosso sistema verifica sua publicação antes de enviá-la, então você receberá uma resposta de erro se algo estiver errado. Veja no link abaixo detalhes sobre as diretrizes de imagem e vídeo.

Diretrizes de imagem e vídeo

URL válida

Certifique-se de que suas URLs de mídia sejam válidas e acessem diretamente a mídia. Um primeiro teste é tentar a URL em um navegador. Se a imagem não carregar ou não puder ser baixada em um navegador, provavelmente falhará. Por exemplo, uma URL do DropBox que abre o aplicativo web do DropBox não funcionará.

Se você tiver uma URL de compartilhamento do Google Drive ou uma URL de compartilhamento do Dropbox, você pode simplesmente usar a URL no parâmetro mediaUrls ao publicar uma postagem ou comentário. O Ayrshare irá converter automaticamente a URL de compartilhamento em um link de download.

Verificamos a URL da mídia fazendo uma requisição HEAD. Certifique-se de que o provedor de hospedagem não esteja bloqueando a requisição HEAD, ou a publicação falhará com um erro 403. Por exemplo, aqui está uma requisição HEAD para a URL da mídia:

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();

Proteção automatizada de mídia

O Ayrshare inclui proteção de mídia integrada que pode detectar e resolver certos problemas de entrega de mídia durante a publicação. Quando uma publicação é bem-sucedida, mas um problema de conteúdo foi detectado e resolvido, cada entrada afetada em postIds[] inclui um objeto opcional contentIssues para que você possa identificar e corrigir o problema subjacente:

{
    "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."]
            }
        }
    ]
}

Se você vir originMediaHostFailed em suas respostas, revise a configuração de hospedagem de mídia. Veja Meta Media Crawler Blocked para causas e soluções comuns.

Espaços e caracteres especiais

Recomendamos evitar o seguinte em suas URLs de mídia:

Espaços na URL.
Espaços codificados em URL na URL.
Caracteres especiais na URL, mesmo que estejam codificados em URL, como acentos como é.

Por exemplo:

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

Essa URL falha por causa do espaço test .webp. Também não recomendamos usar espaços codificados em URL, como %20, na URL — isso também pode causar problemas com algumas redes sociais. E essa imagem do Unsplash:

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

Essa imagem do Unsplash falha porque não acessa diretamente a imagem, mas mostra um aplicativo web.

Sanitizar nomes de arquivos e URLs

Você pode sanitizar seus nomes de arquivos com uma expressão regular como /[^a-z0-9\/\.]/gi.

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

ou sanitizar uma 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");

Informações adicionais

Se você estiver hospedando por conta própria, certifique-se de que a URL possa ser acessada externamente e não exija permissões especiais.
Veja abaixo como lidar com vídeos com extensões desconhecidas, muitas vezes URLs assinadas, como AWS S3.
Se você estiver usando uma URL assinada, como do S3, recomendamos definir a expiração da URL para pelo menos 7 dias. Isso permite que nossa equipe ajude com quaisquer dúvidas sobre a publicação.
Teste se a URL da mídia existe com nossas ferramentas de verificação de mídia.

Velocidade de download

Certifique-se de que sua hospedagem de mídia tenha uma conexão rápida, especialmente a velocidade de download. Você pode testar o desempenho da sua hospedagem de mídia em pingdom. Recomendamos pelo menos uma classificação B.

Extensão de vídeo

Se sua URL não terminar com uma extensão de vídeo conhecida, como mp4, você pode usar o campo isVideo: true na publicação para especificar que a mediaUrl é um vídeo. O Ayrshare tentará determinar o tipo de arquivo, como MOV. No entanto, recomendamos terminar explicitamente seu arquivo de vídeo com uma extensão conhecida, como mp4, já que isso tem uma taxa de sucesso maior com as redes sociais.

Somente imagem ou vídeo

Algumas redes sociais suportam o envio de mídia sem texto de publicação. Se você não quiser incluir texto na publicação, envie uma string vazia: post: "" As seguintes redes sociais suportam publicação sem texto (em branco): Facebook, Instagram, LinkedIn, Threads, TikTok e X/Twitter.

Testando imagens e vídeos

Considere usar gerar texto aleatório e imagem ou vídeo aleatório para acelerar seus testes. Pare de tentar pensar em algo diferente para cada uma de suas publicações de teste!

Quebras de linha

Se você quiser quebras de linha (novas linhas) em uma publicação, use a quebra de linha invisível \u2063\n. Por exemplo, This is a new\u2063\nline.Também recomendamos testar no Postman para ver como a nova quebra de linha é traduzida na sua linguagem de escolha. Por exemplo, o PHP frequentemente usa apenas \nAlgumas redes sociais atualmente não suportam quebras de linha no texto da publicação.

Publicações multiplataforma e mídia

Este recurso permite personalizar o conteúdo e a mídia da sua publicação para diferentes redes sociais em uma única chamada de API. Você pode especificar texto e/ou imagens únicos para cada plataforma usando objetos para os campos post e mediaUrls.

Use uma estrutura de objeto para os campos post e/ou mediaUrls.
Especifique conteúdo específico da plataforma usando os nomes das plataformas como chaves.
Inclua uma chave default para o conteúdo a ser usado em plataformas não especificadas explicitamente.

{
  "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"
  }
}

No exemplo acima:

O Instagram usará seu texto e URL de imagem específicos.
O Facebook usará seu texto específico e a URL de imagem padrão.
O LinkedIn usará o texto padrão e sua URL de imagem específica.

Se precisar publicar várias imagens em diferentes plataformas, crie publicações separadas para cada plataforma em vez de usar essa estrutura multiplataforma.

Profile Keys

Publique em nome do usuário fornecendo as Profile Keys dos usuários como parâmetro do corpo e os dados adicionais na resposta. Plano Business ou Enterprise necessário.

Perfis

Publicações com Rich Text

Você pode adicionar rich text como ”𝓗𝓮𝓵𝓵𝓸, how about a little 𝗯𝗼𝗹𝗱 𝘁𝗲𝘅𝘁 and 𝘪𝘵𝘢𝘭𝘪𝘤𝘴 𝘵𝘦𝘹𝘵 and an x₂?”. Você pode usar rich text em redes como Twitter, Facebook, LinkedIn, Telegram e Instagram. Se estiver publicando no Reddit, use a formatação Markdown do Reddit. Elementos HTML são usados para especificar o tipo de rich text, que é traduzido em unicode. Por exemplo:

{
    "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	Exemplo
<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	Exemplo	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.

Agendar publicações

Criar publicações agendadas

Você pode agendar publicações futuras especificando o parâmetro scheduleDate com a data/hora em Zulu/UTC. O horário Zulu, também conhecido como Tempo Universal Coordenado (UTC), é o padrão mundial de horário. Por exemplo, use o formato YYYY-MM-DDThh:mm:ssZ e envie como 2026-07-08T12:30:00Z. Consulte utctime para mais exemplos.

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

Consulte https://www.utctime.net/ sobre como converter seu horário local para o horário Zulu/UTC. Se a data/hora agendada estiver no passado, a publicação será enviada imediatamente.

Se uma mediaUrl estiver incluída em uma publicação agendada, a mídia deverá estar disponível no horário de publicação agendado. Por exemplo, se a publicação estiver agendada para ser publicada em 5 de março de 2026, a mídia deverá estar disponível em 5 de março de 2026.

Tratamento de erros para publicações agendadas vs. imediatasHá uma diferença importante em como os erros de validação são tratados entre publicações imediatas e agendadas:

Publicações imediatas
- Ao publicar imediatamente (sem scheduleDate), se uma plataforma falhar nas verificações de validação, as outras plataformas continuarão a ser processadas. Por exemplo, se uma publicação exceder o limite de caracteres do Twitter, mas for válida para Facebook e Instagram, a publicação falhará no Twitter, mas ainda será publicada no Facebook e Instagram.
Publicações agendadas
- Ao agendar publicações para publicação futura (com scheduleDate), todas as plataformas devem passar nas verificações de validação iniciais antes que a publicação seja agendada. Se alguma plataforma falhar nessas verificações de pré-validação, toda a operação de agendamento será rejeitada e um erro será retornado imediatamente.
- No entanto, alguns erros específicos da plataforma podem não ser detectados até o horário real de publicação. Nesses casos, a publicação agendada tentará ser publicada em todas as plataformas, e as falhas individuais de cada plataforma serão relatadas nos resultados finais sem afetar as outras plataformas.

Verificar o status de uma publicação agendada

Você pode verificar o status de uma publicação agendada de várias maneiras:

Configure o Webhook Scheduled Action para receber automaticamente o status da publicação agendada. Isso está disponível para o plano Business e é o método recomendado.
Obtenha o status de uma publicação agendada com a chamada GET usando o ID da publicação.
Verifique o status no Ayrshare Dashboard. Primeiro, mude para o User Profile em que a publicação foi publicada, depois acesse a página “Posts” e faça a busca usando o Ayrshare Post ID.

Pausar publicações agendadas

Você pode pausar publicações agendadas que ainda não foram publicadas. Pausar uma publicação agendada impedirá que ela seja publicada até que a publicação seja despausada. Use a chamada PATCH para pausar ou despausar a publicação agendada. Observe que, se uma publicação for despausada e o scheduleDate estiver no passado, a publicação será publicada imediatamente. Considere atualizar o scheduleDate antes de despausá-la.

Encurtar links

Links em uma publicação podem ser encurtados usando o encurtador de links do Ayrshare. Você pode ativar o encurtamento automático de links com o parâmetro shortenLinks ao enviar uma publicação. Max Pack necessário.

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

Imagens do Unsplash

Os seguintes campos estão disponíveis para o parâmetro unsplash no corpo:

Imagem aleatória: random retorna uma imagem aleatória do Unsplash.
Imagem baseada em busca: valor do tipo String com o termo de busca; por exemplo, money selecionará uma imagem aleatória baseada em dinheiro.
IDs de imagem: valor do tipo Array de IDs; por exemplo, [“HubtZZb2fCM”] da imagem https://unsplash.com/photos/HubtZZb2fCM

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

Ao copiar uma URL do Unsplash para publicar em mediaUrls, certifique-se de copiar o endereço da imagem e não apenas a URL. Consulte este exemplo para mais informações.

​Fluxo de aprovação

​Exemplo de fluxo de aprovação

​Vídeo do fluxo de aprovação

​Hashtags automáticas (Auto Hashtags)

​Repostagem automática (Auto Repost)

​Primeiro comentário

​Tempo de processamento do primeiro comentário

​Publicações idempotentes

​Requisitos de imagem e vídeo

Diretrizes de imagem e vídeo

​URL válida

​Proteção automatizada de mídia

​Espaços e caracteres especiais

​Sanitizar nomes de arquivos e URLs

​Informações adicionais

​Velocidade de download

​Extensão de vídeo

​Somente imagem ou vídeo

​Testando imagens e vídeos

​Quebras de linha

​Publicações multiplataforma e mídia

​Profile Keys

Perfis

​Publicações com Rich Text

​Elementos HTML

​Códigos CSS

​Agendar publicações

​Criar publicações agendadas

​Verificar o status de uma publicação agendada

​Pausar publicações agendadas

​Encurtar links

​Imagens do Unsplash

Fluxo de aprovação

Exemplo de fluxo de aprovação

Vídeo do fluxo de aprovação

Hashtags automáticas (Auto Hashtags)

Repostagem automática (Auto Repost)

Primeiro comentário

Tempo de processamento do primeiro comentário

Publicações idempotentes

Requisitos de imagem e vídeo

URL válida

Proteção automatizada de mídia

Espaços e caracteres especiais

Sanitizar nomes de arquivos e URLs

Informações adicionais

Velocidade de download

Extensão de vídeo

Somente imagem ou vídeo

Testando imagens e vídeos

Quebras de linha

Publicações multiplataforma e mídia

Profile Keys

Publicações com Rich Text

Elementos HTML

Códigos CSS

Agendar publicações

Criar publicações agendadas

Verificar o status de uma publicação agendada

Pausar publicações agendadas

Encurtar links

Imagens do Unsplash