O SDK dos scripts
Os dez módulos do SDK api_manager — datasources, HTTP, logs, ficheiros de upload, secrets, notificações, workflows, contas, relatórios e IA — com exemplos Python.
Dentro de um script, a app inteira está ao alcance de um import. O SDK
chama-se api_manager e importa-se módulo a módulo:
from api_manager import db, http, log, files, secrets, notify, workflow, users, reports, ai
Estes dez nomes são a superfície pública inteira do SDK — o que não está aqui não existe em execução:
| Módulo | Para quê |
|---|---|
db |
Consultar os datasources da app (Oracle, PostgreSQL, MySQL/MariaDB, SQL Server, …). |
http |
Pedidos HTTP a serviços externos, com JSON automático. |
log |
Escrever linhas nos logs da execução. |
files |
Ler ficheiros enviados por upload numa API. |
secrets |
Ler segredos da app, decifrados no servidor. |
notify |
Notificações in-app e emails aos utilizadores da app. |
workflow |
Arrancar processos, acordar esperas e decidir tarefas humanas. |
users |
Criar e alterar as contas da app e atribuir-lhes papéis. |
reports |
Gerar os relatórios da app em PDF ou Excel. |
ai |
Usar os modelos de IA da app: texto, JSON, ferramentas, embeddings, imagens, áudio e lotes. |
O editor autocompleta tudo isto — os nomes, os parâmetros e a documentação de cada função aparecem enquanto escreves.
Dica
O botão Prompt para LLM na barra do editor abre o guia completo do SDK, pronto a copiar com Copiar tudo. Cola-o no Claude, ChatGPT ou outro assistente, junto com o que queres que o script faça — o assistente passa a conhecer o contrato exacto e não inventa funções que não existem.

db — os datasources da app
Os datasources configurados na app referenciam-se pelo nome. Duas funções:
from api_manager import db
crm = db("Dados CRM")
linhas = crm.query( # lista de dicts (coluna -> valor)
"select id, nome from contas where cidade = ?", ["Lisboa"]
)
conta = crm.query_one( # a primeira linha, ou None
"select * from contas where id = ?", [42]
)
params é uma lista posicional. Os placeholders são os do motor do
datasource:
| Motor | Placeholders | Exemplo |
|---|---|---|
| PostgreSQL | $1, $2, … |
where id = $1 |
| MySQL / MariaDB | ? |
where id = ? |
| Oracle | :1, :2, … |
where id = :1 |
Se o datasource não existir, a chamada lança um erro (e a execução termina em Erro, se não o apanhares).
Atenção
Datas em Oracle: evita passá-las como parâmetro — o transporte em JSON
torna o tipo ambíguo. Prefere o literal no SQL:
TO_DATE('2026-06-25','YYYY-MM-DD').
Uma coluna binária (bytea, blob, varbinary) chega em bytes, e um
parâmetro em bytes grava-se como binário:
foto = crm.query_one("select foto from contas where id = ?", [42])["foto"]
crm.query("update contas set foto = ? where id = ?", [novos_bytes, 42])
Ligação e transacções
Todas as queries de uma execução ao mesmo datasource correm na mesma ligação, que é só dessa execução. Por isso podes usar transacções:
crm.query("begin")
crm.query("update contas set saldo = saldo - ? where id = ?", [100, 1])
crm.query("update contas set saldo = saldo + ? where id = ?", [100, 2])
crm.query("commit")
O que ficar por confirmar quando a execução termina (com erro, no tempo
limite ou cancelada) é desfeito. Uma query que falha fecha a ligação, e a
seguinte abre outra, já fora da transacção. No SQL Server, a transacção
começa com begin transaction. No Oracle não há begin: as alterações só
ficam gravadas com um commit.
http — pedidos a serviços externos
Cinco verbos, todos com JSON automático — um body dict ou lista segue como
JSON, e uma resposta JSON chega já descodificada:
from api_manager import http, log
r = http.get("https://api.exemplo.com/clientes")
# r = {"status": int, "ok": bool, "body": <json descodificado ou texto>}
if r["ok"]:
log("recebidos", len(r["body"]), "clientes")
r = http.post(
"https://api.exemplo.com/leads",
body={"nome": "Vininha & Filhos", "origem": "keplin"},
headers={"Authorization": "Bearer abc123"},
)
Também existem http.put(url, body, headers), http.patch(url, body, headers) e http.delete(url, headers). r["ok"] é verdadeiro para
respostas 2xx — um 404 ou 500 não lança excepção, verifica tu o estado.
log — os logs da execução
from api_manager import log
log("a processar", 42, {"fase": "inicial"})
Aceita vários argumentos, como o print — e cada chamada é uma linha nos
logs da execução, visível no painel Resultado da execução e no
histórico Execuções. O print clássico também é capturado, mas log é
a forma canónica do SDK.

