Scheduler

O Scheduler é um agendamento de execução recorrente que você registra em um Space. Ao vincular um Script a um horário de execução, o servidor executa esse Script sempre que esse horário chega. Por exemplo, se você quer executar uma vez por dia um Script que, no e-commerce de uma loja de roupas, encontra os produtos com estoque zero e aciona o canal de pedidos do fornecedor, basta criar um Scheduler que aponte para esse Script.

O Scheduler é um recurso subordinado ao Space, gerenciado pela CMA, e seu caminho tem como base /spaces/{spaceId}/schedulers. Não existe o conceito de publicação (publish) nem sys.version. Assim que é criado, entra em agendamento de imediato, e a edição não exige o cabeçalho de versão. Em compensação, há dois pontos em que ele difere dos demais recursos. O Script a ser executado não pode ser alterado após a criação e, para criá-lo ou modificá-lo, além da permissão de configuração do Space é preciso ter, em separado, a permissão de execução do Script em questão. O resultado de cada execução fica registrado como SchedulerLog: uma execução bem-sucedida desaparece após 1 hora e uma execução malsucedida, após 3 dias.

Estrutura do recurso

A seguir está a resposta ao criar um Scheduler. O sys contém identificadores e referências, e o corpo contém o nome, o horário de execução e o estado de ativação.

{
  "sys": {
    "id": "7kQm2ZbTn4Rc9WvXpL3dHsY6fJ",
    "type": "Scheduler",
    "space": { "sys": { "id": "HnQ32YiH", "type": "Refer", "targetType": "Space" } },
    "script": { "sys": { "id": "3trmXRMKq7bd0Prbef1NcZ", "type": "Refer", "targetType": "Script" } },
    "createdBy": { "sys": { "id": "9dLmQ2pVnRb8sTfWcXd3LhJ7gK", "type": "Refer", "targetType": "User" } },
    "createdAt": "2026-08-26T01:20:07.442Z",
    "updatedBy": { "sys": { "id": "9dLmQ2pVnRb8sTfWcXd3LhJ7gK", "type": "Refer", "targetType": "User" } },
    "updatedAt": "2026-08-26T01:20:07.442Z"
  },
  "name": "Pedido de estoque",
  "cronExpression": "0 0 * * *",
  "activated": true
}

Chaves principais:

• sys.id: identificador único do Scheduler. Entra no {schedulerId} dos caminhos de consulta individual, edição e exclusão.
• sys.script: o Script que este agendamento vai executar. Só pode ser definido no momento da criação e não pode ser alterado depois. Para executar outro Script, crie um novo Scheduler.
• name: rótulo exibido no console. Não é usado na execução.
• cronExpression: o horário de execução. Tem cinco campos (minuto, hora, dia, mês, dia da semana) e é interpretado em UTC. Consulte Como definir o horário de execução abaixo.
• activated: se está ativado. Se for false, o registro é mantido e apenas a execução não acontece.

Não há sys.version. Não envie o cabeçalho X-Weegloo-Version nas requisições de edição.

Propriedades do sistema (sys)

space, script, createdBy e updatedBy vêm no formato Refer ({ "sys": { "id", "type": "Refer", "targetType" } }).

Propriedades do corpo:

Como definir o horário de execução

Os cinco campos são escritos, da esquerda para a direita, na ordem minuto, hora, dia, mês, dia da semana. Não há campo para segundos.

Você pode usar * (tudo), , (lista), - (intervalo) e / (incremento); o dia da semana é escrito com número (07, sendo 0 e 7 domingo) ou com nome (SUNSAT).

Todos os valores são interpretados em UTC. Você precisa calcular e considerar a diferença em relação ao horário local, e, em horários vinculados a uma data ou a um dia da semana, essa diferença pode acabar mudando o dia.

Um valor que nunca dispara não é salvo. Se, como em 0 0 30 2 * (30 de fevereiro), ele apontar para um dia que nunca chega, mesmo com o formato correto, é rejeitado.

Estado e restrições

Regras de comportamento e permissão:

