Como Agendar Posts em Redes Sociais com uma API

As duas formas de agendar conteúdo

O Upload-Post oferece duas abordagens para agendamento. Voce pode definir uma data e hora exatas com o parametro scheduled_date, ou pode deixar o sistema decidir o melhor horario usando o sistema de fila. Ambas funcionam em qualquer endpoint: upload de videos, upload de fotos e posts de texto.

Opção A: Agendar para uma data e hora específicas

Adicione o parametro scheduled_date a qualquer requisicao de upload. O formato e ISO-8601, e voce pode agendar com ate 365 dias de antecedencia.

curl -X POST https://api.upload-post.com/api/upload \
  -H "Autorização: Apikey sua-api-key-aqui" \
  -F "[email protected]" \
  -F "user=mybrand" \
  -F "title=Coming soon... stay tuned!" \
  -F "platform[]=tiktok" \
  -F "platform[]=instagram" \
  -F "scheduled_date=2025-09-22T10:00:00Z" \
  -F "timezone=Europe/Madrid"

Alguns detalhes importantes aqui. A data e em UTC por padrao, mas voce pode passar um parametro timezone usando o formato IANA (como America/Sao_Paulo, America/New_York, Europe/London) para que o post va ao ar no horario local correto. Isso evita que voce tenha que fazer calculos de fuso horario manualmente.

Quando um post e agendado com sucesso, a API responde com status 202 e inclui um job_id:

{
  "success": true,
  "job_id": "scheduler_job_abc123",
  "scheduled_date": "2025-09-22T10:00:00Z"
}

Guarde esse job_id porque voce vai precisar dele se quiser editar ou cancelar o post depois.

Opção B: Use o sistema de fila

A fila e perfeita quando voce quer publicacoes consistentes sem escolher horarios exatos. Em vez de escolher uma data, voce define add_to_queue=true e o Upload-Post atribui o proximo horario disponivel com base na sua agenda configurada.

Configurando sua fila

Primeiro, configure as opcoes da sua fila. Voce define em quais dias e quais horarios voce quer publicar:

curl -X POST https://api.upload-post.com/api/uploadposts/queue/settings \
  -H "Autorização: Apikey sua-api-key-aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "timezone": "America/Sao_Paulo",
    "slots": [
      { "hour": 9, "minute": 0 },
      { "hour": 12, "minute": 30 },
      { "hour": 17, "minute": 0 }
    ],
    "days": [0, 1, 2, 3, 4]
  }'

Este exemplo publica as 9:00, 12:30 e 17:00 (horario de Sao Paulo), de segunda a sexta. Voce pode definir ate 24 slots por dia.

Adicionando conteúdo à fila

curl -X POST https://api.upload-post.com/api/upload \
  -H "Autorização: Apikey sua-api-key-aqui" \
  -F "[email protected]" \
  -F "user=mybrand" \
  -F "title=Monday motivation" \
  -F "platform[]=tiktok" \
  -F "platform[]=instagram" \
  -F "add_to_queue=true"

O Upload-Post vai automaticamente atribuir este post ao proximo slot disponivel. Se for quarta-feira as 14h, o post sera agendado para 17:00 do mesmo dia. Se todos os slots de quarta estiverem ocupados, ele vai para quinta-feira as 9:00.

Visualizar os próximos slots da fila

Quer ver quais horarios estao disponiveis antes de enfileirar conteudo? Use o endpoint de preview:

curl https://api.upload-post.com/api/uploadposts/queue/preview?count=10 \
  -H "Autorização: Apikey sua-api-key-aqui"

Isso retorna os proximos 10 slots disponiveis com suas datas e horarios exatos. Voce pode solicitar ate 50 de uma vez.

Gerenciando postagens agendadas

Uma vez que o conteudo esta agendado, voce tem controle total sobre ele pela API.

Listar todos os posts agendados

curl https://api.upload-post.com/api/uploadposts/schedule \
  -H "Autorização: Apikey sua-api-key-aqui"

Retorna um array de jobs pendentes com seus job_id, scheduled_date, detalhes das plataformas e uma URL de preview do conteudo.

Edit a scheduled post

Precisa mudar a data de publicacao ou atualizar a legenda? Use uma requisicao PATCH:

curl -X PATCH https://api.upload-post.com/api/uploadposts/schedule/scheduler_job_abc123 \
  -H "Autorização: Apikey sua-api-key-aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "scheduled_date": "2025-09-25T14:00:00Z",
    "title": "Legenda atualizada com melhores hashtags"
  }'

Cancelar um post agendado

curl -X DELETE https://api.upload-post.com/api/uploadposts/schedule/scheduler_job_abc123 \
  -H "Autorização: Apikey sua-api-key-aqui"

O post e seus arquivos sao removidos imediatamente.

Montando um calendário de conteúdo com a fila

Aqui vai um fluxo de trabalho pratico que muitas agencias usam. Voce produz conteudo em lote na segunda-feira, faz upload de tudo para a fila, e o sistema distribui ao longo da semana automaticamente. Nao precisa estar online as 9h da manha na quarta-feira para apertar o botao de publicar.

Isso e especialmente poderoso quando combinado com ferramentas como n8n ou Make.com. Por exemplo, voce pode configurar um workflow onde novos arquivos em uma pasta do Google Drive sao automaticamente adicionados a fila. Confira nosso template de agendamento com Google Sheets para n8n para uma configuracao pronta.

Nosso calendario de datas comemorativas para redes sociais tambem e util para planejar conteudo ao redor de datas importantes ao longo do ano.

Agendando com Python

from upload_post import UploadPostClient
from datetime import datetime, timedelta

client = UploadPostClient(api_key="your-api-key-here")

# Schedule a video for tomorrow at 10 AM Sao Paulo time
publish_date = (datetime.now() + timedelta(days=1)).replace(
    hour=10, minute=0, second=0
)

response = client.upload_video(
    video_path="/path/to/video.mp4",
    title="Agendado a partir do Python",
    user="mybrand",
    platforms=["tiktok", "instagram", "youtube"],
    scheduled_date=publish_date.isoformat(),
    timezone="America/Sao_Paulo"
)

print(f"Agendado! ID do trabalho: {response['job_id']}")

Limites diários de upload por plataforma

Quando voce agenda muito conteudo, tenha em mente que cada plataforma impoe limites diarios. Sao janelas rolantes de 24 horas por conta conectada:

O sistema de fila respeita esses limites automaticamente e nao vai agendar em excesso para nenhuma plataforma.

Perguntas frequentes

Posso agendar o mesmo conteúdo para horários diferentes em plataformas diferentes?

Nao em uma unica requisicao, mas voce pode enviar requisicoes separadas para cada plataforma com valores diferentes de scheduled_date. Ou use o sistema de fila, que distribui automaticamente.

O que acontece se um post agendado falhar?

Voce recebe uma notificacao por webhooks (se configurado) com os detalhes do erro. Voce tambem pode verificar o status com o endpoint GET /api/uploadposts/status?job_id=your_job_id.

Posso combinar agendamento com as ferramentas no-code?

Com certeza. Tanto o n8n quanto o Make.com podem enviar os parametros scheduled_date ou add_to_queue pelo modulo de requisicao HTTP. Isso significa que voce pode montar um workflow visual que le de uma planilha e agenda tudo automaticamente.