L'SDK degli script
I dieci moduli dell'SDK api_manager — datasource, HTTP, log, file di upload, secrets, notifiche, workflow, account, report e IA — con esempi in Python.
Dentro uno script, l'app intera è a portata di un import. L'SDK si chiama
api_manager e si importa modulo per modulo:
from api_manager import db, http, log, files, secrets, notify, workflow, users, reports, ai
Questi dieci nomi sono l'intera superficie pubblica dell'SDK — quello che non è qui non esiste in esecuzione:
| Modulo | A cosa serve |
|---|---|
db |
Interrogare i datasource dell'app (Oracle, PostgreSQL, MySQL/MariaDB, SQL Server, …). |
http |
Richieste HTTP a servizi esterni, con JSON automatico. |
log |
Scrivere righe nei log dell'esecuzione. |
files |
Leggere file inviati tramite upload in un'API. |
secrets |
Leggere i segreti dell'app, decifrati sul server. |
notify |
Notifiche in-app ed email agli utenti dell'app. |
workflow |
Avviare processi, svegliare attese e decidere attività umane. |
users |
Creare e modificare gli account dell'app e assegnare loro dei ruoli. |
reports |
Generare i report dell'app in PDF o Excel. |
ai |
Usare i modelli di IA dell'app: testo, JSON, strumenti, embedding, immagini, audio e lotti. |
L'editor completa automaticamente tutto questo — i nomi, i parametri e la documentazione di ogni funzione compaiono mentre scrivi.
Suggerimento
Il pulsante Prompt per LLM nella barra dell'editor apre la guida completa dell'SDK, pronta da copiare con Copia tutto. Incollala in Claude, ChatGPT o un altro assistente, insieme a quello che vuoi che lo script faccia — l'assistente arriva a conoscere il contratto esatto e non inventa funzioni che non esistono.

db — i datasource dell'app
I datasource configurati nell'app si richiamano per nome. Due funzioni:
from api_manager import db
crm = db("Dados CRM")
linhas = crm.query( # elenco di dict (colonna -> valore)
"select id, nome from contas where cidade = ?", ["Lisboa"]
)
conta = crm.query_one( # la prima riga, oppure None
"select * from contas where id = ?", [42]
)
params è un elenco posizionale. I segnaposto sono quelli del motore del
datasource:
| Motore | Segnaposto | Esempio |
|---|---|---|
| PostgreSQL | $1, $2, … |
where id = $1 |
| MySQL / MariaDB | ? |
where id = ? |
| Oracle | :1, :2, … |
where id = :1 |
Se il datasource non esiste, la chiamata solleva un errore (e l'esecuzione termina in Errore, se non lo intercetti).
Attenzione
Date in Oracle: evita di passarle come parametro — il trasporto in JSON rende
il tipo ambiguo. Preferisci il letterale nell'SQL:
TO_DATE('2026-06-25','YYYY-MM-DD').
Una colonna binaria (bytea, blob, varbinary) arriva come bytes, e un
parametro in bytes si salva come binario:
foto = crm.query_one("select foto from contas where id = ?", [42])["foto"]
crm.query("update contas set foto = ? where id = ?", [novos_bytes, 42])
Connessione e transazioni
Tutte le query di un'esecuzione verso lo stesso datasource passano per la stessa connessione, che appartiene solo a quell'esecuzione. Per questo puoi usare le transazioni:
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")
Ciò che non è ancora confermato quando l'esecuzione termina (con errore, al
limite di tempo o annullata) viene annullato. Una query che fallisce chiude
la connessione, e la successiva ne apre un'altra, già fuori dalla
transazione. In SQL Server, una transazione inizia con begin transaction.
Oracle non ha begin: le modifiche si salvano solo con un commit.
http — richieste a servizi esterni
Cinque verbi, tutti con JSON automatico — un body dict o lista parte come JSON,
e una risposta JSON arriva già decodificata:
from api_manager import http, log
r = http.get("https://api.exemplo.com/clientes")
# r = {"status": int, "ok": bool, "body": <json decodificato o testo>}
if r["ok"]:
log("ricevuti", len(r["body"]), "clienti")
r = http.post(
"https://api.exemplo.com/leads",
body={"nome": "Vininha & Filhos", "origem": "keplin"},
headers={"Authorization": "Bearer abc123"},
)
Esistono anche http.put(url, body, headers), http.patch(url, body, headers) e http.delete(url, headers). r["ok"] è vero per le risposte 2xx —
un 404 o un 500 non solleva un'eccezione, lo stato lo controlli tu.
log — i log dell'esecuzione
from api_manager import log
log("in elaborazione", 42, {"fase": "inicial"})
Accetta più argomenti, come il print — e ogni chiamata è una riga nei log
dell'esecuzione, visibile nel pannello Esito dell'esecuzione e nella
cronologia Esecuzioni. Anche il print classico viene catturato, ma log è
la forma canonica dell'SDK.

