Tarefas agendadas: rode rotinas no site no horário
Uma tarefa agendada executa algo no seu site em horários definidos sem que ninguém aperte um botão: um resumo toda manhã, uma faxina todo domingo à noite. Você as encontra em Settings do projeto, em Scheduled tasks. Esta página mostra como configurar uma, ler suas execuções e corrigir uma que falha.
O que uma tarefa agendada faz
Uma tarefa agendada é uma chamada que o Briks faz em um horário definido. Ela chama uma rota do seu site (um endereço sob /api/ que executa código em vez de mostrar uma página) ou outro endereço https público, como um serviço que você usa. O endereço faz o trabalho. O Briks faz a chamada na hora certa e registra o que voltou.
Então uma tarefa precisa de algo para chamar. Se o seu site ainda não tem uma rota para o trabalho, peça uma no estúdio primeiro e depois aponte uma tarefa para ela. Sem tarefas ainda, a página diz No scheduled tasks e resume os trabalhos mais comuns: enviar um resumo diário, limpar registros antigos ou sincronizar com outro serviço.
As tarefas rodam com o site publicado ou não, nos horários que você define, no fuso horário que escolher. A seção tem três visões: Tasks, Runs e Settings.
Limites de cada plano
| Plano | Tarefas agendadas por projeto | Três escolhas que todo plano de dashboard faz |
|---|---|---|
| Free | 1 | 2.000 |
| Starter | 5 | 5.000 |
| Pro | 10 | 10.000 |
| Studio | 25 | 50.000 |
| Agency | 50 | 100.000 |
A visão Tasks mostra em que ponto você está, como 2 de 5 no seu plano, e Add task fica cinza quando você atinge o limite. Um link Get more aparece então ao lado da contagem e abre a janela de upgrade, que indica o menor plano com espaço para mais uma tarefa. Uma execução que passaria do limite de chamadas do dia é marcada como Skipped. Os planos são comparados em Cobrança.
Adicionar uma tarefa agendada
Pressione Add task
Onde: Settings, Scheduled tasks
A janela Add a scheduled task abre. Editor, Admin e Owner podem adicionar tarefas.
Dê um nome
Onde: Add a scheduled task
Dê um nome curto que você reconheça na lista de execuções, como
Resumo diário. Até 60 caracteres.Defina a programação
Onde: Add a scheduled task
Digite um horário em Schedule ou clique em um dos botões abaixo dele. A próxima seção explica o formato.
Escolha o fuso horário
Onde: Add a scheduled task
O Time zone começa no seu próprio fuso. Uma caixa abaixo mostra o agendamento em palavras e as próximas cinco vezes em que ele vai rodar nesse fuso, para você conferir antes de salvar.
Diga como se chama
Onde: Add a scheduled task
Em What it calls, escolha A route on this site e digite o caminho dela (começa com
/api/), ou Another address e digite um endereço https completo. Para uma rota, a dica abaixo do campo mostra o endereço completo que será chamado.Escolha POST ou GET
Onde: Add a scheduled task
POST envia uma mensagem curta com a chamada, que a maioria das rotas feitas para uma tarefa espera. GET apenas pede o endereço. Se estiver em dúvida, deixe POST.
Salvar
Onde: Add a scheduled task
Pressione Add task. Ela só é salva depois que o agendador a aceita, então toda tarefa da lista é uma que roda.
Como escrever um agendamento
Um agendamento são cinco valores separados por espaços: minuto, hora, dia do mês, mês e dia da semana. Um * significa todos. Se o que você digitar não puder ser lido, a caixa diz o que está errado, como qual valor está fora do intervalo.
| Você quer | Tipo | A prévia diz |
|---|---|---|
| Todas as manhãs às 7h | 0 7 * * * | Todos os dias às 07:00 |
| De segunda a sexta, às seis e meia da tarde | 30 18 * * 1-5 | Todo dia útil às 18:30 |
| A cada 15 minutos | */15 * * * * | A cada 15 minutos |
| A cada duas horas, em ponto | 0 */2 * * * | A cada 2 horas, em ponto |
| Domingo à noite, às 23h | 0 23 * * 0 | Todo domingo às 23:00 |
| No dia 1 de cada mês, às 6 da manhã | 0 6 1 * * | No dia 1º de cada mês, às 06:00 |
Os dias da semana vão de 0 (domingo) a 6 (sábado), e 7 também é domingo. Você também pode escrever nomes como mon ou jan, listas como 1,3,5, intervalos como 1-5 e passos como */10. Os atalhos também funcionam: @hourly, @daily, @weekly, @monthly e @yearly.
Os botões abaixo do campo preenchem tudo para você: Every 5 minutes, Every hour, Every day at 09:00, Mondays at 09:00 e First of the month.
O que cada chamada traz
Uma tarefa espera até 30 segundos por uma resposta. Toda chamada leva um user-agent com o valor Briks-Cron/1.0 e um cabeçalho x-briks-cron com o id da tarefa, para que a rota saiba de onde a chamada veio. Uma chamada POST também envia uma mensagem JSON curta (JSON é um formato de texto simples que os programas leem) que nomeia a tarefa:
{"cron":{"id":"…","name":"Daily digest"},"trigger":"schedule","scheduledFor":"2026-10-09T06:00:00.000Z"}
trigger é manual quando alguém clicou em Run now, e então scheduledFor é null.
O Briks não chama um endereço de rede privada, um endereço escrito em números nem um de seus próprios endereços, e não segue redirecionamentos, então informe o endereço final. As chamadas a uma rota do seu site vão para o endereço briks.live dele e, se você mudar esse endereço, elas acompanham a mudança.
Execuções e o que cada status significa
Runs lista todas as execuções dos últimos trinta dias, da mais recente para a mais antiga, agendadas ou iniciadas manualmente. Uma execução iniciada manualmente traz a etiqueta By hand. Com mais de uma tarefa, escolha uma na caixa acima da lista e pressione Show. Clique em uma execução para ver o método e o endereço que ela chamou, qualquer erro e o início do que o endereço respondeu.
| Status | O que aconteceu |
|---|---|
| Succeeded | O endereço respondeu com um status 2xx, o código da web para sucesso. |
| Failed | Qualquer outra coisa: um status diferente (404 significa não encontrado, 500 significa que o código por trás falhou), nenhuma resposta em 30 segundos, um redirecionamento ou um endereço que não pôde ser alcançado. |
| Skipped | As chamadas do dia do projeto acabaram. A execução diz: Today's calls for this project are used up. Runs start again after midnight (UTC). |
A visão Tasks mostra o mesmo de relance: Next e o horário da próxima execução, Last com o status mais recente, ou Not run yet.
Quando uma execução falha
Uma execução com falha é registrada e não é repetida. A próxima vem no horário habitual. As execuções perdidas enquanto nada podia rodá-las também não são recuperadas: a tarefa roda uma vez e segue a partir daí.
Depois de corrigir a causa, abra os três pontos da tarefa e escolha Run now. O resultado aparece na hora, por exemplo: Resumo diário executado: o endereço respondeu 200 em 312 ms. Você pode executar uma tarefa manualmente até 20 vezes por hora, e cada execução conta para as chamadas do dia.
| O que a execução diz | O que fazer |
|---|---|
| respondeu 404 | Não existe rota nesse caminho. Confira a grafia e se a versão com a rota foi publicada. |
| respondeu 500 | A própria rota falhou. Abra Registros, escolha Requests e busque o caminho para ler o erro. |
| Sem resposta em 30 segundos. | A tarefa leva tempo demais de uma só vez. Peça no estúdio o caminho para fazer menos por chamada e execute com mais frequência. |
| Redirecionamentos não são seguidos: use o endereço final. | Abra o endereço em um navegador, copie para onde ele vai parar e mude a tarefa para esse endereço. |
| Esse endereço aponta para uma rede privada e não pode ser chamado. | Use um endereço público. O Briks nunca acessa redes privadas. |
Pausar, alterar ou excluir
O botão de alternância ao lado de cada tarefa a pausa (aparece uma etiqueta Paused) e a reinicia. Nos três pontos, Change abre o mesmo formulário, com o título Change task, e Delete a interrompe e remove o histórico de execuções. Tudo isso exige permissão de edição.
A visão Settings tem Download JSON, um arquivo com o nome, o horário, o fuso horário e o que cada tarefa chama. A zona de perigo tem Clear history (as tarefas continuam rodando) e Delete all (você digita o nome do projeto para confirmar). Os dois são para Owners e Admins.
Exemplos práticos
Adicione uma rota em /api/daily-summary que me envie por e-mail, em uma única mensagem, os pedidos de agendamento de ontem.
Depois que a alteração é publicada, a clínica adiciona uma tarefa agendada chamada Daily summary com o agendamento 0 7 * * *, fuso horário Europe/London, chamando POST /api/daily-summary. Toda manhã, às sete, o resumo chega.
O resumo é enviado pelo e-mail do próprio site, que fica desligado até você ativá-lo. Veja E-mail do site para saber como fazer isso e qual é a cota mensal.
Adicione uma rota em /api/tidy-enquiries que apague consultas com mais de 90 dias.
Uma tarefa chamada Limpar solicitações a executa com 0 23 * * 0, todo domingo às 23:00. Na segunda, Runs mostra Succeeded, e abrir a execução mostra o que a rota respondeu.
Antes de rodar uma limpeza como esta pela primeira vez, salve um ponto de restauração nas configurações da aba Database. Se a rota apagar mais do que deveria, você pode voltar atrás. Veja Backups.