Script

Script é um endpoint de backend declarativo que um frontend chama por HTTP. Em vez de escrever código de servidor, você declara "o que fazer" como JSON e o motor da WEEGLOO o executa por você. O objetivo é substituir, com um único Script, o encanamento de backend típico que dá suporte a um frontend (um BFF, Backend-for-Frontend): a autenticação, a verificação de condições (guard), o CRUD encadeado, as chamadas a APIs externas e a transformação de valores.

Este conjunto de documentos é a referência da sintaxe de Script. Os detalhes de cada parte da sintaxe são divididos entre as páginas em Documentos deste grupo abaixo.

Criar e gerenciar um Script (criar, consultar, 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). 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.

Modelo mental

• Um Script é um endpoint HTTP. O método de chamada (method) determina qual Script é executado.
• O corpo é um array statements. Eles são executados sequencialmente, de cima para baixo. É como o corpo de uma função na programação comum.
• É declaração, não código. Você não incorpora código arbitrário (FaaS); você compõe tipos de Statement predefinidos. Foi projetado menos para ser escrito à mão por uma pessoa e mais para ser gerado por um agente de IA via MCP.
• Os valores fluem por templates de JSON Pointer. Você referencia o resultado de uma etapa anterior, o payload de entrada ou uma variável com { /pointer } e o passa para a próxima etapa. Quando precisa de uma condição ou de um cálculo, você usa operadores JsonLogic. As regras completas são abordadas em Expressões de valor.

Estrutura de nível superior (ScriptDefinition)

Um único Script é definido pela seguinte estrutura ScriptDefinition.

{
  "method": "Post",               // Get | Post | Put | Patch | Delete. Método HTTP correspondido na chamada (obrigatório)
  "payloadSchema": { /* ... */ }, // (opcional) JSON Schema. Se presente, valida o payload da requisição antes da execução
  "statements": [ /* Statement[]. Executado de cima para baixo (obrigatório, 1 ou mais) */ ],
  "secrets": [ /* (opcional) Lista de valores secretos. Lidos nos Statements com { /secrets/<key> } */ ]
}

O payload aceita apenas um objeto JSON. O corpo da chamada é acessado pela raiz de contexto /payload ({ /payload/... }) e, se você precisar da string original antes do parse, por /rawPayload (nos casos em que o cálculo é feito sobre os bytes enviados, como na verificação de assinatura). Os cabeçalhos HTTP da requisição da chamada são referenciados pela raiz /headers ({ /headers/... }, com chaves em minúsculas). O instante em que a execução começou está na raiz /now. Os valores secretos declarados em secrets são lidos pela raiz /secrets ({ /secrets/<key> }). O conjunto completo de raízes de contexto é abordado em Expressões de valor.

Requisição e resposta

No final, um Script retorna o valor de seu Statement Return ao chamador. O formato da resposta é o seguinte.

{
  "requestId": "…",     // Identificador de execução
  "durationMs": 1234,   // Tempo de execução (ms)
  "statusCode": 200,    // O statusCode do Return alcançado (padrão 200)
  "return": <value>     // Apenas quando Return.isError é false. Se o valor for null, ""
  // "error": <value>   // Quando Return.isError é true, ou quando a execução falhou (neste caso "return" está ausente). Se o valor for null, ""
}

• requestId é o identificador desta execução. O mesmo valor entra no sys.requestId do ScriptLog que aquela execução deixou, portanto ele é a chave para localizar esta execução nos logs.
• return e error nunca aparecem juntos. O isError do Statement Return decide qual dos dois é.
• Se o Script terminar sem alcançar um Statement Return, return e error estão ambos ausentes e o statusCode é o padrão (200).
• Quando a execução falha, o error é preenchido mesmo sem um Return. Se a falha tem origem no lado do chamador, como um payload inválido, e nenhum Try a captura, o motivo da falha entra em error e o statusCode passa a ser o código correspondente àquela falha (um payload inválido dá 4xx; se uma chamada externa ou um envio de e-mail falha, 502). Na prática, é esta a forma de resposta de erro que você encontra com mais frequência. Uma execução que ultrapassa o orçamento de tempo responde com 408, e não com o envelope.
• Se um valor for null, esse campo é emitido como uma string vazia "".

Você controla o corpo da resposta e o código de status com o value, o isError e o statusCode do Return. Os detalhes são abordados em Return no Catálogo de Statements.

O tempo concedido a uma execução

Um Script é executado inline, no caminho que processa a requisição da chamada. Não existe um fluxo que o transfira para segundo plano nem que devolva antes uma resposta de aceite: o corpo da resposta da chamada é o próprio resultado da execução. Também não existe um caminho de polling para buscar o resultado mais tarde.

O tempo permitido para uma execução é de no máximo 180 segundos. O tempo permitido é a base de 30 segundos somada ao tempo que as chamadas externas (Http, EmailSend) podem usar, e um Http que envia arquivos soma também o tempo de download de cada arquivo.

• Trabalhos que não são chamadas externas, como ler e gravar recursos, são processados dentro da base de 30 segundos.
• Uma iteração (Loop, ResourceForEach) multiplica o tempo do seu interior pelo número de iterações. Por isso, uma iteração sem chamada externa precisa terminar dentro da base de 30 segundos.
• Mesmo que o valor calculado passe de 180 segundos, o salvamento e a execução acontecem, e a execução é interrompida no momento em que chega a 180 segundos.

O tempo que cada Statement acrescenta e exemplos de cálculo são abordados em Orçamento de tempo.

Exemplo mínimo

Cria um Content de postagem a partir do título e do corpo no payload da requisição, publica-o imediatamente e, em seguida, retorna o sys.id criado.

{
  "method": "Post",
  "statements": [
    { "type": "ResourceCreate", "resource": "Content",
      "contentType": { "sys": { "id": "ct_post" } },
      "fields": {
        "title": { "en-US": "{ /payload/fields/title }" },
        "body":  { "en-US": "{ /payload/fields/body }" }
      },
      "publish": true,
      "name": "post" },
 
    { "type": "Return", "value": { "id": "{ /post/sys/id }" }, "statusCode": 201 }
  ]
}

• ResourceCreate cria o Content e vincula o resultado ao nome post.
• Return retorna { "id": <novo Content id> } com 201.
• Por que os valores de fields de um Content são mapas de locale ({ "en-US": ... }) é abordado em Mapas de locale em Expressões de valor.

Você encontrará cenários mais variados no Cookbook.

Documentos deste grupo

• Expressões de valor: aborda referências { /pointer }, literais, operações e condições JsonLogic, raízes de contexto e mapas de locale. É o núcleo da sintaxe.
• Catálogo de Statements: aborda os campos e resultados dos 25 tipos de Statement (CRUD e leitura de recursos, Http, EmailSend, SetVar, Cache, ParseJson, Signature, Hash, Regex, If, Loop, Parallel, Try, Return).
• Semântica de execução, restrições e segurança: aborda a ordem de execução, os guards, a compensação, o bloqueio otimista, os erros, as restrições estáticas e os limites de plano, e o modelo de segurança.
• Cookbook: aborda exemplos completos como upsert, um guard de crédito, um proxy de LLM, a paginação, a execução paralela, uma saga de pagamento e a verificação de assinatura de webhook.
• Recurso e endpoints de Script: aborda a estrutura sys do recurso Script, a especificação dos endpoints HTTP de autoria e de execução (/execute) e o log de execução ScriptLog.

Se esta é a sua primeira vez, recomendamos ler a partir desta página na ordem Expressões de valor e depois Catálogo de Statements. O Cookbook também vale a pena percorrer inteiro.