files — file inviati tramite upload
Quando un'API dell'app ha un argomento di tipo Upload, il client invia un
file e lo script lo riceve in input["args"] come handle — i byte restano su
disco, non in memoria. Il modulo files opera su quell'handle:
from api_manager import files
def main(input):
f = input["args"]["ficheiro"] # l'handle dell'upload
texto = files.read_text(f) # str (utf-8)
dados = files.read(f) # bytes
caminho = files.path(f) # percorso assoluto su disco
files.save(f, "ultimo-recebido.csv") # copia nella cartella dello script
return {"nome": f["filename"], "tamanho": f["size"]}
L'handle porta filename, mimeType e size — utili per convalidare prima di
elaborare.
secrets — segreti dell'app
Token e chiavi si conservano nella pagina Secrets dell'app (albero laterale, gruppo App), cifrati. Lo script li legge tramite la chiave:
from api_manager import secrets
token = secrets.get("STRIPE_KEY") # -> str | None
if token is None:
raise RuntimeError("Secret STRIPE_KEY non configurato in questa app.")
Il valore viene decifrato sul server, nel momento dell'esecuzione — non compare mai nel browser né resta nel codice.

Attenzione
Non fare log(token). I log restano nella cronologia delle esecuzioni — un
segreto scritto in un log ha smesso di essere un segreto.
notify — notifiche ed email
L'app ha due canali fissi — uno in-app e uno di email — attivabili nelle
impostazioni di Notifiche dell'app (è lì che vive la configurazione SMTP e il
mittente). users sono username di utenti dell'app; roles si espandono a
tutti i membri del ruolo.
In-app, in tempo reale:
from api_manager import notify
r = notify.send(
"Report pronto",
subtitle="Report mensili",
body="Il report mensile è disponibile.",
users=["joao"],
roles=None,
data={"url": "/relatorios/42"},
)
# r = {"recipients": int, "delivered": int}
delivered conta quelli consegnati in tempo reale, a chi è collegato; i restanti
restano nella posta in arrivo e li ricevono al momento dell'accesso.
Email:
r = notify.email(
"Avviso di stock",
to=["chefe@empresa.pt"], # indirizzi liberi
users=None,
roles=["admin"], # e/o utenti e ruoli dell'app
text="Stock sotto il minimo.",
html=None,
)
# r = {"accepted": [emails], "skipped": [username senza email]}
L'invio SMTP avviene in modo asincrono sul server — lo script non resta in
attesa. attachments accetta allegati con il contenuto in base64 (vedi reports
qui sotto per il caso tipico).
workflow — i processi dell'app
Uno script può avviare un processo, svegliare chi sta aspettando un evento, e
decidere attività umane. Il processo si richiama per nome (o tramite
l'identificatore stabile); key è la chiave del record su cui viene eseguito:
from api_manager import workflow
r = workflow.start("Approvazione spesa", 42, data={"valor": 1200})
# r = {"instanceId": int}
r = workflow.signal("visto", key=42)
# r = {"woken": int}
abertas = workflow.tasks("joao")
# attività aperte di quell'utente dell'app, con le decisioni possibili
r = workflow.complete(task=17, outcome="aprovar", as_user="joao",
data={"nota": "ok"})
# r = {"ok": bool}
Regole che contano:
workflow.startrestituisce appena il motore arriva alla prima attesa — non aspetta mai che il processo finisca.workflow.signalsenzakeysveglia tutti i processi fermi su quell'evento;{"woken": 0}non è un errore — può non esserci nessuno in attesa.- In
workflow.complete,as_userè obbligatorio (chi decide resta nella cronologia) e l'attività deve essere assegnata a quell'utente. I valori dioutcomesono le uscite del nodo dell'attività — gli stessi che la persona vede come pulsanti. Non inventare nomi.
users — gli account dell'app
Uno script crea e modifica gli account dell'app e assegna loro ruoli che
esistono già. I ruoli e i permessi si creano nel costruttore; il modulo non
li crea né li modifica. user è l'id (numero) o lo username (testo)
dell'account:
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") # l'account, o None
users.list(role="vendedor") # senza gli account disattivati
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")
Regole che contano:
- Le regole sono quelle del costruttore e della registrazione pubblica:
username da 3 a 120 caratteri (lettere, numeri, punto, trattino,
_e@), email valida, password da 8 a 200 caratteri, e username ed email liberi, anche l'uno rispetto all'altra. - Gli account arrivano allo script senza la password. Senza
password, l'account entra solo dopo che qualcuno gliene ha impostata una. users.updatecambia solo i campi indicati, eemail=Nonecancella l'email.users.listinclude gli account disattivati coninclude_disabled=True.- Le modifiche valgono subito: un account disattivato perde l'accesso alla
richiesta successiva, e
set_passwordchiude le sessioni aperte dell'account. - Ogni modifica finisce nell'audit, con chi ha fatto girare lo script e il nome dello script.
- Chiama
passwordl'argomento della password: la cronologia Esecuzioni nasconde gli argomenti con quel nome.
Un errore solleva users.Error, con un code stabile: invalid_username, invalid_email, invalid_name, weak_password, username_taken, email_taken, unknown_role, not_found o
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, "errore": "Questo username esiste già."}
raise
return {"ok": True, "id": u["id"]}
reports — generare i report dell'app
Il documento viene generato sul server, con i dati dell'app, a partire da un report esistente:
from api_manager import notify, reports
r = reports.render("Fatture del mese", {"mes": "2026-03"})
# r = {"filename", "pages", "format", "mime", "bytes", "base64"}
notify.email(
"Fatture di marzo",
to=["financeiro@empresa.pt"],
text="In allegato.",
attachments=[{"filename": r["filename"], "content": r["base64"]}],
)
Il terzo argomento opzionale è il formato: "pdf" (predefinito) o "xlsx". I
parametri sono quelli che il report dichiara. Nel risultato, bytes arriva
pronto da salvare su disco e base64 pronto da allegare a un'email.
Uno script gira senza nessuno con una sessione: reports.render e i verbi di
workflow leggono e scrivono i dati come l'app stessa, con tutte le API
attive, sia in una pianificazione sia in Esegui ora.
ai — i modelli di IA dell'app
Gli script interrogano i modelli di IA che l'app ha configurato in Modelli di IA, con il nome dell'alias. Le chiavi dei fornitori restano sul server e lo script non le vede mai:
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)}
| Funzione | Restituisce |
|---|---|
ai.chat(prompt, ...) |
Un dict con text, stop_reason, usage, model, provider e alias. |
ai.json(prompt, schema=..., ...) |
Il JSON della risposta, già validato rispetto allo schema. |
ai.embed(testi) |
Un vettore per testo (una lista di numeri). |
ai.models() |
Gli alias dell'app, con l'uso e il modello di ciascuno. |
ai.run(prompt, tools=[...], ...) |
La risposta finale di un compito in cui il modello usa funzioni dello script, con i passi. |
ai.image(prompt, ...) |
Le immagini generate, già salvate nell'app. |
ai.transcribe(file, ...) |
Il testo di una registrazione. |
ai.speak(testo, ...) |
L'audio della voce, già salvato nell'app. |
ai.batch.submit(richieste, ...) |
L'id di un lotto elaborato in background; ai.batch.get, ai.batch.results e ai.batch.cancel lo seguono. |
I parametri, i file, i codici di errore e i limiti sono in Usare l'IA negli script, Strumenti e lotti e Immagini e audio.
Un esempio completo
Sulla falsariga dello script atualizar_indicadores dell'app Gestione
Clienti — legge il pipeline, scrive log utili e avvisa quando ci sono chiusure
vicine:
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"], "opportunità /", abertas["total"], "EUR")
if fechos:
notify.send(
"Chiusure di questa settimana",
body=f"{len(fechos)} opportunità con chiusura prevista entro {limite}.",
roles=["comercial"],
)
return {
"oportunidades_abertas": abertas["n"],
"valor_pipeline": abertas["total"],
"fechos_proximos_7_dias": len(fechos),
}
Limiti e buone pratiche
- Il risultato di
maindeve essere serializzabile in JSON; massimo 32 MB. - Ogni esecuzione rispetta il Limite di tempo dello script (da 30 secondi a 10 minuti) — al superamento, il processo viene terminato e resta Timeout.
- Le esecuzioni sono isolate: non dipendere da variabili di un'esecuzione precedente. Persisti in file della cartella dello script o in un datasource.
- Fai
log(...)a ogni fase rilevante — è quello che leggerai quando qualcosa fallirà alle 7:00 di una domenica. - Intercetta gli errori recuperabili e registrali; lascia salire quelli fatali — un'eccezione non gestita segna l'esecuzione come Errore, ed è questo che vuoi vedere nella cronologia quando qualcosa va davvero male.
- Non stampare segreti, e leggili sempre da
secrets— non scriverli mai nel codice.
Domande frequenti
from api_manager import db fallisce sul mio computer.
È previsto: il modulo api_manager esiste solo in esecuzione sulla
piattaforma — è lì che viene iniettato. Nell'editor hai il completamento
automatico completo dell'SDK; il file api_manager.py che vedi nella cartella
dello script esiste solo per quello.
db("nome") dice che il datasource non esiste.
Il nome deve essere esattamente quello del datasource nell'app (es.: Dados CRM, con le maiuscole e lo spazio). Guarda l'elenco nella sezione
Datasource dell'albero.
notify.email ha restituito accepted ma l'email non è arrivata.
L'invio SMTP è asincrono — accepted significa che l'email è passata al canale
email dell'app. Controlla la configurazione SMTP nelle impostazioni di
Notifiche dell'app e la casella di spam del destinatario.
Posso usare l'SDK nella convalida di una finestra?
Sì — la convalida viene eseguita nello stesso ambiente dello script principale,
con lo stesso input e lo stesso SDK. Vedi Pianificazioni.