Publicar imediatamente por meio de uma API é simples. Agendar é onde estão os problemas interessantes, porque um post agendado é uma promessa sobre o futuro, e o futuro contém horário de verão, quedas e posts sobre os quais você muda de ideia.
Fusos horários: passe um explicitamente
O bug de agendamento mais comum é um post que se desloca uma hora duas vezes por ano.
Um horário agendado precisa de duas coisas: o instante, como um timestamp ISO-8601, e o fuso em que ele foi expresso, como um nome IANA, por exemplo America/New_York.
await bp.posts.create({
content: 'Morning update.',
channels: [{ channelId: 1, platform: 'linkedin' }],
status: 'scheduled',
scheduledAt: '2026-04-10T14:00:00Z',
timezone: 'America/New_York',
});Armazenar apenas um instante em UTC é aceitável para algo pontual. É errado para qualquer coisa recorrente, porque “toda semana útil às 9h local” é um instante UTC diferente antes e depois de uma mudança de horário de verão. O fuso é o que torna isso correto.
Nunca armazene um deslocamento bruto como -05:00 como substituto de um fuso. Deslocamentos mudam; fusos não.
Modele mais do que dois estados
Um post não é apenas agendado ou publicado. Construa para pelo menos:
- draft, criado mas não enfileirado
- scheduled, na fila para um horário
- processing, enviado para a plataforma, resultado desconhecido
- published, confirmado no ar
- failed, com um motivo
- partial, publicado em alguns destinos e não em outros
Os dois que as pessoas esquecem são processing e partial.
processing existe porque várias plataformas aceitam um post e o publicam de forma assíncrona. Um 200 não é uma publicação, e o resultado real chega depois.
partial existe porque um post geralmente tem várias plataformas como destino. Se três têm sucesso e uma falha, nem “published” nem “failed” é verdadeiro, e forçar em um dos dois produz uma interface que mente para o usuário.
O que acontece quando uma plataforma está fora do ar
Projete para isso, porque acontece.
Falhas transitórias devem ser tentadas de novo com backoff. Uma plataforma retornando 503 por dois minutos não deveria perder o post.
Retentativas precisam ser seguras. Uma criação que expirou pode ter tido sucesso. Tentar de novo às cegas duplica o post, o que é pior do que a falha original. Verifique antes de tentar de novo.
Falhas permanentes não deveriam ser tentadas de novo. Um token expirado ou uma legenda inválida não vão se resolver sozinhos, e tentar de novo só queima cota e atrasa a notificação.
Alguém precisa ser avisado. Um post agendado que falha às 3h da manhã é silencioso, a menos que você o torne visível. Webhooks são o mecanismo certo.
Edição e cancelamento
Um post agendado é uma promessa que você pode precisar quebrar. Sua integração deveria suportar mudar o horário, editar o conteúdo e cancelar completamente.
Note que as plataformas diferem quanto a permitir isso depois que elas já detêm o post, o que é um dos motivos pelos quais agendar na sua própria camada e enviar no último momento se comporta melhor do que entregar à plataforma um post com data futura.
Slots de fila versus horários explícitos
Dois modelos de agendamento, e ambos têm o seu lugar.
Horários explícitos são o que você quer quando um post precisa chegar em um momento específico: um lançamento, um evento, um anúncio coordenado.
Slots de fila são o que você quer para um fluxo constante. Você define uma cadência de publicação e o próximo post ocupa o próximo slot livre, então você não escolhe timestamps para cada post em um lote.
Para trabalho em massa, o segundo é muito menos tedioso, e é o modelo que torna “enfileirar trinta posts” uma operação sensata, e não trinta decisões.
Agendamentos recorrentes
Distintos de um post agendado. Um agendamento recorrente é uma regra que continua produzindo posts em uma frequência: diária, semanal, quinzenal ou mensal.
Duas coisas para projetar. O fuso horário importa ainda mais aqui, pelo motivo do horário de verão acima. E a mídia anexada a um post recorrente precisa ser mantida em vez de limpa depois da publicação, porque o agendamento vai precisar dela de novo na próxima vez.
Limites de plano
| Free | Pro | Business | |
|---|---|---|---|
| Requisições de API/dia | 30 | 5.000 | 50.000 |
| Publicações | 3/dia | 30/dia | Ilimitadas |
| Agendamentos recorrentes | Nenhum | 10 | Ilimitados |
A versão curta
Passe um fuso horário IANA junto com todo timestamp agendado, especialmente para qualquer coisa recorrente. Modele processing e partial como estados reais, porque a publicação assíncrona e os posts multiplataforma fazem os dois acontecerem de fato. Tente de novo falhas transitórias com backoff, nunca refaça uma criação às cegas, e use webhooks para que uma falha às 3h da manhã não seja silenciosa.