Recurso e endpoints do Script

Um Script é um endpoint de backend declarativo que o frontend chama por HTTP (o conceito e a estrutura de nível superior são abordados na Visão geral do Script). Esta página aborda a estrutura sys e as propriedades do corpo do recurso Script, a especificação dos endpoints HTTP que criam e executam um Script, e o registro de execução ScriptLog.

Criar e gerenciar um Script (listar, consultar, criar, atualizar e excluir) é feito na CMA (https://cma.weegloo.com/v1). A execução fica a cargo do caminho de execução do host dedicado de Script (https://script.weegloo.com/v1), e esse único caminho de execução aceita os dois: um token de Weegloo User e o token de um membro que se cadastrou no produto (um ServiceUser). A ACMA não tem a API de Script, e as APIs de entrega somente leitura (CDA, ACDA) também não.

Um Script é um recurso que carrega um version e é um recurso faturável sujeito a um limite de quantidade por plano. Diferente de Content ou Media, no entanto, ele não tem status de publicação. Seu sys não tem propriedades relacionadas a publicação como status ou publish; apenas o version aumenta a cada alteração. Como não há conceito de publicação nem de cancelamento de publicação, a exclusão também ocorre imediatamente, sem cancelar a publicação primeiro.

Estrutura do recurso

A seguir está a resposta de consulta única do Script "t6-http". Junto com sys (propriedades de sistema), ele tem como propriedades do corpo name, definition e, abrindo e fechando os caminhos de chamada, directCallEnabled·anonymousCallEnabled.

{
  "sys": {
    "id": "3trmXRMZcTAjDnphewjj1AaxYcaxlK",
    "type": "Script",
    "space": { "sys": { "id": "6jSUUAWT", "type": "Refer", "targetType": "Space" } },
    "createdBy": { "sys": { "id": "3p4tcFbQYJNvYTBJf2rYKr42xegQLJ", "type": "Refer", "targetType": "User" } },
    "createdAt": "2026-07-15T12:35:47.575Z",
    "updatedBy": { "sys": { "id": "3p4tcFbQYJNvYTBJf2rYKr42xegQLJ", "type": "Refer", "targetType": "User" } },
    "updatedAt": "2026-07-15T12:35:47.575Z",
    "version": 1
  },
  "name": "t6-http",
  "directCallEnabled": true,
  "anonymousCallEnabled": false,
  "definition": {
    "method": "Post",
    "statements": [
      {
        "name": "resp",
        "method": "POST",
        "url": "https://postman-echo.com/post",
        "headers": [ { "key": "Content-Type", "value": "application/json", "secret": false } ],
        "body": { "prompt": "{ /payload/prompt }" },
        "timeoutMs": 10000,
        "retry": 0,
        "type": "Http"
      },
      {
        "value": { "status": "{ /resp/status }", "prompt": "{ /resp/body/json/prompt }" },
        "isError": false,
        "statusCode": 200,
        "type": "Return"
      }
    ]
  }
}

Chaves principais:

• sys.id: O identificador único do Script. Entra em {scriptId} nos caminhos de consulta única, atualização, exclusão e execução.
• name: O nome do Script (1 a 64 caracteres). Usado na listagem em tela e para identificação de gerenciamento.
• definition: O ScriptDefinition que declara o que este Script faz. É composto pelo método de chamada (method), pelo array de statements (statements) e por um schema de payload opcional (payloadSchema). Sua estrutura detalhada é abordada em Definição e nome abaixo e em a estrutura de nível superior na Visão geral do Script.
• directCallEnabled: Se este Script pode ser chamado diretamente por /execute (booleano, true se omitido). Se false, a chamada direta é rejeitada. Os outros caminhos para executar este Script permanecem como estão. A ação de vínculo (script) de um Webhook e um Scheduler não passam por este endpoint, portanto o executam normalmente.
• anonymousCallEnabled: Se este Script pode ser chamado sem autenticação por /execute/anonymous (booleano, false se omitido). Se ativado, até um terceiro que não consegue enviar um token pode executar este Script por aquele caminho, e a execução ocorre com a identidade do autor. As condições e as regras de salvamento são abordadas em Chamada anônima abaixo.

Observe que sys não tem status, publish nem archive. Um Script não é um recurso que é publicado em um caminho de entrega; é um recurso que você cria e executa através das APIs de gerenciamento.

Propriedades de sistema (sys)

Todo Script carrega propriedades de sistema comuns no objeto sys. space, createdBy e updatedBy vêm no formato Refer ({ "sys": { "id", "type": "Refer", "targetType" } }).

O status (status de publicação) e o publish (histórico de publicação) presentes no sys de Content, Content Type e Media não existem em um Script, porque um Script não é publicado. Também não há a propriedade archive. Por isso, o version de um Script aumenta puramente conforme o número de criações e atualizações, sem nenhuma publicação.

Definição e nome (name, definition)

Um Script tem quatro propriedades do corpo: name, definition, directCallEnabled e anonymousCallEnabled.

Chaves de definition (ScriptDefinition):

Os tipos e campos de cada statement que você coloca no array statements são abordados no Catálogo de statements, e as expressões { /pointer } que encaminham valores são abordadas em Expressões de valor.

No exemplo "t6-http" acima, o definition tem method Post; ele chama uma API externa com um statement Http e então devolve esse resultado com um statement Return. Um statement que faz uma chamada externa, como Http, declara o seu próprio tempo, e esse tanto é somado ao tempo concedido a uma execução (veja O tempo concedido a uma execução).

Restrições

As restrições estáticas acima são verificadas no momento de salvar (criar/atualizar), e uma violação faz com que o salvamento seja rejeitado. O número de chamadas externas e o total de statements não são erros de validação, mas limites de plano, portanto a mesma definição é permitida em um plano superior.

No momento de salvar, as permissões e os tipos de recurso também são verificados.

• Verifica-se se o autor realmente possui as permissões de recurso e de ação que esses statements utilizam (se qualquer uma faltar, o salvamento é rejeitado; consulte Erros). Um statement que lê um membro (ServiceUser) é verificado não pelo mapa de permissões, mas pelo SETTING_SERVICE_LOGIN do settings do SpaceRole.
• Se houver um statement que altera um membro (ServiceUser), o salvamento é rejeitado. Como esse recurso é apenas de leitura no Script, não é possível salvá-lo com nenhum papel.

As regras detalhadas, o orçamento de tempo e os limites de comprimento de valor verificados durante a execução são abordados em Semântica de execução, restrições e segurança.

Um Script é um recurso faturável, e a quantidade por Organization é limitada por plano (Free 5 / Basic 10 / Pro 50 / Enterprise ilimitado). Quando o limite é atingido, a criação de um novo Script é rejeitada (consulte limites de quantidade por plano).

Chamada anônima (anonymousCallEnabled)

Se você deixar anonymousCallEnabled como true, aquele Script passa a ser executável também por um caminho dedicado sem autenticação.

{method} https://script.weegloo.com/v1/spaces/{spaceId}/scripts/{scriptId}/execute/anonymous

Os casos em que isso é necessário são raros. É um dispositivo para terceiros que precisam nos enviar um callback, como uma processadora de pagamentos (PG·MoR), mas não suportam cabeçalhos personalizados e portanto não têm como enviar um Access Token. Todo chamador capaz de enviar um token usa o caminho autenticado (/execute).

• O caminho autenticado continua o mesmo. /execute continua exigindo um Bearer token e a permissão Execute sobre o Script. O único caminho que fica sem autenticação é este, /execute/anonymous.
• Ele não aceita token. Mesmo que você envie um token, ele é ignorado, e a execução é sempre com a identidade do autor. Para executar com a identidade do chamador, use /execute.
• É preciso passar por dois gates. Se anonymousCallEnabled for false, a requisição é rejeitada como acesso não autenticado; se directCallEnabled for false, ela é rejeitada porque a chamada direta está bloqueada. O código devolvido varia conforme o gate em que ela parou (consulte Erros). Como a permissão de anônimo é verificada primeiro, um chamador sem credenciais não consegue descobrir o estado de configuração daquele Script.
• A partir daí, é igual a /execute. O método HTTP da requisição precisa coincidir com definition.method, e a chamada consome a cota de execução de Script da Organization e é medida como uso.
• Este caminho fica no mesmo host de Script do caminho de execução autenticado (https://script.weegloo.com/v1).

É executado com a identidade do autor

Como não há chamador, a execução ocorre com a identidade do usuário que criou aquele Script (sys.createdBy).

• O createdBy·updatedBy de um Content ou Media criado ou editado dentro do Script recebe o autor (não o chamador anônimo, porque não há outra identidade a quem atribuir).
• O createdBy: ":self" de where também é resolvido para o autor, e não para o chamador. Manter um filtro de propriedade escrito supondo um chamador autenticado e ativar o anônimo abriria silenciosamente os recursos do autor; por isso, uma definição assim nem chega a ser salva (veja abaixo).

Verificações adicionais ao salvar

Um Script com anonymousCallEnabled igual a true recebe uma regra a mais.

É que a chamada anônima não tem identidade de chamador e, por isso, :self é resolvido para o autor. Isso impede, já no momento de salvar, que um filtro de propriedade escrito supondo um chamador autenticado seja silenciosamente furado.

A autenticação efetiva é feita pelo próprio Script

Neste caminho não existe a autenticação que a plataforma impõe. Qualquer pessoa que conheça a URL pode chamá-lo, e essa chamada consome a cota de execução de Script da Organization, sem um rate limit próprio. Por isso, um Script anônimo precisa verificar por conta própria a requisição que recebeu.

• Coloque no início um Signature para conferir a assinatura sobre { /rawPayload } e, se não passar, interrompa ali mesmo com um Return. O exemplo completo está na verificação de assinatura de webhook do cookbook.
• Se você também verificar a janela de replay com /now, impede que uma requisição antiga seja reenviada (veja /now).
• Coloque em um Script anônimo apenas o que aquele callback realmente precisa fazer. Como o Script é executado com as permissões do autor delegadas a ele, tudo o que você colocar nele fica aberto sem autenticação (veja Modelo de segurança).

ScriptLog

Cada vez que um Script é executado, fica um registro. Esse registro é o ScriptLog. Ele é somente de consulta e não tem endpoints de criação, atualização ou exclusão. O caminho é /spaces/{spaceId}/scripts/{scriptId}/logs, e a URL base não é a do host de execução, mas a da CMA, https://cma.weegloo.com/v1. Para ler, é necessária a permissão Read sobre aquele Script.

{
  "sys": {
    "id": "3trmXRM7pLdV5Rz8kWq2NcHfJt4bYs",
    "type": "ScriptLog",
    "space": { "sys": { "id": "6jSUUAWT", "type": "Refer", "targetType": "Space" } },
    "script": { "sys": { "id": "3trmXRMZcTAjDnphewjj1AaxYcaxlK", "type": "Refer", "targetType": "Script" } },
    "trigger": { "sys": { "id": "3trmXRMZcTAjDnphewjj1AaxYcaxlK", "type": "Refer", "targetType": "Script" } },
    "requestId": "3trmXRM9wTbK4Vz7hLp2QsNdRf6cYm",
    "returned": true,
    "value": { "status": 200, "prompt": "3 linhas de descrição para o vestido de verão" },
    "success": true,
    "statusCode": 200,
    "durationMs": 195,
    "createdBy": { "sys": { "id": "3p4tcFbQYJNvYTBJf2rYKr42xegQLJ", "type": "Refer", "targetType": "User" } },
    "createdAt": "2026-07-15T12:41:03.902Z",
    "updatedBy": { "sys": { "id": "3p4tcFbQYJNvYTBJf2rYKr42xegQLJ", "type": "Refer", "targetType": "User" } },
    "updatedAt": "2026-07-15T12:41:03.902Z"
  }
}

Todos os valores estão dentro de sys, e não há propriedades do corpo. As chaves sem valor ficam de fora da resposta.

trigger aponta para o que disparou esta execução. Em uma chamada direta, é o próprio Script; se foi executado pela ação de vínculo de um Webhook, é aquele Webhook; se foi um Scheduler que o rodou, é aquele Scheduler.

requestId é o mesmo valor do requestId no envelope da resposta de execução. Use este valor como referência para localizar, a partir da resposta que o chamador recebeu, o registro daquela execução.

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. Um valor que precise ficar guardado por mais tempo que isso deve ser salvo como Content dentro do Script.

createdBy aponta para a identidade com que aquela execução foi realizada. Uma execução chamada com um token de Weegloo User é aquele usuário; uma execução chamada com um token de membro (ServiceUser) é aquele membro. Em uma execução sem chamador, a identidade vem do disparador. Uma execução anônima é o autor daquele Script; uma execução que um Scheduler rodou é o usuário que criou aquele Scheduler (que pode ser diferente do autor do Script); e a que um Webhook executou é o usuário que criou aquele Webhook. O runAs de um Webhook apenas define em nome de quem as operações dentro do Script acontecem, e não altera a atribuição deste log.

Erros

São os códigos que aparecem ao chamar ou excluir um Script. Os códigos que aparecem ao salvar a definição estão em Erros em Semântica de execução, restrições e segurança, os códigos que violam as regras das expressões de valor estão em Erros em Expressões de valor, e os códigos comuns a todos os recursos, em Erros comuns.

API

A URL base dos cinco endpoints abaixo (listar, consultar, criar, atualizar e excluir) é a da CMA, https://cma.weegloo.com/v1, e é necessário um Bearer token que autentica na CMA no cabeçalho Authorization. A atualização também deve enviar o cabeçalho X-Weegloo-Version (o sys.version atual do recurso) para controle de concorrência otimista. As duas consultas de ScriptLog no final também usam essa mesma URL base da CMA.

A URL base dos dois endpoints de execução é a do host dedicado de Script, https://script.weegloo.com/v1. A execução autenticada (/execute) aceita os dois: um Bearer token com identidade de Weegloo User e um Bearer token com identidade de membro (ServiceUser); em qualquer dos casos, o chamador precisa da permissão Execute sobre aquele Script.

Só a execução anônima (/execute/anonymous) é a exceção: ela não exige cabeçalho de autenticação. Fica no mesmo host de Script e só é alcançável quando aquele Script tem anonymousCallEnabled ativado (veja Chamada anônima acima).

A resposta do exemplo de execução autenticada acima não tem return, porque o Script alvo terminou sem alcançar um Return que carrega um valor (nesse caso, statusCode assume o padrão 200). Se, como no exemplo de execução anônima, um Return devolver um valor, a resposta carrega return (ou error, se Return.isError for verdadeiro). As regras completas da resposta são abordadas em Requisição e resposta na Visão geral do Script.

Documentos relacionados

• Visão geral do Script: aborda a estrutura de nível superior do ScriptDefinition, a requisição e a resposta, e o tempo concedido a uma execução.
• Catálogo de statements: aborda os campos e resultados de cada statement que você coloca em statements.
• Expressões de valor: aborda referências { /pointer } e operações JsonLogic.
• Semântica de execução, restrições e segurança: aborda as restrições estáticas, os limites de quantidade por plano e o modelo de permissões e segurança.
• SpaceRole e ServiceUserRole: abordam como conceder a um Role as permissões de ação de um Script (incluindo Execute).