files — ficheiros enviados por upload
Quando uma API da app tem um argumento do tipo Upload, o cliente envia
um ficheiro e o script recebe-o em input["args"] como um handle — os
bytes ficam em disco, não na memória. O módulo files opera sobre esse
handle:
from api_manager import files
def main(input):
f = input["args"]["ficheiro"] # o handle do upload
texto = files.read_text(f) # str (utf-8)
dados = files.read(f) # bytes
caminho = files.path(f) # caminho absoluto em disco
files.save(f, "ultimo-recebido.csv") # copia para a pasta do script
return {"nome": f["filename"], "tamanho": f["size"]}
O handle traz filename, mimeType e size — úteis para validar antes de
processar.
secrets — segredos da app
Tokens e chaves guardam-se na página Secrets da app (árvore lateral, grupo App), cifrados. O script lê-os pela chave:
from api_manager import secrets
token = secrets.get("STRIPE_KEY") # -> str | None
if token is None:
raise RuntimeError("Secret STRIPE_KEY não configurado nesta app.")
O valor é decifrado no servidor, no momento da execução — nunca aparece no browser nem fica no código.

Atenção
Não faças log(token). Os logs ficam no histórico de execuções — um
segredo escrito num log deixou de ser segredo.
notify — notificações e emails
A app tem dois canais fixos — um in-app e um de email — activáveis
nas definições de Notificações da app (é lá que vive a configuração
SMTP e o remetente). users são usernames de utilizadores da app;
roles expandem para todos os membros do role.
In-app, em tempo real:
from api_manager import notify
r = notify.send(
"Relatório pronto",
subtitle="Relatórios mensais",
body="O relatório mensal está disponível.",
users=["joao"],
roles=None,
data={"url": "/relatorios/42"},
)
# r = {"recipients": int, "delivered": int}
delivered conta os entregues em tempo real, a quem está ligado; os
restantes ficam no inbox e recebem ao entrar.
Email:
r = notify.email(
"Alerta de stock",
to=["chefe@empresa.pt"], # endereços livres
users=None,
roles=["admin"], # e/ou utilizadores e roles da app
text="Stock abaixo do mínimo.",
html=None,
)
# r = {"accepted": [emails], "skipped": [usernames sem email]}
O envio SMTP acontece de forma assíncrona no servidor — o script não fica à
espera. attachments aceita anexos com o conteúdo em base64 (ver reports
abaixo para o caso típico).
workflow — os processos da app
Um script pode arrancar um processo, acordar quem está à espera de um
evento, e decidir tarefas humanas. O processo referencia-se pelo nome (ou
pelo identificador estável); key é a chave do registo sobre o qual ele
corre:
from api_manager import workflow
r = workflow.start("Aprovação de despesa", 42, data={"valor": 1200})
# r = {"instanceId": int}
r = workflow.signal("visto", key=42)
# r = {"woken": int}
abertas = workflow.tasks("joao")
# tarefas abertas desse utilizador da app, com as decisões possíveis
r = workflow.complete(task=17, outcome="aprovar", as_user="joao",
data={"nota": "ok"})
# r = {"ok": bool}
Regras que importam:
workflow.startdevolve assim que o motor chega à primeira espera — nunca fica à espera de que o processo acabe.workflow.signalsemkeyacorda todos os processos parados nesse evento;{"woken": 0}não é erro — pode não haver ninguém à espera.- Em
workflow.complete,as_useré obrigatório (quem decide fica no histórico) e a tarefa tem de estar atribuída a esse utilizador. Os valores deoutcomesão as saídas do nó da tarefa — os mesmos que a pessoa vê como botões. Não inventes nomes.
users — as contas da app
Um script cria e altera as contas da app e atribui-lhes papéis que já
existem. Os papéis e as permissões criam-se no construtor; o módulo não os
cria nem altera. user é o id (número) ou o username (texto) da conta:
from api_manager import users
users.roles() # ["gestor", "vendedor"]
u = users.create("ana", password=input["args"]["password"],
email="ana@empresa.pt", name="Ana Silva", roles=["vendedor"])
# u = {"id", "username", "email", "name", "disabled", "roles",
# "createdAt", "lastLoginAt"}
users.get("ana") # a conta, ou None
users.list(role="vendedor") # sem as contas desactivadas
users.update("ana", name="Ana M. Silva", disabled=True)
users.set_password("ana", nova)
users.set_roles("ana", ["vendedor", "gestor"])
users.add_role("ana", "gestor")
users.remove_role("ana", "vendedor")
Regras que importam:
- As regras são as do construtor e do registo público: username de 3 a 120
caracteres (letras, números, ponto, hífen,
_e@), email válido, palavra-passe de 8 a 200 caracteres, e username e email livres, também um contra o outro. - As contas chegam ao script sem a palavra-passe. Sem
password, a conta só entra depois de lhe definirem uma. users.updatesó muda os campos indicados, eemail=Noneapaga o email.users.listjunta as contas desactivadas cominclude_disabled=True.- As alterações valem logo: uma conta desactivada perde o acesso no pedido
seguinte, e
set_passwordtermina as sessões abertas da conta. - Cada alteração fica na auditoria, com quem fez o script correr e o nome do script.
- Chama
passwordao argumento da palavra-passe: o histórico Execuções esconde os argumentos com esse nome.
Uma falha levanta users.Error, com um code estável: invalid_username, invalid_email, invalid_name, weak_password, username_taken, email_taken, unknown_role, not_found ou
invalid_request.
def main(input):
a = input["args"]
try:
u = users.create(a["username"], password=a["password"], roles=["vendedor"])
except users.Error as e:
if e.code == "username_taken":
return {"ok": False, "erro": "Esse username já existe."}
raise
return {"ok": True, "id": u["id"]}
reports — gerar relatórios da app
O documento é gerado no servidor, com os dados da app, a partir de um relatório existente:
from api_manager import notify, reports
r = reports.render("Facturas do mês", {"mes": "2026-03"})
# r = {"filename", "pages", "format", "mime", "bytes", "base64"}
notify.email(
"Facturas de Março",
to=["financeiro@empresa.pt"],
text="Segue em anexo.",
attachments=[{"filename": r["filename"], "content": r["base64"]}],
)
O terceiro argumento opcional é o formato: "pdf" (omissão) ou "xlsx".
Os parâmetros são os que o relatório declara. No resultado, bytes vem
pronto a gravar em disco e base64 pronto a anexar num email.
Um script corre sem ninguém com sessão: reports.render e os verbos de
workflow lêem e escrevem os dados como a própria app, com todas as APIs
activas, tanto num agendamento como no Executar agora.
ai — os modelos de IA da app
Os scripts pedem aos modelos de IA que a app configurou em Modelos de IA, pelo nome do alias. As chaves dos fornecedores ficam no servidor e o script nunca as vê:
from api_manager import ai
def main(input):
resumo = ai.chat("Resume este pedido numa frase: " + input["args"]["pedido"])
dados = ai.json(
"Extrai o nome e o email do cliente: " + input["args"]["pedido"],
schema={
"type": "object",
"properties": {"nome": {"type": "string"}, "email": {"type": "string"}},
"required": ["nome", "email"],
},
)
vector = ai.embed(resumo["text"])
return {"resumo": resumo["text"], "cliente": dados, "dimensoes": len(vector)}
| Função | Devolve |
|---|---|
ai.chat(prompt, ...) |
Um dict com text, stop_reason, usage, model, provider e alias. |
ai.json(prompt, schema=..., ...) |
O JSON da resposta, já validado contra o schema. |
ai.embed(textos) |
Um vector por texto (uma lista de números). |
ai.models() |
Os aliases da app, com o uso e o modelo de cada um. |
ai.run(prompt, tools=[...], ...) |
A resposta final de uma tarefa em que o modelo usa funções do script, com os passos. |
ai.image(prompt, ...) |
As imagens geradas, já guardadas na app. |
ai.transcribe(ficheiro, ...) |
O texto de uma gravação. |
ai.speak(texto, ...) |
O áudio da voz, já guardado na app. |
ai.batch.submit(pedidos, ...) |
O id de um lote processado em segundo plano; ai.batch.get, ai.batch.results e ai.batch.cancel seguem-no. |
Os parâmetros, os ficheiros, os códigos de erro e os limites estão em Usar a IA nos scripts, Ferramentas e lotes e Imagens e áudio.
Um exemplo completo
Do género do script atualizar_indicadores da app Gestão de Clientes —
lê o pipeline, escreve logs úteis e avisa quando há fechos próximos:
from datetime import date, timedelta
from api_manager import db, log, notify
def main(input):
crm = db("Dados CRM")
abertas = crm.query_one(
"select count(*) as n, coalesce(sum(valor), 0) as total "
"from oportunidades where fase not in ('fechada_ganha', 'fechada_perdida')"
)
limite = (date.today() + timedelta(days=7)).isoformat()
fechos = crm.query(
"select titulo, data_fecho from oportunidades "
"where fase not in ('fechada_ganha', 'fechada_perdida') "
"and data_fecho <= ? order by data_fecho",
[limite],
)
log("pipeline:", abertas["n"], "oportunidades /", abertas["total"], "EUR")
if fechos:
notify.send(
"Fechos esta semana",
body=f"{len(fechos)} oportunidades com fecho previsto até {limite}.",
roles=["comercial"],
)
return {
"oportunidades_abertas": abertas["n"],
"valor_pipeline": abertas["total"],
"fechos_proximos_7_dias": len(fechos),
}
Limites e boas práticas
- O resultado de
maintem de ser serializável em JSON; máximo 32 MB. - Cada execução respeita o Tempo limite do script (30 segundos a 10 minutos) — ao excedê-lo, o processo é terminado e fica Timeout.
- As execuções são isoladas: não dependas de variáveis de uma execução anterior. Persiste em ficheiros da pasta do script ou num datasource.
- Faz
log(...)em cada fase relevante — é o que vais ler quando algo falhar às 7h00 de um domingo. - Apanha os erros recuperáveis e regista-os; deixa subir os fatais — uma excepção não apanhada marca a execução como Erro, e é isso que queres ver no histórico quando algo está realmente mal.
- Não imprimas segredos, e lê-os sempre de
secrets— nunca os escrevas no código.
Perguntas frequentes
from api_manager import db falha no meu computador.
É esperado: o módulo api_manager só existe em execução na plataforma —
é lá que ele é injectado. No editor tens o autocompletar completo do SDK; o
ficheiro api_manager.py que vês na pasta do script existe só para isso.
db("nome") diz que o datasource não existe.
O nome tem de ser exactamente o do datasource na app (ex.: Dados CRM, com maiúsculas e espaço). Vê a lista na secção Datasources da
árvore.
O notify.email devolveu accepted mas o email não chegou.
O envio SMTP é assíncrono — accepted significa que o email seguiu para o
canal de email da app. Confirma a configuração SMTP nas definições de
Notificações da app e a caixa de spam do destinatário.
Posso usar o SDK na validação de uma janela?
Sim — a validação corre no mesmo ambiente do script principal, com o mesmo
input e o mesmo SDK. Ver Agendamentos.