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.

Script é criado e executado na CMA (com a identidade de Weegloo User). Sob a identidade de um membro que se cadastrou no produto (um ServiceUser), você pode usá-lo da mesma forma também na ACMA. A API de Script existe apenas nessas duas APIs de gerenciamento (CMA, ACMA); ela não existe nas APIs de entrega somente leitura (CDA, ACDA).

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
  "executionMode": "Sync",        // "Sync" | "Async" (obrigatório)
  "statements": [ /* Statement[]. Executado de cima para baixo (obrigatório, 1 ou mais) */ ]
}

O payload aceita apenas JSON. O corpo da chamada é acessado pela raiz de contexto /payload ({ /payload/... }). Os cabeçalhos HTTP da requisição da chamada são referenciados pela raiz /headers ({ /headers/... }, com chaves em minúsculas). 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 (ou do resultado do polling do Async) é o seguinte.

{
  "requestId": "…",     // Identificador de execução (no Async, faça polling do resultado com este id)
  "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>   // Apenas quando Return.isError é true (neste caso "return" está ausente). Se o valor for null, ""
}

• 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).
• 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.

Modos de execução: Sync e Async

• Se houver I/O externo, apenas Async é permitido. Se qualquer statement realizar uma operação de rede, como uma chamada externa Http (ExternalIo) ou uma ingestão de arquivo de Media (MediaIngest, a partir de uma url ou base64), então executionMode deve ser Async; tentar salvá-lo como Sync é rejeitado no momento de salvar. Isso é para que a thread da requisição não seja bloqueada pela latência externa.
• É apenas uma diferença de onde a execução acontece; de qualquer forma, o resultado é o valor de Return.

As regras de como uma determinada capacidade força um modo, junto com os limites aplicáveis, são abordadas em Semântica de execução, restrições e segurança.

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",
  "executionMode": "Sync",
  "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 17 tipos de statement (CRUD e leitura de recursos, Http, SetVar, 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 e uma saga de pagamento.
• Recurso e endpoints de Script: aborda a estrutura sys do recurso Script e a especificação dos endpoints HTTP de criação e execução (/execute).

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.