• São necessárias duas permissões ao mesmo tempo. O settings do papel (SpaceRole) deve conter SETTING_SCHEDULER e, à parte disso, é preciso ter a permissão Execute sobre o Script de destino. A verificação ocorre não só na criação, mas também na edição e na edição parcial. Isso porque alterar o horário de execução é definir quando esse Script será executado, e ativar algo que estava desativado é iniciar a execução. Se faltar qualquer uma delas, a requisição é rejeitada.
• A execução ocorre com a permissão de sys.createdBy. O filtro :self dentro do Script também é interpretado como esse usuário. Mesmo que quem edita seja outra pessoa, o responsável pela execução não muda.
• Se o autor perde a permissão de execução, ele é desativado automaticamente. No horário de execução seguinte, o servidor verifica isso, não executa e define activated como false. Mesmo que a permissão seja restaurada, ele não é reativado automaticamente.
• Há um limite de quantidade. O número de Scheduler que uma Organization pode ter é definido por plano (Free 1, Basic 5, Pro 30, Enterprise ilimitado). Se esse limite for ultrapassado, a criação é rejeitada.
• A contagem de execuções é compartilhada com o Script. Cada vez que roda, consome uma execução de Script do plano. Não há um limite de execução exclusivo do Scheduler. Se esse limite for excedido e a execução de Script da Organization for interrompida, os Scheduler cujo horário de execução chegar a partir daí não são executados e o activated passa a false. Nesse caso fica um SchedulerLog e o motivo é registrado em sys.error. Depois de desativado, esse Scheduler não volta a ser agendado.
• Execuções perdidas não são recuperadas. Mesmo que haja ciclos que não puderam ser executados, eles não são executados em lote depois; a execução recomeça a partir do próximo horário.
• Um Script em uso não pode ser excluído. Ao tentar excluir um Script referenciado por algum Scheduler, essa exclusão é rejeitada (consulte Erros do Script).
• Não há publicação. Sem valores de estado nem etapa de publicação, ao criar ele entra em agendamento imediatamente, e a exclusão também é imediata, sem etapas prévias.

SchedulerLog

Cada vez que um Scheduler roda, fica um registro de execução. É somente de consulta e não tem endpoints de criação, edição nem exclusão. O caminho é /spaces/{spaceId}/schedulers/{schedulerId}/logs.

{
  "sys": {
    "id": "5nRt8YcVm2Qb7WxZpK4dGhJ9sL",
    "type": "SchedulerLog",
    "space": { "sys": { "id": "HnQ32YiH", "type": "Refer", "targetType": "Space" } },
    "requestId": "3trmXRM8dNvQ2LbYpK7fHsJ3gWc4Rt",
    "success": true,
    "createdBy": { "sys": { "id": "7kQm2ZbTn4Rc9WvXpL3dHsY6fJ", "type": "Refer", "targetType": "Scheduler" } },
    "createdAt": "2026-09-03T00:00:02.503Z",
    "updatedBy": { "sys": { "id": "7kQm2ZbTn4Rc9WvXpL3dHsY6fJ", "type": "Refer", "targetType": "Scheduler" } },
    "updatedAt": "2026-09-03T00:00:02.503Z"
  }
}

Todos os valores ficam dentro de sys e não há propriedades do corpo. As chaves sem valor ficam de fora da resposta (no exemplo acima não há error).

Não existe o campo scheduler. Qual Scheduler gerou o registro é indicado pelo sys.createdBy, cujo targetType é "Scheduler". O sys.updatedBy também é o mesmo Scheduler.

Também não existem os campos startedAt, endedAt e result nem um campo de tempo decorrido. Quanto tempo um ciclo levou e o valor que o Script devolveu estão no ScriptLog que tem o mesmo requestId (sys.durationMs, sys.value, sys.statusCode). A composição desses campos é abordada em Recurso e endpoints do Script.

Um ciclo deixa dois registros. Um é este SchedulerLog enxuto, e o outro é o ScriptLog, que contém a execução em si (o sys.trigger do ScriptLog aponta para este Scheduler). Os dois são ligados pelo mesmo requestId.

O registro é escrito uma vez depois que a execução termina e não muda mais. Uma execução bem-sucedida desaparece após 1 hora, e uma execução malsucedida, após 3 dias. Não há na resposta um campo com o horário de expiração; quando chega a hora, o registro desaparece. Um valor que precise ficar guardado por mais tempo que isso deve ser salvo como Content dentro do Script.

Erros

São os códigos que você encontra ao lidar com o Scheduler. Para os códigos comuns a todos os recursos, consulte Erros comuns.

API

A URL base de todos os endpoints abaixo é https://cma.weegloo.com/v1, e o cabeçalho Authorization precisa de um token Bearer que autentique na CMA. Como o Scheduler não tem sys.version, não envie o cabeçalho X-Weegloo-Version na edição.

Documentos relacionados

• Script: o recurso que o Scheduler executa. Aborda a estrutura de definição e os tipos de statement.
• Webhook: o recurso que executa um Script por evento, e não por horário.
• SpaceRole: o papel que contém a permissão de configuração SETTING_SCHEDULER e a permissão Execute do Script.
• Conceito de Scheduler: para que serve o recurso e como manuseá-lo no console.